// Package storage provides an abstraction layer for file content persistence.
package storage

import (
	"context"
	"io"
)

// StorageBackend abstracts where file content is written, read, and deleted.
// Paths passed to all methods are relative to the backend's root and must
// not contain path traversal sequences.
type StorageBackend interface {
	// Save writes the contents of reader to path, creating parent directories
	// as needed. It returns the number of bytes written.
	Save(ctx context.Context, path string, reader io.Reader) (int64, error)

	// Open returns a reader for the file at path. The caller must close the
	// returned ReadCloser.
	Open(ctx context.Context, path string) (io.ReadCloser, error)

	// Delete removes the file at path. It is idempotent — deleting a
	// non-existent file is not an error.
	Delete(ctx context.Context, path string) error
}