Documentation
¶
Overview ¶
Package upload implements the backend-neutral, instance-owned core file store.
Index ¶
- Constants
- type Config
- type UploadReadLease
- type UploadStore
- func (s *UploadStore) AcquireReadLease(ctx context.Context, principal runtime.InstancePrincipal, ...) (*UploadReadLease, error)
- func (s *UploadStore) CleanupInstance(ctx context.Context, p runtime.InstancePrincipal) error
- func (s *UploadStore) Close(ctx context.Context) error
- func (s *UploadStore) Delete(ctx context.Context, p runtime.InstancePrincipal, ref *wire.UploadedFileRef) error
- func (s *UploadStore) LastCleanupError() error
- func (s *UploadStore) RegistrarFactory(services runtime.InstanceServices) (core.HelperRegistrar, error)
- func (s *UploadStore) Sweep(ctx context.Context) error
Constants ¶
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
ManagementDirectory string
Limits runtime.Limits
// ModuleMountRoots lists every trusted host subtree exposed to modules.
// Roots must already exist; lexical and resolved overlap both fail closed.
ModuleMountRoots []string
}
Config deliberately has no defaults for the five operator-required upload limits. The supervisor provisions ManagementDirectory/uploads as a private, runtime-owned 0700 child outside every module mount. The management parent may remain root-owned and grant only trusted runtime-group traversal.
type UploadReadLease ¶
type UploadReadLease struct {
// contains filtered or unexported fields
}
UploadReadLease pins one immutable upload for a single admitted outbound operation. Deletion/expiry prevent new leases but do not cancel this lease. Cancellation closes readers; the owning backend joins its multipart/HTTP workers before calling Release. Instance cleanup joins forced releases.
func (*UploadReadLease) Context ¶
func (l *UploadReadLease) Context() context.Context
Context is bounded by both the actual admission and outbound operation. Use it for HTTP and multipart workers so instance stop cancels the complete operation.
func (*UploadReadLease) Open ¶
func (l *UploadReadLease) Open(ctx context.Context) (io.ReadCloser, error)
Open returns a fresh offset-zero reader. Every reader must be closed before Release can complete. A shorter per-attempt context also cancels that reader.
func (*UploadReadLease) Reference ¶
func (l *UploadReadLease) Reference() *wire.UploadedFileRef
Reference returns a fresh validated metadata copy, never a filesystem path.
func (*UploadReadLease) Release ¶
func (l *UploadReadLease) Release() error
Release prevents further Open calls, waits for all owned readers to close, and drops the storage pin exactly once. It does not cancel admitted readers. Cancellation/stop instead close readers through the lease's context callback.
type UploadStore ¶
type UploadStore struct {
// contains filtered or unexported fields
}
UploadStore owns all reservation and retirement state under a single lock. Byte charges and record entries are released independently, only after actual unlink and, for entries, the original deletion retention window have ended.
func New ¶
func New(ctx context.Context, config Config) (*UploadStore, error)
New verifies and exclusively claims the existing supervisor-provisioned ManagementDirectory/uploads child, then reclaims its old internal spool files. It never recovers references from an earlier runtime.
func (*UploadStore) AcquireReadLease ¶
func (s *UploadStore) AcquireReadLease(ctx context.Context, principal runtime.InstancePrincipal, ref *wire.UploadedFileRef) (*UploadReadLease, error)
AcquireReadLease requires an actual runtime operation admission in ctx and a finite outbound-operation deadline. Metadata is checked against the stored owner, exact size/name/MIME and original expiry; none is used as authority.
func (*UploadStore) CleanupInstance ¶
func (s *UploadStore) CleanupInstance(ctx context.Context, p runtime.InstancePrincipal) error
CleanupInstance is runtime.ManagerOptions.FileCleanup. It denies new work, cancels and joins writers/readers, drops retention, and reclaims actual bytes. A deadline or unlink failure keeps the ownership lock and all remaining charges so the manager can fail closed and retry rather than declaring reclamation.
func (*UploadStore) Close ¶
func (s *UploadStore) Close(ctx context.Context) error
Close cancels all instances and releases exclusive directory ownership only after every worker and actual spool file has been reclaimed. Retry on failure. The composition must stop/join backend operations before closing the store.
func (*UploadStore) Delete ¶
func (s *UploadStore) Delete(ctx context.Context, p runtime.InstancePrincipal, ref *wire.UploadedFileRef) error
Delete prevents new reads. Already admitted leases remain usable until their own operation deadline. A successful unlink retains an owner-checked tombstone until the original expiration, even for zero-byte files.
func (*UploadStore) LastCleanupError ¶
func (s *UploadStore) LastCleanupError() error
LastCleanupError returns a fixed, structured diagnostic, never a filesystem path or underlying OS error. A failure remains observable after later retries.
func (*UploadStore) RegistrarFactory ¶
func (s *UploadStore) RegistrarFactory(services runtime.InstanceServices) (core.HelperRegistrar, error)
RegistrarFactory is runtime.ManagerOptions.FileTransfer. It captures the real instance Authorizer, never a metadata identity. Construct one shared store per runtime; host quotas and the ownership lock must not be split among instances.