storage

type Backend ¶

type Backend interface {
	// Capabilities returns the immutable guarantees supported by this adapter.
	Capabilities() Capabilities
	// Put streams the borrowed source into a complete publication and reports its mutation
	// outcome on failure.
	Put(context.Context, ObjectKey, io.Reader, PutOptions) (ObjectInfo, error)
	// Open returns metadata and an owned reader for the selected object span; callers must
	// close any returned reader.
	Open(context.Context, ObjectKey, ReadOptions) (io.ReadCloser, ReadInfo, error)
	// Stat returns complete metadata for the selected object version.
	Stat(context.Context, ObjectKey, ReadOptions) (ObjectInfo, error)
	// Delete removes the selected object; an unconditional deletion of an absent object
	// succeeds.
	Delete(context.Context, ObjectKey, DeleteOptions) error
	// List returns a bounded page of objects and supported child prefixes, excluding
	// staging data.
	List(context.Context, ListOptions) (Page, error)
}

Backend implementations stream with bounded buffers and preserve cancellation. Put never closes its caller-owned source. A blocked uncooperative source may delay cancellation; capacity remains owned until the actual call exits. Open transfers a reader whose Close is safe concurrently with Read and interrupts it where supported. A reader returned alongside an error must still be closed.

Each successful mutation must be fully published. Errors classify whether it was unchanged, applied or uncertain; adapters never blindly retry mutations. Complete metadata and object bytes must describe the same version. Delete is idempotent only when unconditional; a missing conditional target conflicts. List is bounded and not a transactional snapshot. Never return directories, upload fragments or internal metadata as objects; entries that cannot be represented as framework objects are skipped and counted in Page.Skipped. Backend lifetime is borrowed by Disk: close the Disk and wait for Done before closing its adapter.

type BatchDeleter ¶

type BatchDeleter interface {
	// DeleteBatch unconditionally deletes keys and returns aligned per-key results or a
	// call-level failure.
	DeleteBatch(ctx context.Context, keys []ObjectKey) ([]error, error)
}

BatchDeleter deletes several keys unconditionally in one provider request. Results align with keys; nil means deleted or already absent. A call-level error means the batch outcome is unknown for every key without a result.

type ByteRange ¶

type ByteRange struct{ Offset, Length int64 }

ByteRange requests up to Length bytes from Offset. The returned range is clipped at EOF. An empty object or starting beyond EOF is unsatisfiable.

func (r ByteRange) Resolve(size int64) (offset, length int64, err error)

func (r ByteRange) Validate() error

type Capabilities ¶

type Capabilities struct {
	// RequiresNFCKeys restricts object keys, namespaces and listing prefixes to
	// Unicode NFC. Adapters reject other spellings; they never normalize input
	// into another object's identity. Local storage and AWS do not require NFC.
	RequiresNFCKeys    bool
	Ranges             bool
	ConditionalRead    bool
	ConditionalCreate  bool
	ConditionalReplace bool
	ConditionalDelete  bool
	Versions           bool
	// ConditionalVersionDelete permits IfMatch together with an explicit Version
	// on Delete. Providers that evaluate a delete condition against the current
	// object (AWS) leave it false: an explicit immutable Version already selects
	// exactly one object, so callers delete by Version alone.
	ConditionalVersionDelete bool
	// DelimitedList supports one-level ListOptions.Delimited listings that
	// report child prefixes as Page.Directories.
	DelimitedList bool
	// ObjectMetadata supports the optional PutOptions.Metadata fields (cache
	// and presentation headers, custom metadata, storage class, encryption key).
	ObjectMetadata bool
	// ConditionalWriteMaxBytes, when positive, requires a declared Size within
	// this bound for conditional creates/replacements. Zero adds no size limit.
	ConditionalWriteMaxBytes int64
}

