Documentation
¶
Overview ¶
Package upload is the client upload path of the files subsystem (SYN-27): spool → tier decision (inline / BIND dedup / full) → encrypt → UnixFS DAG → local CARv2 → register the payloads row → enqueue the durable phase.
Add never touches the network: the durable phase (presigned PUT + receipt-verified RequestSign against the fileV2 broker) belongs to the drive-toward-durable queue, which calls DriveDurable. A file whose durable phase fails (quota, offline) stays registered with local bytes and is retried by the queue.
Index ¶
Constants ¶
const KindDurable = "durable"
KindDurable is the drive-toward-durable job kind (mirrors the queue package constant; declared here so upload does not import it).
Variables ¶
var ErrLimited = errors.New("fileupload: storage limit exceeded")
ErrLimited — the broker refused backup (storage limit). The file is registered and locally available; it is not durable.
Functions ¶
This section is empty.
Types ¶
type AddOpts ¶
type AddOpts struct {
Name string
Mime string
// Variant/VariantOf tag this file as an alternate representation
// (e.g. a thumbnail) of an existing file. Validated by the caller
// (spaceimpl) — this layer just seals them.
Variant string
VariantOf string
}
AddOpts carries caller metadata for one file. All fields ride in the sealed (member-only) part of the row.
type Broker ¶
type Broker interface {
Upload(ctx context.Context, spaceId string, items []*fileprotov2.UploadRequestItem) (*fileprotov2.UploadResponse, error)
Put(ctx context.Context, up *fileprotov2.PresignedUpload, body io.Reader, size int64) error
RequestSign(ctx context.Context, spaceId string, rootCids [][]byte) (*fileprotov2.RequestSignResponse, error)
VerifyReceipt(rcpt *fileprotov2.NetworkSignReceipt, spaceId string, root cid.Cid, objectSize uint64) (string, error)
}
Broker is the durable-phase seam (implemented by broker.Client; faked in tests).
type Enqueuer ¶
Enqueuer is the persistent-queue seam: every unsigned row gets a durable job, and the queue's worker runs the durable phase. Nil = no queue (tests).
type RegisterOpts ¶
type RegisterOpts struct {
RootCid string
Size int64
NetworkSign string
Enc payloads.EncPayload
}
RegisterOpts mirrors the payloads registration input.
type Registrar ¶
type Registrar interface {
RegisterFile(ctx context.Context, ownerId string, opts RegisterOpts) (fileId string, err error)
SetNetworkSign(ctx context.Context, ownerId, fileId, sign string) error
Row(ctx context.Context, ownerId, fileId string) (payloads.Row, error)
// FindRow resolves a row by fileId alone (space-wide), a deleted
// derived owner's row included: its receipt still covers the root.
FindRow(ctx context.Context, fileId string) (payloads.Row, error)
}
Registrar is the per-space payloads write surface (implemented over spaceimpl.PayloadsAPI; faked in tests). RegisterFile returns a *payloads.NotWrittenError when it wrote no row.
type Result ¶
type Result struct {
FileId string
RootCid string // empty for inline
Size int64 // plaintext bytes
Inline bool
Durable bool
// Bound: the content matched an already-registered file (per-space
// dedup); the new row reuses its rootCid, key and receipt.
Bound bool
}
Result reports one completed Add.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the upload orchestrator. One per SDK.
func (*Service) Add ¶
func (s *Service) Add(ctx context.Context, reg Registrar, spaceId, ownerId string, r io.Reader, opts AddOpts) (Result, error)
Add ingests r as a file bound to ownerId in spaceId: registers the payloads row and, for the S3 tier, lands the CARv2 locally and enqueues the durable phase. Add is local-only and never waits on the network; Result.Durable is true only for an inline file or one bound to an already durable donor.
func (*Service) DriveDurable ¶
func (s *Service) DriveDurable(ctx context.Context, reg Registrar, spaceId, ownerId, fileId string) error
DriveDurable drives an already registered row to a verified receipt (the queue worker path). Transport failures return at once — the queue owns that backoff; only the broker's activation-window codes are retried here. No-op when the row is already durable or inline; a row whose content another row already backed up takes that receipt without an upload; ErrLimited on a limit refusal.
Source Files