upload

type Config struct {
	// MaxFileSize is the maximum allowed file size in bytes.
	// Default: 10MB.
	MaxFileSize int64

	// AllowedTypes is a list of allowed MIME types.
	// If empty, all types are allowed.
	AllowedTypes []string

	// AllowedExtensions is a list of allowed filename extensions (e.g. ".png", "jpg").
	// If empty, all extensions are allowed.
	AllowedExtensions []string

	// RequireExtensionMatch rejects uploads whose filename extension does not match the detected MIME type.
	// This is an optional defense-in-depth check to avoid content-type/extension confusion.
	RequireExtensionMatch bool

	// TempExpiry is how long temp files live before cleanup.
	// Default: 1 hour.
	TempExpiry time.Duration
}

type DiskStore struct {
	// contains filtered or unexported fields
}

type File struct {
	// ID is the unique identifier for this upload.
	ID string

	// Filename is a compatibility alias for SafeFilename.
	// It is always normalized by the framework and never contains raw client input.
	Filename string

	// OriginalFilename is the raw filename from the client upload request.
	// Treat this as untrusted input.
	OriginalFilename string

	// SafeFilename is the normalized filename produced by NormalizeFilename.
	SafeFilename string

	// ContentType is the MIME type of the file.
	ContentType string

	// Size is the file size in bytes.
	Size int64

	// Path is the local filesystem path (for DiskStore).
	Path string

	// URL is the remote URL (for S3/CDN storage).
	URL string

	// Reader provides access to the file contents.
	// May be nil if the file is stored on disk (use Path instead).
	Reader io.ReadCloser
}

type SaveRequest struct {
	// OriginalFilename is the raw filename provided by the client.
	// This value is untrusted and must never be used directly in security-sensitive contexts.
	OriginalFilename string

	// SafeFilename is framework-normalized and safe for headers, logs, and storage keys.
	SafeFilename string

	// ContentType is the server-detected MIME type of the upload.
	ContentType string

	// Size is the client-reported size in bytes.
	Size int64

	// Request is the incoming HTTP request that produced this upload.
	// It is optional and may be nil for direct Store.Save calls in tests/tools.
	Request *http.Request

	// Context is the request context associated with this upload.
	// It is optional and may be nil for direct Store.Save calls in tests/tools.
	Context context.Context
}

type Store interface {
	// Save stores the uploaded file and returns a temp ID.
	// The file is stored temporarily until Claim is called.
	// Implementations must consume r synchronously and must not retain it after Save returns.
	// HandlerWithConfig cleans up multipart temp files at the end of the request.
	Save(req SaveRequest, r io.Reader) (tempID string, err error)

	// Claim retrieves and removes a temp file, returning a file handle.
	// After claiming, the temp file is deleted (or marked for deletion).
	// Implementations should populate OriginalFilename and SafeFilename when available.
	Claim(tempID string) (*File, error)

	// Cleanup removes expired temp files.
	// Call this periodically (e.g., every 5 minutes).
	Cleanup(maxAge time.Duration) error
}