Capabilities are immutable adapter guarantees. Unsupported options must fail before consuming a source or mutating data; no option may be silently ignored. Individual flags describe single options; the combination flags below make provider limits on combined selectors explicit. ValidatePut, ValidateRead and ValidateDelete are the shared checks used by Disk and adapters alike.

func (c Capabilities) ValidateDelete(options DeleteOptions) error

func (c Capabilities) ValidateList(options ListOptions) error

func (c Capabilities) ValidatePut(options PutOptions) error

func (c Capabilities) ValidateRead(options ReadOptions) error

type CleanupID ¶

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

CleanupID identifies provider cleanup work (for example a multipart upload). It is opaque diagnostic data; ordinary formatting deliberately hides it.

func NewCleanupID(text string) CleanupID

func (CleanupID) Format(s fmt.State, _ rune)

func (id CleanupID) Value() string

type Code ¶

type Code string

Code is comparable with errors.Is; provider causes are retained but redacted.

const (
	NotFound            Code = "storage_not_found"
	Forbidden           Code = "storage_forbidden"
	Unsupported         Code = "storage_unsupported"
	PreconditionFailed  Code = "storage_precondition_failed"
	RangeNotSatisfiable Code = "storage_range_not_satisfiable"
	LimitExceeded       Code = "storage_limit_exceeded"
	Invalid             Code = "storage_invalid"
	Unavailable         Code = "storage_unavailable"
	IntegrityFailed     Code = "storage_integrity_failed"
	Closed              Code = "storage_closed"
)

func (c Code) Error() string

type Config ¶

type Config struct {
	Visibility        Visibility
	MaxObjectBytes    int64
	MaxActive         int
	Timeout           time.Duration
	MaxStreams        int
	StreamIdleTimeout time.Duration
}

Config bounds one disk. MaxActive and Timeout apply to metadata and write operations (Put, Stat, Delete, List, signing) and to opening a read stream. An open read stream uses a separate MaxStreams pool and remains open while it makes progress: StreamIdleTimeout cancels it only after no read progress for that long, so a slow client download is neither cut off by Timeout nor able to exhaust write capacity. Capacity waits are queued (at most min(Timeout, 5s)) and then fail as retryable overload (fault.Overloaded). Zero MaxStreams or StreamIdleTimeout selects its default.

func DefaultConfig() Config

func (c Config) Validate() error

type CopyOptions ¶

type CopyOptions struct {
	Source      ReadOptions
	Destination PutOptions
}

CopyOptions reads one complete source version and publishes a destination. Destination metadata defaults to the source's media type, exact size and available checksum. Conditions remain explicit. Copies between disks sharing one ServerCopier adapter run inside the provider; other copies stream with the adapters' bounded buffers. Neither buffers the entire object.

type Cursor ¶

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

Cursor is an opaque provider continuation. Copy it only from the returned page; it is tied to that disk/prefix, and never grants object authorization.

func NewCursor(text string) Cursor

func (c Cursor) IsZero() bool

func (c Cursor) Token() string

type Declaration ¶

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

Declaration is a reusable typed disk descriptor. IDs are explicit, not guessed from default configuration. Separate domain concerns should declare disks once.

func DefineDisk(id DiskID) Declaration

func (d Declaration) Bind(backend Backend, config Config) (*Disk, error)

func (d Declaration) ID() DiskID

func (d Declaration) Resolve(registry *Registry) (*Disk, error)

func (d Declaration) Validate() error

type DeleteFailure ¶

type DeleteFailure struct {
	Key ObjectKey
	Err error
}

DeleteFailure is one key a batch did not delete; Err is a classified *Error whose Outcome distinguishes unchanged from uncertain deletion.

type DeleteManyResult ¶

type DeleteManyResult struct {
	Deleted []ObjectKey
	Failed  []DeleteFailure
}

DeleteManyResult separates successfully deleted keys from classified per-key failures.

type DeleteOptions ¶

type DeleteOptions struct {
	IfMatch ETag
	Version VersionID
}

