artifact

type Accessor interface {
	// Path returns the local file path of a staged input. It returns an
	// empty string for an input that was not declared, was not bound, or
	// was declared lazy.
	Path(name string) string

	// Open streams an input's bytes. It works for both staging modes:
	// a path-staged input reads from local disk, a lazy one from the
	// backend.
	Open(ctx context.Context, name string) (io.ReadCloser, error)

	// Ref returns the artifact bound to an input.
	Ref(name string) (Ref, bool)

	// Create begins writing an output owned by the running job. Outputs
	// are imperative rather than declared so a handler can produce a
	// number of them it only discovers at run time.
	Create(ctx context.Context, name string, opts ...CreateOption) (*CommitWriter, error)

	// Existing returns an artifact a previous attempt committed under this
	// name, letting a retried handler skip work it already did.
	Existing(ctx context.Context, name string) (Ref, bool)
}

type Artifact struct {
	ID          id.ArtifactID `json:"id"`
	Backend     string        `json:"backend"`
	Bucket      string        `json:"bucket"`
	Key         string        `json:"key"`
	Size        int64         `json:"size"`
	ContentHash string        `json:"content_hash,omitempty"`
	ContentType string        `json:"content_type,omitempty"`
	Lifecycle   Lifecycle     `json:"lifecycle"`
	ScopeAppID  string        `json:"scope_app_id,omitempty"`
	ScopeOrgID  string        `json:"scope_org_id,omitempty"`
	ExpiresAt   *time.Time    `json:"expires_at,omitempty"`
	CreatedAt   time.Time     `json:"created_at"`
	DeletedAt   *time.Time    `json:"deleted_at,omitempty"`
}

type Backend interface {
	// Name returns the backend's identifier, recorded in Artifact.Backend.
	Name() string

	// Open returns a reader over the object's bytes. It returns
	// ErrNotFound if the object does not exist.
	Open(ctx context.Context, ref Ref) (io.ReadCloser, error)

	// Create begins writing a new object. The bytes are not visible until
	// Commit. Callers must call Commit or Abort.
	Create(ctx context.Context, bucket, key string) (Writer, error)

	// Stat reports the object's size and content type without reading it.
	// It returns ErrNotFound if the object does not exist.
	Stat(ctx context.Context, ref Ref) (ObjectInfo, error)

	// Delete removes the object. Deleting a missing object is not an error.
	Delete(ctx context.Context, ref Ref) error
}

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

type CreateOption func(*CreateOptions)

type CreateOptions struct {
	ContentType string
	ScopeAppID  string
	ScopeOrgID  string
	Retention   time.Duration
	IfAbsent    bool
}

type InputOption func(*InputSpec)

type InputSpec struct {
	// Name identifies the input in the handler and in bindings.
	Name string
	// Required fails the job when no binding is supplied.
	Required bool
	// MaxSize rejects an oversized binding at enqueue. Zero means no limit.
	MaxSize int64
	// Mode selects staging behaviour.
	Mode StageMode
}

type Lifecycle string

type Link struct {
	ArtifactID id.ArtifactID `json:"artifact_id"`
	OwnerKind  OwnerKind     `json:"owner_kind"`
	OwnerID    string        `json:"owner_id"`
	Role       Role          `json:"role"`
	Name       string        `json:"name"`
	Attempt    int           `json:"attempt"`
	CreatedAt  time.Time     `json:"created_at"`
}

type ListOpts struct {
	// Limit is the maximum number of artifacts to return. Zero means no limit.
	Limit int
	// Offset is the number of artifacts to skip.
	Offset int
	// Lifecycle filters by lifecycle. Empty means all.
	Lifecycle Lifecycle
	// ScopeAppID filters by tenant application. Empty means all.
	ScopeAppID string
	// ScopeOrgID filters by tenant organization. Empty means all.
	ScopeOrgID string
	// IncludeDeleted includes soft-deleted artifacts. Default false.
	IncludeDeleted bool
}

type ObjectInfo struct {
	Size        int64
	ContentType string
	ETag        string
}

type OwnerKind string

type OwnerRef struct {
	Kind OwnerKind
	ID   string
}

type Page struct {
	Artifacts  []*Artifact
	NextCursor string
	Complete   bool
}

type PageLister interface {
	ListArtifactsPage(ctx context.Context, opts PageOpts) (Page, error)
}

type PageOpts struct {
	Lifecycle      Lifecycle
	ScopeAppID     string
	ScopeOrgID     string
	IncludeDeleted bool
	Cursor         string
	Limit          int
}

type PresignSupport interface{ SupportsPresign(ref Ref) bool }

type Presigner interface {
	// PresignGet returns a time-limited URL granting read access.
	PresignGet(ctx context.Context, ref Ref, ttl time.Duration) (string, error)
}

