Janady13/missionmatch / internal/platform/storage/storage.go

1// Package storage is the cloud agnostic object store port for retained payloads (raw feed records 2// today, resumes and exports later). The interface keeps the core app free of any cloud SDK: a local 3// filesystem store backs development and the offline demo, and an S3 compatible store (MinIO, AWS 4// GovCloud S3, or Azure Blob behind the same shape) is wired at deploy. Choosing a backend is 5// configuration, not code (the cloud portability mandate). No payload key is ever trusted blindly: 6// every key is validated so a crafted source id can never write outside the store root. 7package storage 8 9import ( 10 "context" 11 "crypto/sha256" 12 "encoding/hex" 13 "errors" 14 "fmt" 15 "os" 16 "path" 17 "path/filepath" 18 "strings" 19 "sync" 20) 21 22// ErrNotFound is returned by Get when the key has no object. 23var ErrNotFound = errors.New("storage: object not found") 24 25// Storer is the minimal object store contract. Keys are forward slash separated logical paths; an 26// implementation maps them to its own layout (a directory tree for local, an object prefix for S3). 27// Implementations MUST reject any key that would escape their root. 28type Storer interface { 29 Put(ctx context.Context, key string, data []byte) error 30 Get(ctx context.Context, key string) ([]byte, error) 31 Exists(ctx context.Context, key string) (bool, error) 32 Delete(ctx context.Context, key string) error 33} 34 35// SHA256Hex returns the lowercase hex sha256 of data, used as the integrity stamp on a stored payload. 36func SHA256Hex(data []byte) string { 37 sum := sha256.Sum256(data) 38 return hex.EncodeToString(sum[:]) 39} 40 41// cleanKey validates a logical key and returns its slash separated clean form. It rejects an empty 42// key, an absolute key, and any key that climbs above the root, so a source supplied id can never 43// traverse out of the store. 44func cleanKey(key string) (string, error) { 45 k := strings.TrimSpace(key) 46 if k == "" { 47 return "", errors.New("storage: empty key") 48 } 49 if strings.HasPrefix(k, "/") { 50 return "", fmt.Errorf("storage: absolute key not allowed: %q", key) 51 } 52 cleaned := path.Clean(k) 53 if cleaned == "." || cleaned == ".." || strings.HasPrefix(cleaned, "../") { 54 return "", fmt.Errorf("storage: key escapes root: %q", key) 55 } 56 return cleaned, nil 57} 58 59// LocalStore is a filesystem backed Storer rooted at a single directory. It is the default for 60// development and the offline demo. Writes are atomic (temp file then rename) so a crashed sync never 61// leaves a half written payload. 62type LocalStore struct{ root string } 63 64// NewLocal builds a LocalStore, creating the root directory if it does not exist. 65func NewLocal(root string) (*LocalStore, error) { 66 r := strings.TrimSpace(root) 67 if r == "" { 68 return nil, errors.New("storage: local root is required") 69 } 70 abs, err := filepath.Abs(r) 71 if err != nil { 72 return nil, fmt.Errorf("storage: resolve root: %w", err) 73 } 74 if err := os.MkdirAll(abs, 0o750); err != nil { 75 return nil, fmt.Errorf("storage: create root: %w", err) 76 } 77 return &LocalStore{root: abs}, nil 78} 79 80func (s *LocalStore) pathFor(key string) (string, error) { 81 cleaned, err := cleanKey(key) 82 if err != nil { 83 return "", err 84 } 85 full := filepath.Join(s.root, filepath.FromSlash(cleaned)) 86 // Defense in depth: even after cleaning, confirm the resolved path stays under the root. 87 if full != s.root && !strings.HasPrefix(full, s.root+string(os.PathSeparator)) { 88 return "", fmt.Errorf("storage: key escapes root: %q", key) 89 } 90 return full, nil 91} 92 93// Put writes data at key, creating parent directories as needed. The write is atomic. 94func (s *LocalStore) Put(_ context.Context, key string, data []byte) error { 95 full, err := s.pathFor(key) 96 if err != nil { 97 return err 98 } 99 if err := os.MkdirAll(filepath.Dir(full), 0o750); err != nil { 100 return fmt.Errorf("storage: mkdir: %w", err) 101 } 102 tmp := full + ".tmp" 103 if err := os.WriteFile(tmp, data, 0o640); err != nil { 104 return fmt.Errorf("storage: write: %w", err) 105 } 106 if err := os.Rename(tmp, full); err != nil { 107 _ = os.Remove(tmp) 108 return fmt.Errorf("storage: rename: %w", err) 109 } 110 return nil 111} 112 113// Get reads the object at key, returning ErrNotFound when it is absent. 114func (s *LocalStore) Get(_ context.Context, key string) ([]byte, error) { 115 full, err := s.pathFor(key) 116 if err != nil { 117 return nil, err 118 } 119 b, err := os.ReadFile(full) 120 if errors.Is(err, os.ErrNotExist) { 121 return nil, ErrNotFound 122 } 123 if err != nil { 124 return nil, fmt.Errorf("storage: read: %w", err) 125 } 126 return b, nil 127} 128 129// Exists reports whether an object is present at key. 130func (s *LocalStore) Exists(_ context.Context, key string) (bool, error) { 131 full, err := s.pathFor(key) 132 if err != nil { 133 return false, err 134 } 135 _, err = os.Stat(full) 136 if errors.Is(err, os.ErrNotExist) { 137 return false, nil 138 } 139 if err != nil { 140 return false, fmt.Errorf("storage: stat: %w", err) 141 } 142 return true, nil 143} 144 145// Delete removes the object at key. A missing object is not an error. 146func (s *LocalStore) Delete(_ context.Context, key string) error { 147 full, err := s.pathFor(key) 148 if err != nil { 149 return err 150 } 151 if err := os.Remove(full); err != nil && !errors.Is(err, os.ErrNotExist) { 152 return fmt.Errorf("storage: delete: %w", err) 153 } 154 return nil 155} 156 157// MemoryStore is an in memory Storer for tests. It enforces the same key validation as LocalStore. 158type MemoryStore struct { 159 mu sync.RWMutex 160 m map[string][]byte 161} 162 163// NewMemory builds an empty in memory store. 164func NewMemory() *MemoryStore { return &MemoryStore{m: map[string][]byte{}} } 165 166func (s *MemoryStore) Put(_ context.Context, key string, data []byte) error { 167 cleaned, err := cleanKey(key) 168 if err != nil { 169 return err 170 } 171 cp := make([]byte, len(data)) 172 copy(cp, data) 173 s.mu.Lock() 174 s.m[cleaned] = cp 175 s.mu.Unlock() 176 return nil 177} 178 179func (s *MemoryStore) Get(_ context.Context, key string) ([]byte, error) { 180 cleaned, err := cleanKey(key) 181 if err != nil { 182 return nil, err 183 } 184 s.mu.RLock() 185 v, ok := s.m[cleaned] 186 s.mu.RUnlock() 187 if !ok { 188 return nil, ErrNotFound 189 } 190 cp := make([]byte, len(v)) 191 copy(cp, v) 192 return cp, nil 193} 194 195func (s *MemoryStore) Exists(_ context.Context, key string) (bool, error) { 196 cleaned, err := cleanKey(key) 197 if err != nil { 198 return false, err 199 } 200 s.mu.RLock() 201 _, ok := s.m[cleaned] 202 s.mu.RUnlock() 203 return ok, nil 204} 205 206func (s *MemoryStore) Delete(_ context.Context, key string) error { 207 cleaned, err := cleanKey(key) 208 if err != nil { 209 return err 210 } 211 s.mu.Lock() 212 delete(s.m, cleaned) 213 s.mu.Unlock() 214 return nil 215} 216