DeleteOptions selects an optional validator or immutable version for deletion.

func (o DeleteOptions) Validate() error

type DeletePrefixOptions ¶

type DeletePrefixOptions struct {
	Prefix Prefix
	Cursor Cursor
	Limit  int
}

DeletePrefixOptions selects one bounded page below a nonempty prefix.

type DeletePrefixResult ¶

type DeletePrefixResult struct {
	DeleteManyResult
	Skipped int
	Next    Cursor
}

DeletePrefixResult reports one page. Skipped entries (foreign or oversized objects) are never deleted. Continue with Next until it is zero.

type Disk ¶

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

Disk owns bounded operations and returned readers, borrowing its backend. Metadata/write operations and open read streams use separate queued admission pools. Close cancels work and closes readers; Done waits for their actual release. Close the backend only afterward. Construction performs no storage I/O.

func NewDisk(id DiskID, backend Backend, config Config) (*Disk, error)

func (d *Disk) Capabilities() Capabilities

func (d *Disk) Close(ctx context.Context) error

func (d *Disk) Config() Config

func (d *Disk) CopyTo(ctx context.Context, source ObjectKey, destination *Disk, target ObjectKey, options CopyOptions) (StoredObject, error)

func (d *Disk) Delete(ctx context.Context, key ObjectKey, options DeleteOptions) error

func (d *Disk) DeleteMany(ctx context.Context, keys []ObjectKey) (DeleteManyResult, error)

func (d *Disk) DeletePrefix(ctx context.Context, options DeletePrefixOptions) (DeletePrefixResult, error)

func (d *Disk) Done() <-chan struct{}

func (d *Disk) Exists(ctx context.Context, key ObjectKey) (bool, error)

func (d *Disk) ID() DiskID

func (d *Disk) List(ctx context.Context, options ListOptions) (Page, error)

func (d *Disk) MoveTo(ctx context.Context, source ObjectKey, destination *Disk, target ObjectKey, options CopyOptions) (MoveResult, error)

func (d *Disk) Open(ctx context.Context, key ObjectKey, options ReadOptions) (io.ReadCloser, ReadInfo, error)

func (d *Disk) OpenSeek(ctx context.Context, key ObjectKey, options ReadOptions) (io.ReadSeekCloser, ObjectInfo, error)

func (d *Disk) PublicURL(ctx context.Context, key ObjectKey) (string, error)

func (d *Disk) Put(ctx context.Context, key ObjectKey, source io.Reader, options PutOptions) (StoredObject, error)

func (d *Disk) PutBytes(ctx context.Context, key ObjectKey, data []byte, options PutOptions) (StoredObject, error)

func (d *Disk) PutFile(ctx context.Context, key ObjectKey, path string, options PutOptions) (StoredObject, error)

func (d *Disk) ReadBytes(ctx context.Context, key ObjectKey, maximum int64, options ReadOptions) ([]byte, ReadInfo, error)

func (d *Disk) Stat(ctx context.Context, key ObjectKey, options ReadOptions) (ObjectInfo, error)

func (d *Disk) Stats() Stats

func (d *Disk) TemporaryURL(ctx context.Context, key ObjectKey, options LinkOptions) (TemporaryURL, error)

func (d *Disk) TemporaryUploadForm(ctx context.Context, key ObjectKey, options UploadFormOptions) (UploadForm, error)

func (d *Disk) TemporaryUploadURL(ctx context.Context, key ObjectKey, options UploadLinkOptions) (UploadLink, error)

func (d *Disk) Validate() error

type DiskID ¶

type DiskID string

DiskID is an explicit registered disk, not an object key or filesystem path.

func (d DiskID) Validate() error

type ETag ¶

type ETag string

ETag is an opaque strong object validator, including its quotes. It is not assumed to be an MD5 or other content digest. Zero means no validator.

func (t ETag) Validate() error