type RangeReader interface {
	// OpenRange returns a reader over n bytes starting at off. A negative
	// n reads to the end.
	OpenRange(ctx context.Context, ref Ref, off, n int64) (io.ReadCloser, error)
}

type RecordReader interface {
	GetArtifactRecord(ctx context.Context, artifactID id.ArtifactID) (*Artifact, error)
}

type Ref struct {
	ID          id.ArtifactID `json:"id"`
	Backend     string        `json:"backend"`
	Bucket      string        `json:"bucket"`
	Key         string        `json:"key"`
	Size        int64         `json:"size"`
	ContentHash string        `json:"content_hash,omitempty"`
}

type RegisterOption func(*RegisterOptions)

type RegisterOptions struct {
	ScopeAppID  string
	ScopeOrgID  string
	ContentType string
}

type Role string

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

type ServiceOption func(*Service)

type StageMode int

type Store interface {
	// CreateArtifact inserts an artifact and, when link is non-nil, its
	// first link atomically. Returns ErrExists if an artifact already
	// exists at the same backend, bucket, and key.
	CreateArtifact(ctx context.Context, a *Artifact, link *Link) error

	// GetArtifact retrieves an artifact by ID. Returns ErrNotFound if it
	// does not exist or has been soft-deleted.
	GetArtifact(ctx context.Context, artifactID id.ArtifactID) (*Artifact, error)

	// FindArtifactByKey retrieves an artifact by its storage coordinates.
	// Returns ErrNotFound if none exists.
	FindArtifactByKey(ctx context.Context, backend, bucket, key string) (*Artifact, error)

	// UpdateArtifact persists changes to size, content hash, content type,
	// and expiry. It must not permit changing lifecycle.
	UpdateArtifact(ctx context.Context, a *Artifact) error

	// ListArtifacts returns artifacts matching the given options.
	ListArtifacts(ctx context.Context, opts ListOpts) ([]*Artifact, error)

	// LinkArtifact records that an owner references an artifact. Linking
	// the same artifact, owner, name, and attempt twice is a no-op rather
	// than an error.
	LinkArtifact(ctx context.Context, link *Link) error

	// ListLinks returns every link belonging to the given owner.
	ListLinks(ctx context.Context, owner OwnerRef) ([]*Link, error)

	// FindLinkByName returns the link for an owner and name with the
	// highest attempt number, breaking ties by CreatedAt descending so
	// resolution is deterministic and favours the later writer. This is
	// what IfAbsent uses to detect that a prior attempt already produced
	// an output. Returns ErrNotFound if no attempt has produced it.
	//
	// Ties happen: track D's lease reclaim increments EvictCount, never
	// RetryCount, so a reclaimed (zombie) holder and the worker it was
	// fenced out for can both commit a link at the same (OwnerKind,
	// OwnerID, Name, Attempt) — CreateFenced closes the storage-key
	// collision between them, but nothing stops two Link rows with
	// different ArtifactIDs at the identical tuple. The CreatedAt
	// tie-break is the cheap half of the fix: it makes which of the two
	// wins deterministic instead of backend-dependent map/query order.
	// The complete fix — carrying the fence token on Link itself, so the
	// zombie's write is rejected rather than merely outrun — is a schema
	// change across all five backends and remains open.
	FindLinkByName(ctx context.Context, owner OwnerRef, name string) (*Link, error)

	// ListArtifactsByOwner returns the artifacts linked to an owner,
	// optionally filtered by role. An empty role returns all.
	ListArtifactsByOwner(ctx context.Context, owner OwnerRef, role Role) ([]*Artifact, error)

	// SweepEphemeral marks eligible ephemeral artifacts as deleted and
	// returns them.
	SweepEphemeral(ctx context.Context, opts SweepOpts) ([]*Artifact, error)

	// SweepOrphans marks ephemeral artifacts that have no links at all and
	// were created before the cutoff.
	SweepOrphans(ctx context.Context, cutoff time.Time, limit int) ([]*Artifact, error)

	// ListPurgeable returns soft-deleted artifacts whose deletion is older
	// than grace, so their bytes may be removed from the backend.
	ListPurgeable(ctx context.Context, grace time.Duration, limit int) ([]*Artifact, error)

	// PurgeArtifact hard-deletes an artifact row and its links after the
	// bytes have been removed from the backend.
	PurgeArtifact(ctx context.Context, artifactID id.ArtifactID) error
}

type SweepOpts struct {
	// Retention is the grace period after the last owner reaches a
	// terminal state before an artifact becomes eligible.
	Retention time.Duration
	// Limit caps how many artifacts a single sweep call may mark.
	// Zero means no limit.
	Limit int
	// DryRun computes eligibility and returns the artifacts that would be
	// marked without modifying anything.
	DryRun bool
}

type Writer interface {
	io.Writer

	// Commit finalises the object and returns its logical info.
	Commit(ctx context.Context) (ObjectInfo, error)

	// Abort discards the partial object. It is a no-op after Commit.
	Abort() error
}