Documentation
¶
Overview ¶
Package upload owns request-scoped temporary files behind typed HTTP handles.
Index ¶
- type Batch
- func (b *Batch) Capture(ctx context.Context, source io.Reader, name, declaredType string) (File, error)
- func (b *Batch) CaptureFrom(ctx context.Context, name string, produce func(io.Writer) (string, error)) (result File, err error)
- func (b *Batch) CleanupComplete() bool
- func (b *Batch) Close() error
- func (b *Batch) RetryCleanup() error
- type CleanupError
- type Config
- type File
- func (f File) ClientContentType() string
- func (f File) ContentType() string
- func (f File) Extension() string
- func (File) GoString() string
- func (f File) IsZero() bool
- func (File) MarshalJSON() ([]byte, error)
- func (f File) Name() string
- func (f File) Open(ctx context.Context) (io.ReadSeekCloser, error)
- func (f File) SHA256() [sha256.Size]byte
- func (f File) Size() int64
- func (File) String() string
- type Limit
- type LimitError
- type Pool
- func (p *Pool) Claim() error
- func (p *Pool) ClaimExclusive() error
- func (p *Pool) Close() error
- func (p *Pool) Directory() string
- func (p *Pool) MaxBytes() int64
- func (p *Pool) Reserve(ctx context.Context, bytes int64) (*Reservation, error)
- func (p *Pool) RetryCleanup() error
- func (p *Pool) Usage() (active int, bytes int64)
- type PoolConfig
- type ReadError
- type Reader
- type Reservation
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Batch ¶
type Batch struct {
// contains filtered or unexported fields
}
Batch owns all temporary files and readers for one request. Close waits for active captures/reads, closes readers, and removes only owned files. No recursive deletion or client-provided path participates in cleanup.
func (*Batch) Capture ¶
func (b *Batch) Capture(ctx context.Context, source io.Reader, name, declaredType string) (File, error)
Capture consumes a borrowed reader with fixed scratch space. It never closes the source or uses its WriterTo method. Limits include failed capture attempts.
func (*Batch) CaptureFrom ¶ added in v0.30.0
func (b *Batch) CaptureFrom(ctx context.Context, name string, produce func(io.Writer) (string, error)) (result File, err error)
CaptureFrom lends a bounded writer to a synchronous producer, such as an HTTP download. The producer returns the untrusted media hint after successful EOF. The writer counts, hashes and sniffs exactly the bytes stored. It becomes closed before this call returns; ignored write failures cannot publish a partial File. The batch retains ownership until the producer and all admitted writes exit.
func (*Batch) CleanupComplete ¶ added in v0.30.0
CleanupComplete reports actual removal, independently of response/cancellation.
func (*Batch) RetryCleanup ¶ added in v0.30.0
RetryCleanup retries exact-file cleanup only after Close has drained work.
type CleanupError ¶
type CleanupError struct{ Cause error }
CleanupError reports a failed local cleanup rather than misclassifying an incoming reader failure as the complete outcome. The cause remains private.
func (*CleanupError) Error ¶
func (*CleanupError) Error() string
func (*CleanupError) Unwrap ¶
func (e *CleanupError) Unwrap() error
type Config ¶
Config bounds capture bytes, created files and concurrently open readers. Empty TempDirectory uses the operating system's temporary directory.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File is an opaque handle to a fully captured request-owned upload. Its zero value is absent. Metadata remains readable after cleanup; Open does not.
func (File) ClientContentType ¶
ClientContentType is untrusted metadata supplied by the client.
func (File) ContentType ¶
ContentType is the framework's bounded content sniff, not proof of a valid image/document.
func (File) MarshalJSON ¶
func (File) Open ¶
Open returns a new reader at offset zero. The caller closes it after use; request cleanup also closes retained readers. Neither the temporary filename nor an unrestricted os.File is exposed. Both contexts govern every operation.
type LimitError ¶
type LimitError struct{ Kind Limit }
func (*LimitError) Error ¶
func (*LimitError) Error() string
type Pool ¶ added in v0.30.0
type Pool struct {
// contains filtered or unexported fields
}
Pool owns one directory and a fail-fast reservation budget. Close only after all borrowers exit; retained cleanup can be retried without admitting work.
func NewPool ¶ added in v0.30.0
func NewPool(config PoolConfig) (*Pool, error)
func (*Pool) Claim ¶ added in v0.31.0
Claim enables reservations for a manually managed lifetime. Repeated calls on the same pool are idempotent; they do not transfer ownership.
func (*Pool) ClaimExclusive ¶ added in v0.31.0
ClaimExclusive acquires a new server lifetime or refuses an existing owner, including another server or manual Claim on this same pool object.
func (*Pool) Close ¶ added in v0.30.0
Close seals admission. Active work or failed cleanup retains the marker so another process cannot treat occupied storage as a fresh budget.
func (*Pool) RetryCleanup ¶ added in v0.30.0
RetryCleanup removes only batch-owned files. A failed batch conservatively retains its entire encoded-body reservation, including metadata headroom.
type PoolConfig ¶ added in v0.30.0
PoolConfig reserves capture slots and bytes independently of downstream work. Directory must be a private, writable directory on a quota-controlled volume. Claim reconciles captures left by a dead owner before enabling reservations.
func (PoolConfig) Validate ¶ added in v0.30.0
func (c PoolConfig) Validate() error
type ReadError ¶
type ReadError struct{ Cause error }
ReadError distinguishes failed incoming bytes from local filesystem failures. Error formatting never invokes the underlying reader's error methods.
type Reservation ¶ added in v0.30.0
type Reservation struct {
// contains filtered or unexported fields
}
Reservation is held until its owner exits, even after cancellation. Attach its batch before capture. Release closes it before returning capacity.
func (*Reservation) Attach ¶ added in v0.30.0
func (r *Reservation) Attach(batch *Batch) error
Attach binds exactly one bounded capture to the reservation before reading.
func (*Reservation) Release ¶ added in v0.30.0
func (r *Reservation) Release()
type Source ¶
type Source interface {
Open(context.Context) (io.ReadSeekCloser, error)
Name() string
ClientContentType() string
}
Source is the shared structural contract for a captured file that a feature can open. The caller owns the file; each operation closes the reader it opens. Name and ClientContentType are untrusted display/type hints.
Source Files