type Error ¶

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

Error retains a storage classification, operation, mutation outcome and redacted cause.

func Failure(code Code, op Operation, outcome Outcome, cause error) *Error

func (e *Error) Cleanup() value.Optional[CleanupID]

func (e *Error) Code() Code

func (e *Error) Error() string

func (e *Error) Format(s fmt.State, _ rune)

func (e *Error) Is(target error) bool

func (e *Error) LogValue() slog.Value

func (e *Error) Operation() Operation

func (e *Error) Outcome() Outcome

func (e *Error) Unwrap() error

func (e *Error) WithCleanup(id CleanupID) *Error

type FormField ¶

type FormField struct{ Name, Value string }

FormField is one signed form value. Submit every field unchanged, then the file content last in the field named by UploadForm.FileField.

type LinkOptions ¶

type LinkOptions struct {
	ExpiresIn                  time.Duration
	Version                    VersionID
	ResponseContentType        MediaType
	ResponseContentDisposition string
}

LinkOptions bounds one signed read. ResponseContentType and ResponseContentDisposition are signed provider response overrides (for example to force a download filename); use RFC 8187 encoding for non-ASCII filenames. They never change stored object metadata.

func (o LinkOptions) Validate() error

type ListOptions ¶

type ListOptions struct {
	Prefix    Prefix
	Cursor    Cursor
	Limit     int
	Delimited bool
}

ListOptions selects one bounded page. Delimited lists a single level below Prefix: objects without a further "/" after Prefix and each distinct child prefix ending in "/" (reported once in Page.Directories). It requires Capabilities.DelimitedList. Limit bounds objects and directories together.

func (o ListOptions) Validate() error

type MediaType ¶

type MediaType string

MediaType is stored object metadata, not proof of a validated file format.

const Binary MediaType = "application/octet-stream"

func (m MediaType) Validate() error

type MoveResult ¶

type MoveResult struct {
	Destination        value.Optional[StoredObject]
	DestinationOutcome Outcome
	SourceOutcome      Outcome
}

MoveResult records the two separately committed effects. A failed move can retain a complete Destination. SourceOutcome distinguishes a preserved source from an applied or uncertain deletion. Never automatically compensate by deleting Destination: another writer might already have replaced it.

type ObjectAddress ¶

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

ObjectAddress identifies a provider object independently of disk names and namespace aliases. Adapters use a stable store identity and the complete key. It is opaque operational metadata, not a URL, authorization token or DB ID.

func NewObjectAddress(store, object string) (ObjectAddress, error)

func (ObjectAddress) Format(s fmt.State, _ rune)

type ObjectInfo ¶

type ObjectInfo struct {
	Key         ObjectKey
	Size        int64
	ContentType MediaType
	Modified    temporal.DateTime
	ETag        ETag
	Version     VersionID
	Checksum    value.Optional[SHA256]
}

ObjectInfo describes a complete object. Checksum is a full-object SHA-256 when available; do not compare it to the bytes of a partial ranged read.

func (i ObjectInfo) Validate() error

func (i ObjectInfo) ValidateListed() error

type ObjectKey ¶

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

ObjectKey is a validated, case-sensitive UTF-8 object name. It is never a filesystem path or URL. Parsing rejects traversal and ambiguous separators; it never cleans, case-folds, percent-decodes or Unicode-normalizes a key.

func ParseKey(text string) (ObjectKey, error)

func (k ObjectKey) IsZero() bool

func (ObjectKey) JSONContract() contract.JSON[ObjectKey]

func (k ObjectKey) MarshalJSON() ([]byte, error)

func (k ObjectKey) MarshalText() ([]byte, error)

func (k ObjectKey) String() string

func (k *ObjectKey) UnmarshalJSON(data []byte) error

func (k *ObjectKey) UnmarshalText(text []byte) error

func (k ObjectKey) Validate() error

type ObjectLocator ¶

type ObjectLocator interface {
	// Locate returns the physical object identity without performing I/O.
	Locate(ObjectKey) (ObjectAddress, error)
}

ObjectLocator lets safe moves reject aliases of the same physical object. Locate performs no I/O. Return the same store identity across adapter instances for the same store, and account for Namespace in the complete object key.

type ObjectMetadata ¶

type ObjectMetadata struct {
	CacheControl       string
	ContentDisposition string
	ContentEncoding    string
	StorageClass       StorageClass
	EncryptionKey      string
	Custom             map[string]string
}

ObjectMetadata is optional per-object provider metadata. Header values are printable ASCII; use RFC 8187 encoding for non-ASCII Content-Disposition filenames. Custom names are lowercase letters, digits and '-' and must not use the reserved "foundry-" prefix. EncryptionKey selects a provider-managed SSE-KMS key identifier; it is an identifier, never key material. Metadata is written with the object; listings and Stat do not echo it back.

func (m ObjectMetadata) Clone() ObjectMetadata

func (m ObjectMetadata) IsZero() bool

func (m ObjectMetadata) Validate() error

type Operation ¶

type Operation string

Operation identifies the storage action associated with a failure.

const (
	PutOperation    Operation = "put"
	OpenOperation   Operation = "open"
	StatOperation   Operation = "stat"
	DeleteOperation Operation = "delete"
	ListOperation   Operation = "list"
	CopyOperation   Operation = "copy"
	MoveOperation   Operation = "move"
	SignOperation   Operation = "sign"
	CloseOperation  Operation = "close"
)

type Outcome ¶

type Outcome uint8

Outcome describes visibility of a mutation, not an instruction to retry. Applied errors can follow successful publication but failed cleanup/durability. Unknown means the caller must reconcile; no automatic mutation retry is safe.

const (
	NotApplicable Outcome = iota
	Unchanged
	Applied
	Unknown
)

type Page ¶

type Page struct {
	Objects     []ObjectInfo
	Directories []Prefix
	Skipped     int
	Next        Cursor
}

Page is one listing page. Listed objects carry key, size, modification time, ETag and version from the provider listing; ContentType and Checksum are zero when the listing does not report them (S3). Use Stat for complete metadata. Skipped counts provider entries under the prefix that are not representable framework objects (foreign or unparsable keys, entries beyond the object size limit, entries without validators); they never fail a page.

type Prefix ¶

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

Prefix selects an exact lexical prefix, not a directory or a normalized path. Zero means every object. A trailing slash is allowed for directory-like use.

func ParsePrefix(text string) (Prefix, error)

func (p Prefix) Contains(key ObjectKey) bool

func (p Prefix) String() string

func (p Prefix) Validate() error

type PublicBase ¶

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

PublicBase is an explicitly configured public bucket/CDN root. It is not inferred from an authenticated API endpoint and does not make a bucket public. Object keys are encoded once as literal path text, including percent signs. A literal '+' is encoded as %2B because some CDNs and S3-compatible servers decode a path '+' as a space.

func ParsePublicBase(address string) (PublicBase, error)

func (b PublicBase) IsZero() bool

func (b PublicBase) URL(key ObjectKey) (string, error)

type PutOptions ¶

type PutOptions struct {
	ContentType MediaType
	Size        value.Optional[int64]
	Checksum    value.Optional[SHA256]
	Condition   WriteCondition
	// Metadata is optional provider object metadata. Adapters without
	// Capabilities.ObjectMetadata reject a nonzero value before consuming input.
	Metadata ObjectMetadata
}

PutOptions declares publication metadata, optional exact size and checksum, and write conditions.

func (o PutOptions) Validate(maximum int64) error

type ReadInfo ¶

type ReadInfo struct {
	Object         ObjectInfo
	Offset, Length int64
}

ReadInfo separates the complete object's metadata from the returned byte span.

type ReadOptions ¶

type ReadOptions struct {
	Range   value.Optional[ByteRange]
	IfMatch ETag
	Version VersionID
}

ReadOptions selects an optional byte range, validator and immutable object version.

func (o ReadOptions) Validate() error

type Registry ¶

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

Registry is immutable and borrows its disks. The lifecycle owner closes each disk before its backend. Registry construction and resolution perform no I/O.

func NewDefaultRegistry(selected DiskID, disks ...*Disk) (*Registry, error)

func NewRegistry(disks ...*Disk) (*Registry, error)

func (r *Registry) Default() (*Disk, error)

func (r *Registry) DefaultName() DiskID

func (r *Registry) Disk(id DiskID) (*Disk, error)

func (r *Registry) Disks() []DiskID

type SHA256 ¶

type SHA256 [32]byte

SHA256 is a full-object SHA-256 digest.

func ParseSHA256(text string) (SHA256, error)

func (s SHA256) String() string

type ServerCopier ¶

type ServerCopier interface {
	// Copy publishes a complete destination within the adapter using the supplied
	// selectors and size bound.
	Copy(ctx context.Context, source, target ObjectKey, options CopyOptions, maximum int64) (ObjectInfo, error)
}

ServerCopier copies within one adapter without streaming bytes through this process (for example S3 CopyObject or a local kernel-assisted file copy). It honors the same source pins, destination condition and declared size/checksum as a streamed copy, and writes the metadata a streamed copy writes: the destination's content type (the source's by default), the source's recorded full checksum and options.Destination.Metadata, never other source metadata such as cache or custom headers. A source larger than maximum (the smaller of both disks' MaxObjectBytes) fails with LimitExceeded and an Unchanged outcome before any mutation. When a request needs the streamed path, it returns Unsupported with an Unchanged outcome before any provider mutation.

type SignedFormProvider ¶

type SignedFormProvider interface {
	// TemporaryUploadForm returns a signed bearer form constrained by options.
	TemporaryUploadForm(context.Context, ObjectKey, UploadFormOptions) (UploadForm, error)
}

SignedFormProvider presigns a browser form upload (an HTML POST policy).

type SignedURLProvider ¶

type SignedURLProvider interface {
	// TemporaryURL returns a signed read URL constrained by options.
	TemporaryURL(context.Context, ObjectKey, LinkOptions) (TemporaryURL, error)
}

SignedURLProvider produces a read-only bearer URL. A URL remains usable until expiry/credential revocation even if the framework disk subsequently closes.

type SignedUploadProvider ¶

type SignedUploadProvider interface {
	// TemporaryUploadURL returns a signed bearer PUT request constrained by options.
	TemporaryUploadURL(context.Context, ObjectKey, UploadLinkOptions) (UploadLink, error)
}

SignedUploadProvider produces a presigned single-request upload. The exact size, media type, optional checksum metadata and optional absence condition are signed; the client must send UploadLink.Headers unchanged.

type Stats ¶

type Stats struct {
	Active  int
	Streams int
	Closing bool
}

Stats reports admitted work. Active counts operations and open streams; Streams is the subset holding MaxStreams slots.

type StorageClass ¶

type StorageClass string

StorageClass is a provider storage tier such as STANDARD or STANDARD_IA. It is passed to the provider verbatim; zero selects the bucket default.

type StoredObject ¶

type StoredObject struct {
	Disk   DiskID
	Object ObjectInfo
}

StoredObject pairs an object description with its registered disk identifier.

type TemporaryURL ¶

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

TemporaryURL deliberately redacts formatting and rejects implicit JSON. Explicitly call URL when returning a link in an authorized response DTO. ExpiresAt is an upper bound: revoked/expired credentials may invalidate it sooner.

func NewTemporaryURL(address string, expires time.Time) (TemporaryURL, error)

func (u TemporaryURL) ExpiresAt() time.Time

func (TemporaryURL) Format(s fmt.State, _ rune)

func (TemporaryURL) LogValue() slog.Value

func (TemporaryURL) MarshalJSON() ([]byte, error)

func (TemporaryURL) String() string

func (u TemporaryURL) URL() string

type URLProvider ¶

type URLProvider interface {
	// PublicURL returns the configured stable public address for key.
	PublicURL(context.Context, ObjectKey) (string, error)
}

URLProvider supplies stable public addresses without changing provider access policies.

type UploadForm ¶

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

UploadForm is a signed bearer form upload. Formatting redacts it and implicit JSON fails; explicitly return URL, Fields and FileField in an authorized response DTO. The object is written by the browser, not by this process: confirm it with Stat (and its checksum) before relying on it.

func NewUploadForm(address string, fields []FormField, expires time.Time) (UploadForm, error)

func (f UploadForm) ExpiresAt() time.Time

func (f UploadForm) Fields() []FormField

func (UploadForm) FileField() string

func (UploadForm) Format(s fmt.State, _ rune)

func (UploadForm) LogValue() slog.Value

func (UploadForm) MarshalJSON() ([]byte, error)

func (UploadForm) String() string

func (f UploadForm) URL() string

type UploadFormOptions ¶

type UploadFormOptions struct {
	ExpiresIn        time.Duration
	ContentType      MediaType
	MinSize, MaxSize int64
	Checksum         value.Optional[SHA256]
}

UploadFormOptions constrains a direct browser form upload. The object key and ContentType are exact and the uploaded size must lie within [MinSize, MaxSize] (a signed content-length-range). Checksum, when set, is recorded as the object's full SHA-256 metadata; the provider does not verify it, but complete framework reads do. Form uploads take no write condition.

func (o UploadFormOptions) Validate(maximum int64) error

type UploadLink ¶

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

UploadLink is a signed bearer upload request. Formatting redacts it and implicit JSON fails; explicitly return URL, Method and Headers in an authorized response DTO. The object is written by the client, not by this process: confirm it with Stat (and its checksum) before relying on it.

func NewUploadLink(address, method string, headers http.Header, expires time.Time) (UploadLink, error)

func (l UploadLink) ExpiresAt() time.Time

func (UploadLink) Format(s fmt.State, _ rune)

func (l UploadLink) Headers() http.Header

func (UploadLink) LogValue() slog.Value

func (UploadLink) MarshalJSON() ([]byte, error)

func (l UploadLink) Method() string

func (UploadLink) String() string

func (l UploadLink) URL() string

type UploadLinkOptions ¶

type UploadLinkOptions struct {
	ExpiresIn   time.Duration
	ContentType MediaType
	Size        int64
	Checksum    value.Optional[SHA256]
	Condition   WriteCondition
}

UploadLinkOptions describes a direct client upload. ContentType and Size are required and exact; Size must be at least one byte (a zero length is not signed, so an empty link would accept any size). Checksum is recorded as the object's full SHA-256 metadata; the provider does not verify it, but complete framework reads do. Condition supports IfAbsent only where the disk supports conditional create.

func (o UploadLinkOptions) Validate(maximum int64) error

type VersionID ¶

type VersionID string

VersionID selects an immutable provider object version. A local generation validator is an ETag, not a promise that previous versions remain readable.

func (v VersionID) Validate() error

type Visibility ¶

type Visibility uint8

Visibility is access intent. Foundry never changes object ACLs/bucket policy. Private disks reject stable public URLs even if their adapter has a CDN base.

const (
	Private Visibility = iota
	Public
)

type WriteCondition ¶

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

WriteCondition declares an atomic publication precondition; zero permits unconditional writes.

func IfAbsent() WriteCondition

func IfMatch(tag ETag) (WriteCondition, error)

func (c WriteCondition) Match() ETag

func (c WriteCondition) RequiresAbsence() bool