Go API

Import github.com/chester-hill-solutions/stow-s3/pkg/stow. Use Runtime for objects and Workspace for editable directories and checkpoints.

Defaults and limits

Behavior

• Pass a context to operations for cancellation.
• Check Capabilities before optional operations.
• ETag conditions compare content; ReadForSave/SaveObject also detect managed metadata and generation changes.
• Save results distinguish SaveCommitted, SaveNotCommitted and SaveUnknown.
• Persist request keys before durable saves or captures.
• Resolve uncertain results before retrying.
• Close preserves durable data; Destroy is a separate authorized operation.
• Workspace embeds Runtime and inherits its object methods.
• Store extensions advertise conditional, staged, streaming, range and multipart support independently.

Errors

• Use errors.Is for sentinel errors and errors.As for structured errors.
• ErrPreconditionFailed and ErrSaveConflict preserve current data.
• ErrMutationCommitted means content was published despite a later index error; inspect the returned object before retrying.
• ErrSaveRequestUnknown and SaveUnknown require resolution.
• ErrQuotaExceeded bounds managed storage, not process memory or direct host writes.

Example

runtime, err := stow.Open(stow.Options{MaxBytes: 16 << 20, MaxObjects: 1000})
if err != nil { return err }
defer runtime.Close()
ctx := context.Background()
if err := runtime.CreateBucket(ctx, "files"); err != nil { return err }
object, err := runtime.PutObject(ctx, "files", "note.txt", []byte("hello"), stow.PutOptions{ContentType: "text/plain"})
if err != nil { return err }
_ = object

Symbols

AddRecoveryHold · AdoptHandoff · AdoptHandoffArchive · AllowAll · AllowNone · ApplyDelta · ApplyDeltaWithOptions · Authority · Backend · BackendFilesystem · BackendHost · BackendMemory · BackendWorkspace · Bucket · BucketCreate · BucketDelete · BucketList · Capabilities · CapacityHost · CapacityHostOptions · CapacityNamespace · CapacityNamespaceOptions · CapacitySnapshot · CaptureCheckpoint · CapturePrincipal · CheckpointArchiveOptions · CheckpointArchivePreview · CheckpointBucketChange · CheckpointChange · CheckpointError · CheckpointFile · CheckpointHold · CheckpointInfo · CheckpointManifest · CheckpointObject · CheckpointObjectChange · CheckpointOf · CheckpointOfAuthorized · CheckpointOptions · CheckpointProvenance · CheckpointRepository · CheckpointRequest · CheckpointResult · Collect · CollectOptions · CollectResult · CompareCheckpoints · ComparePortableCheckpoints · ConditionalWriteStore · CopyStore · CreateDelta · DecodeDelta · DefaultWorkspaceRegistryDir · DefaultWorkspaceRegistryDirForTeam · DeleteCheckpoint · DeltaChange · DeltaChangeAdded · DeltaChangeChanged · DeltaChangeDeleted · DeltaDocument · DeltaDocumentDigest · DeltaOptions · DeltaVersion · DestroyRegisteredWorkspace · DiscardRecoveryHold · EncodeDelta · EnvironmentDestroy · EnvironmentPromote · EnvironmentReset · ErrBucketExists · ErrBucketNotEmpty · ErrBucketNotFound · ErrCapacityConflict · ErrCapacityFull · ErrCapacityInvalid · ErrCapacityUnknown · ErrClosed · ErrConditionalWritesUnsupported · ErrDeltaConflict · ErrDeltaDigestMismatch · ErrDeltaTooLarge · ErrDeltaVersionUnsupported · ErrGuardedSavesUnsupported · ErrInvalidBucket · ErrInvalidKey · ErrInvalidListLimit · ErrInvalidRecoveryHold · ErrInvalidSaveCondition · ErrInvalidSaveRequest · ErrMutationCommitted · ErrNotAuthorized · ErrObjectNotFound · ErrPreconditionFailed · ErrQuotaExceeded · ErrRecoveryHeld · ErrRecoveryHoldConflict · ErrRecoveryHoldCorrupt · ErrRecoveryHoldFull · ErrRecoveryHoldNotFound · ErrRecoveryHoldsUnsupported · ErrSaveConflict · ErrSaveRequestConflict · ErrSaveRequestFull · ErrSaveRequestNotCommitted · ErrSaveRequestNotFound · ErrSaveRequestsUnsupported · ErrSaveRequestUnknown · ErrUnsupportedBackend · ExportCheckpoint · ExportHandoff · FilesystemOptions · GetRegistryPolicy · GitRepositoryInput · Handoff · HandoffArchive · HandoffError · HandoffExportOptions · ImportCheckpoint · ImportHandoff · List · ListOptions · ListRecoveryHolds · ListWorkspacesOptions · LoadCheckpoint · LookupWorkspace · MaxDeltaBytes · MaxRecoveryHoldBytes · MaxRecoveryHoldPeakBytes · MaxRecoveryHolds · MaxRecoveryReferences · MultipartOptions · MultipartStore · MultipartUpload · Object · ObjectDelete · ObjectList · ObjectPage · ObjectRange · ObjectRead · ObjectRecoveryHoldOptions · ObjectRecoveryReference · ObjectWrite · Open · OpenCapacityHost · OpenFilesystem · OpenWorkspace · Operation · Options · Part · PortableCheckpointDiff · PreparedRepository · PreparedWorkspace · PrepareOptions · PrepareWorkspace · PreviewCheckpointArchive · Prune · PruneOptions · PruneResult · PutOptions · RangeStore · ReadCheckpointFile · ReadHandoff · ReadHandoffReader · ReadOnly · ReadWrite · RecoveryHold · RecoveryHoldPage · RecoveryHoldQuery · RecoveryHoldRequest · RecoveryReference · RegistryPolicy · ReleaseRecoveryHold · ReplacementCondition · ResolveCheckpoint · ResolveRegistryDir · RestoreCheckpoint · RestoreCheckpointWithGit · Resume · ResumeIn · ResumeWith · Runtime · SaveCommitted · SaveCondition · SaveNotCommitted · SaveOptions · SaveOutcome · SaveResult · SaveUnknown · SetRegistryPolicy · StagedObject · StagedWriteStore · Store · StreamingStore · StreamingWriteStore · StreamPutOptions · UpstreamRead · UpstreamWrite · Usage · ValidateHandoff · VerifyDeltaDigest · Workspace · WorkspaceFacade · WorkspaceFacadeOptions · WorkspaceInput · WorkspaceListing · WorkspaceOptions · WorkspaceReference · WorkspaceSummary · WorkspaceTaskManifest

AddRecoveryHold

AddRecoveryHold is host administration over a trusted registry, not a grant from Owner.

func AddRecoveryHold(ctx context.Context, registryDir string, request RecoveryHoldRequest) (RecoveryHold, error)

Returns: RecoveryHold, error.

AdoptHandoff

AdoptHandoff returns imported checkpoint information even if restoration fails.

func AdoptHandoff(ctx context.Context, path string, options WorkspaceOptions, archiveOptions CheckpointArchiveOptions) (*Workspace, CheckpointInfo, error)

Returns: *Workspace, CheckpointInfo, error.

AdoptHandoffArchive

AdoptHandoffArchive consumes the checked document and opened archive without reopening paths.

func AdoptHandoffArchive(ctx context.Context, document Handoff, archive *os.File, options WorkspaceOptions, archiveOptions CheckpointArchiveOptions) (*Workspace, CheckpointInfo, error)

Returns: *Workspace, CheckpointInfo, error.

AllowAll

AllowAll returns an Authority that permits every operation.

func AllowAll() Authority

AllowNone

AllowNone returns an Authority that permits nothing.

func AllowNone() Authority

ApplyDelta

ApplyDelta brings a checkpoint to the state a delta describes, and returns the new checkpoint.

func ApplyDelta(ctx context.Context, registryDir, baseID string, delta *DeltaDocument) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

ApplyDeltaWithOptions

ApplyDeltaWithOptions applies a transported delta when the receiver explicitly consents to carrying sensitive-looking paths as well as the sender's consent.

func ApplyDeltaWithOptions(ctx context.Context, registryDir, baseID string, delta *DeltaDocument, options DeltaOptions) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

Authority

Authority is a set of permitted operations.

type Authority struct{ Mask uint32 }

Authority.Allows

Allows reports whether op is permitted.

func (a Authority) Allows(op Operation) bool

Returns: bool.

Authority.Check

Check returns *ErrNotAuthorized when op is not permitted.

func (a Authority) Check(op Operation) error

Returns: error.

Authority.Intersect

Intersect returns the operations both a and b permit.

func (a Authority) Intersect(b Authority) Authority

Returns: Authority.

Authority.IsSupersetOf

IsSupersetOf reports whether a permits everything b permits.

func (a Authority) IsSupersetOf(b Authority) bool

Returns: bool.

Authority.Operations

Operations lists what is permitted, sorted, for a descriptor or a diagnostic.

func (a Authority) Operations() []Operation

Returns: []Operation.

Authority.String

String renders the permitted set, for an error message or a log line.

func (a Authority) String() string

Returns: string.

Authority.With

With returns a copy that additionally permits the given operations.

func (a Authority) With(ops ...Operation) Authority

Returns: Authority.

Authority.Without

Without returns a copy that no longer permits the given operations.

func (a Authority) Without(ops ...Operation) Authority

Returns: Authority.

Backend

type Backend string

BackendFilesystem

const BackendFilesystem Backend = "filesystem"

BackendHost

const BackendHost Backend = "host"

BackendMemory

const BackendMemory Backend = "memory"

BackendWorkspace

const BackendWorkspace Backend = "workspace"

Bucket

type Bucket struct {
	Name		string
	CreationDate	time.Time
}

BucketCreate

const BucketCreate = authority.BucketCreate

BucketDelete

const BucketDelete = authority.BucketDelete

BucketList

const BucketList = authority.BucketList

Capabilities

Return the operations and limits supported by this handle.

type Capabilities struct {
	Backend			Backend
	MaxBytes		int64
	MaxObjects		int64
	MaxMultipartUploads	int64
	Persistent		bool
	Multipart		bool
	Upstream		bool
	ConditionalWrites	bool
	GuardedSaves		bool
	DurableSaveRequests	bool
	RecoveryHolds		bool
}

CapacityHost

CapacityHost configures trusted namespace budgets; it does not authenticate callers.

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

CapacityHost.BindNamespace

func (h *CapacityHost) BindNamespace(options CapacityNamespaceOptions) (*CapacityNamespace, error)

Returns: *CapacityNamespace, error.

CapacityHostOptions

type CapacityHostOptions struct {
	Dir		string
	MaxBytes	int64
	MaxNamespaces	int
}

CapacityNamespace

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

CapacityNamespace.Snapshot

func (n *CapacityNamespace) Snapshot(ctx context.Context) (CapacitySnapshot, error)

Returns: CapacitySnapshot, error.

CapacityNamespaceOptions

type CapacityNamespaceOptions struct {
	ID	string
	MaxBytes,
	RecoveryReserveBytes	int64
	MaxOperations, MaxDependencies	int
}

CapacitySnapshot

type CapacitySnapshot struct {
	PayloadBytes, RecoveryBytes, ReservedRecoveryBytes, PendingBytes	int64
	Operations								int
}

CaptureCheckpoint

Capture paused writers with a persisted unique request key. Replay retained results before admitting a new capture.

func CaptureCheckpoint(ctx context.Context, registryDir, workspaceID string, request CheckpointRequest) (CheckpointResult, error)

Returns: CheckpointResult, error.

CapturePrincipal

CapturePrincipal is what a capture from outside the workspace is decided by.

type CapturePrincipal struct {
	Environment	authority.Authority
	Policy		policy.Source
}

CheckpointArchiveOptions

CheckpointArchiveOptions bounds archive work.

type CheckpointArchiveOptions struct {
	MaxBytes		int64
	MaxFiles		int64
	IncludeSensitiveFiles	bool
}

CheckpointArchivePreview

CheckpointArchivePreview describes the verified contents of an archive.

type CheckpointArchivePreview struct {
	Version		int			`json:"version"`
	PrimaryBucket	string			`json:"primary_bucket,omitempty"`
	Buckets		[]string		`json:"buckets,omitempty"`
	Objects		[]CheckpointObject	`json:"objects,omitempty"`
	CheckpointID	string			`json:"checkpoint_id"`
	WorkspaceID	string			`json:"workspace_id"`
	ParentID	string			`json:"parent_checkpoint_id,omitempty"`
	Files		[]CheckpointFile	`json:"files"`
	Excluded	[]string		`json:"excluded_sensitive_paths,omitempty"`
	SensitivePaths	[]string		`json:"sensitive_paths,omitempty"`
	Bytes		int64			`json:"bytes"`
}

CheckpointBucketChange

type CheckpointBucketChange struct {
	Bucket	string	`json:"bucket"`
	Kind	string	`json:"kind"`
}

CheckpointChange

type CheckpointChange struct {
	Path	string		`json:"path"`
	Kind	string		`json:"kind"`
	From	*CheckpointFile	`json:"from,omitempty"`
	To	*CheckpointFile	`json:"to,omitempty"`
}

CheckpointError

type CheckpointError struct {
	Code		string	`json:"code"`
	Phase		string	`json:"phase"`
	Attempts	int	`json:"attempts"`
	Retryable	bool	`json:"retryable"`
	Outcome		string	`json:"outcome"`
	Err		error	`json:"-"`
}

CheckpointError.Error

func (e *CheckpointError) Error() string

Returns: string.

CheckpointError.Unwrap

func (e *CheckpointError) Unwrap() error

Returns: error.

CheckpointFile

type CheckpointFile struct {
	Path	string	`json:"path"`
	Size	int64	`json:"size"`
	Mode	uint32	`json:"mode"`
	SHA256	string	`json:"sha256"`
}

CheckpointHold

type CheckpointHold struct {
	ID		string		`json:"id"`
	Owner		string		`json:"owner"`
	ExpiresAt	time.Time	`json:"expires_at,omitempty"`
}

CheckpointInfo

type CheckpointInfo struct {
	Version		int		`json:"version,omitempty"`
	Objects		int64		`json:"objects,omitempty"`
	ID		string		`json:"id"`
	WorkspaceID	string		`json:"workspace_id"`
	ParentID	string		`json:"parent_id"`
	Created		time.Time	`json:"created"`
	Files		int64		`json:"files"`
	Bytes		int64		`json:"bytes"`
	Excluded	[]string	`json:"excluded"`
}

CheckpointManifest

type CheckpointManifest struct {
	Provenance		*CheckpointProvenance	`json:"provenance,omitempty"`
	PrimaryBucket		string			`json:"primary_bucket,omitempty"`
	Buckets			[]string		`json:"buckets,omitempty"`
	Objects			[]CheckpointObject	`json:"objects,omitempty"`
	Payloads		[]CheckpointFile	`json:"payloads,omitempty"`
	WorkingDirectory	string			`json:"working_directory,omitempty"`
	Version			int			`json:"version"`
	ID			string			`json:"id"`
	WorkspaceID		string			`json:"workspace_id"`
	ParentID		string			`json:"parent_id,omitempty"`
	Created			time.Time		`json:"created"`
	Files			[]CheckpointFile	`json:"files"`
	Excluded		[]string		`json:"excluded,omitempty"`
}

CheckpointObject

CheckpointObject describes logical object state, independent of backend paths.

type CheckpointObject struct {
	Bucket			string			`json:"bucket"`
	Key			string			`json:"key"`
	Payload			string			`json:"payload"`
	Size			int64			`json:"size"`
	SHA256			string			`json:"sha256"`
	ContentType		string			`json:"content_type"`
	Metadata		map[string]string	`json:"metadata,omitempty"`
	ChecksumAlgorithm	string			`json:"checksum_algorithm,omitempty"`
	ChecksumValue		string			`json:"checksum_value,omitempty"`
	ChecksumType		string			`json:"checksum_type,omitempty"`
}

CheckpointObjectChange

type CheckpointObjectChange struct {
	Bucket	string			`json:"bucket"`
	Key	string			`json:"key"`
	Kind	string			`json:"kind"`
	From	*CheckpointObject	`json:"from,omitempty"`
	To	*CheckpointObject	`json:"to,omitempty"`
}

CheckpointOf

CheckpointOf captures a checkpoint of a workspace that another process may be using right now: the operation an orchestrator needs and could not perform, since the answer to "what has it done so far?" must not require the agent to stop.

func CheckpointOf(ctx context.Context, registryDir, id string, options CheckpointOptions) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

CheckpointOfAuthorized

CheckpointOfAuthorized is CheckpointOf with its principal named.

func CheckpointOfAuthorized(ctx context.Context, registryDir, id string, options CheckpointOptions, principal CapturePrincipal) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

CheckpointOptions

type CheckpointOptions struct {
	PortableObjects		bool	`json:"portable_objects,omitempty"`
	ParentID		string	`json:"parent_id,omitempty"`
	MaxBytes		int64	`json:"max_bytes,omitempty"`
	MaxFiles		int64	`json:"max_files,omitempty"`
	IncludeSensitiveFiles	bool	`json:"include_sensitive_files,omitempty"`
}

CheckpointProvenance

type CheckpointProvenance struct {
	Repositories		[]CheckpointRepository	`json:"repositories,omitempty"`
	OriginCheckpointID	string			`json:"origin_checkpoint_id,omitempty"`
}

CheckpointRepository

type CheckpointRepository struct {
	Destination	string	`json:"destination"`
	Commit		string	`json:"commit"`
	SourceLabel	string	`json:"source_label,omitempty"`
}

CheckpointRequest

type CheckpointRequest struct {
	Hold	*CheckpointHold		`json:"hold,omitempty"`
	Key	string			`json:"request_key"`
	Options	CheckpointOptions	`json:"options"`
}

CheckpointResult

type CheckpointResult struct {
	Checkpoint	CheckpointInfo	`json:"checkpoint"`
	Replayed	bool		`json:"replayed"`
	Outcome		string		`json:"outcome"`
}

Collect

Collect reclaims workspaces that are past their TTL and provably unused.

func Collect(options CollectOptions) ([]CollectResult, error)

Returns: []CollectResult, error.

CollectOptions

CollectOptions configures a sweep.

type CollectOptions struct {
	RegistryDir	string

	Team	string

	Now	func() time.Time
}

CollectResult

CollectResult is one workspace a sweep considered, and what it did about it.

type CollectResult struct {
	ID	string	`json:"id"`

	Dir	string	`json:"dir"`

	Removed	bool	`json:"removed"`

	Reason	string	`json:"reason"`
}

CompareCheckpoints

func CompareCheckpoints(registryDir, fromID, toID string) ([]CheckpointChange, error)

Returns: []CheckpointChange, error.

ComparePortableCheckpoints

func ComparePortableCheckpoints(registryDir, fromID, toID string) (PortableCheckpointDiff, error)

Returns: PortableCheckpointDiff, error.

ConditionalWriteStore

ConditionalWriteStore opts into atomic IfMatch/IfNoneMatch enforcement.

type ConditionalWriteStore interface {
	SupportsConditionalWrites() bool
}

CopyStore

type CopyStore interface {
	CopyObject(context.Context, string, string, string, string) (Object, error)
}

CreateDelta

CreateDelta describes the difference between two checkpoints in one registry.

func CreateDelta(ctx context.Context, registryDir, baseID, targetID string, options DeltaOptions) (*DeltaDocument, error)

Returns: *DeltaDocument, error.

DecodeDelta

DecodeDelta parses a transported delta.

func DecodeDelta(raw []byte) (*DeltaDocument, error)

Returns: *DeltaDocument, error.

DefaultWorkspaceRegistryDir

DefaultWorkspaceRegistryDir reports where this host stores local workspace references.

func DefaultWorkspaceRegistryDir() (string, error)

DefaultWorkspaceRegistryDirForTeam

DefaultWorkspaceRegistryDirForTeam reports where a named team's workspace references live on this host.

func DefaultWorkspaceRegistryDirForTeam(team string) (string, error)

Returns: string, error.

DeleteCheckpoint

DeleteCheckpoint removes a retained checkpoint and its local replay receipt.

func DeleteCheckpoint(ctx context.Context, registryDir, id string) error

Returns: error.

DeltaChange

DeltaChange is one path's difference.

type DeltaChange struct {
	Path	string		`json:"path"`
	Kind	string		`json:"kind"`
	From	*CheckpointFile	`json:"from,omitempty"`
	To	*CheckpointFile	`json:"to,omitempty"`
}

DeltaChangeAdded

Change kinds, matching what the checkpoint diff already emits.

const DeltaChangeAdded = "added"

DeltaChangeChanged

Change kinds, matching what the checkpoint diff already emits.

const DeltaChangeChanged = "changed"

DeltaChangeDeleted

Change kinds, matching what the checkpoint diff already emits.

const DeltaChangeDeleted = "deleted"

DeltaDocument

DeltaDocument is the transferable form.

type DeltaDocument struct {
	Version			int			`json:"version"`
	BaseID			string			`json:"base_id"`
	TargetID		string			`json:"target_id"`
	Created			time.Time		`json:"created"`
	Changes			[]DeltaChange		`json:"changes"`
	Files			int64			`json:"files"`
	Bytes			int64			`json:"bytes"`
	Content			map[string][]byte	`json:"content,omitempty"`
	IncludeSensitive	bool			`json:"include_sensitive,omitempty"`
}

DeltaDocumentDigest

DeltaDocumentDigest is the digest a sender publishes for a document and a receiver checks it against.

func DeltaDocumentDigest(encoded []byte) string

Returns: string.

DeltaOptions

DeltaOptions bounds the work a delta may describe.

type DeltaOptions struct {
	MaxBytes	int64
	MaxFiles	int64

	IncludeSensitive	bool

	Encoded		[]byte
	ExpectSHA256	string
}

DeltaVersion

DeltaVersion is the delta document's format version.

const DeltaVersion = 1

DestroyRegisteredWorkspace

DestroyRegisteredWorkspace is an explicit host-administrative operation over a trusted registry.

func DestroyRegisteredWorkspace(ctx context.Context, registryDir, id string) error

Returns: error.

DiscardRecoveryHold

func DiscardRecoveryHold(ctx context.Context, registryDir, id, owner string) (RecoveryHold, error)

Returns: RecoveryHold, error.

EncodeDelta

EncodeDelta serializes a delta, including its content, for transport.

func EncodeDelta(delta *DeltaDocument) ([]byte, error)

Returns: []byte, error.

EnvironmentDestroy

const EnvironmentDestroy = authority.EnvironmentDestroy

EnvironmentPromote

const EnvironmentPromote = authority.EnvironmentPromote

EnvironmentReset

const EnvironmentReset = authority.EnvironmentReset

ErrBucketExists

var ErrBucketExists = errors.New("stow: bucket already exists")

ErrBucketNotEmpty

var ErrBucketNotEmpty = errors.New("stow: bucket is not empty")

ErrBucketNotFound

var ErrBucketNotFound = errors.New("stow: bucket not found")

ErrCapacityConflict

var ErrCapacityConflict = capacity.ErrConflict

ErrCapacityFull

var ErrCapacityFull = capacity.ErrFull

ErrCapacityInvalid

var ErrCapacityInvalid = capacity.ErrInvalid

ErrCapacityUnknown

var ErrCapacityUnknown = capacity.ErrUnknown

ErrClosed

var ErrClosed = errors.New("stow: runtime is closed")

ErrConditionalWritesUnsupported

var ErrConditionalWritesUnsupported = errors.New("stow: conditional writes unsupported")

ErrDeltaConflict

ErrDeltaConflict reports that a delta could not be applied because the target is not where the delta was written to be applied.

var ErrDeltaConflict = errors.New("delta target has diverged from the delta's base")

ErrDeltaDigestMismatch

ErrDeltaDigestMismatch reports that a delta document does not hash to the digest the sender published for it.

var ErrDeltaDigestMismatch = errors.New("delta document does not match the digest the sender published")

ErrDeltaTooLarge

ErrDeltaTooLarge reports a delta document whose content is over MaxDeltaBytes.

var ErrDeltaTooLarge = errors.New("delta document is larger than the format allows")

ErrDeltaVersionUnsupported

ErrDeltaVersionUnsupported reports a delta whose format version this build does not speak.

var ErrDeltaVersionUnsupported = errors.New("delta document version is not supported")

ErrGuardedSavesUnsupported

var ErrGuardedSavesUnsupported = errors.New("stow: guarded saves unsupported")

ErrInvalidBucket

var ErrInvalidBucket = errors.New("stow: invalid bucket name")

ErrInvalidKey

var ErrInvalidKey = errors.New("stow: invalid object key")

ErrInvalidListLimit

var ErrInvalidListLimit = errors.New("stow: list limit must not be negative")

ErrInvalidRecoveryHold

var ErrInvalidRecoveryHold = storage.ErrInvalidRecoveryHold

ErrInvalidSaveCondition

var ErrInvalidSaveCondition = errors.New("stow: invalid guarded save condition")

ErrInvalidSaveRequest

var ErrInvalidSaveRequest = errors.New("stow: invalid save request")

ErrMutationCommitted

var ErrMutationCommitted = storage.ErrMutationCommitted

ErrNotAuthorized

ErrNotAuthorized is returned for a refused operation.

type ErrNotAuthorized struct {
	Operation	Operation
	Authority	Authority
}

ErrNotAuthorized.Error

func (e *ErrNotAuthorized) Error() string

Returns: string.

ErrObjectNotFound

var ErrObjectNotFound = errors.New("stow: object not found")

ErrPreconditionFailed

var ErrPreconditionFailed = errors.New("stow: precondition failed")

ErrQuotaExceeded

var ErrQuotaExceeded = errors.New("stow: runtime quota exceeded")

ErrRecoveryHeld

var ErrRecoveryHeld = storage.ErrRecoveryHeld

ErrRecoveryHoldConflict

var ErrRecoveryHoldConflict = workspace.ErrRecoveryHoldConflict

ErrRecoveryHoldCorrupt

var ErrRecoveryHoldCorrupt = workspace.ErrRecoveryHoldCorrupt

ErrRecoveryHoldFull

var ErrRecoveryHoldFull = workspace.ErrRecoveryHoldFull

ErrRecoveryHoldNotFound

var ErrRecoveryHoldNotFound = workspace.ErrRecoveryHoldNotFound

ErrRecoveryHoldsUnsupported

var ErrRecoveryHoldsUnsupported = storage.ErrRecoveryHoldsUnsupported

ErrSaveConflict

var ErrSaveConflict = errors.New("stow: guarded save conflicts with current object")

ErrSaveRequestConflict

var ErrSaveRequestConflict = errors.New("stow: save request key has different meaning")

ErrSaveRequestFull

var ErrSaveRequestFull = errors.New("stow: save request retention full")

ErrSaveRequestNotCommitted

var ErrSaveRequestNotCommitted = errors.New("stow: save request was not committed")

ErrSaveRequestNotFound

var ErrSaveRequestNotFound = errors.New("stow: save request receipt not found")

ErrSaveRequestsUnsupported

var ErrSaveRequestsUnsupported = errors.New("stow: durable save requests unsupported")

ErrSaveRequestUnknown

var ErrSaveRequestUnknown = errors.New("stow: save request effect unknown")

ErrUnsupportedBackend

var ErrUnsupportedBackend = errors.New("stow: unsupported runtime backend")

ExportCheckpoint

ExportCheckpoint writes a portable gzip-compressed tar archive.

func ExportCheckpoint(ctx context.Context, registryDir, id string, output io.Writer, options CheckpointArchiveOptions) error

Returns: error.

ExportHandoff

ExportHandoff creates a new directory containing a self-contained portable bundle.

func ExportHandoff(ctx context.Context, options HandoffExportOptions) (Handoff, error)

Returns: Handoff, error.

FilesystemOptions

type FilesystemOptions struct {
	Dir		string
	Options		Options
	Namespace	*CapacityNamespace
}

GetRegistryPolicy

func GetRegistryPolicy(registryDir string) (RegistryPolicy, error)

Returns: RegistryPolicy, error.

GitRepositoryInput

GitRepositoryInput fetches one local repository commit into a fresh shallow repository and checks it out detached.

type GitRepositoryInput struct {
	Source		string	`json:"source"`
	Destination	string	`json:"destination"`
	Ref		string	`json:"ref"`
}

Handoff

type Handoff struct {
	Version		int		`json:"version"`
	WorkspaceID	string		`json:"workspace_id"`
	CheckpointID	string		`json:"checkpoint_id,omitempty"`
	RegistryDir	string		`json:"registry_dir,omitempty"`
	Team		string		`json:"team,omitempty"`
	Archive		*HandoffArchive	`json:"archive,omitempty"`
}

HandoffArchive

type HandoffArchive struct {
	Path	string	`json:"path"`
	SHA256	string	`json:"sha256"`
	Bytes	int64	`json:"bytes"`
	Files	int64	`json:"files"`
}

HandoffError

type HandoffError struct {
	BundleDir	string
	Outcome		string
	Err		error
}

HandoffError.Error

func (e *HandoffError) Error() string

Returns: string.

HandoffError.Unwrap

func (e *HandoffError) Unwrap() error

Returns: error.

HandoffExportOptions

type HandoffExportOptions struct {
	RegistryDir	string
	WorkspaceID	string
	CheckpointID	string
	BundleDir	string
	ArchiveOptions	CheckpointArchiveOptions
}

ImportCheckpoint

ImportCheckpoint validates a portable checkpoint archive in a private staging directory and atomically publishes it only after every path and digest passes.

func ImportCheckpoint(ctx context.Context, registryDir string, input io.Reader, options CheckpointArchiveOptions) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

ImportHandoff

ImportHandoff verifies identity and a private copy of the received archive before import.

func ImportHandoff(ctx context.Context, path, registryDir string, document Handoff, options CheckpointArchiveOptions) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

List

List returns the workspaces this machine knows about, quietest first.

func List(options ListWorkspacesOptions) (WorkspaceListing, error)

Returns: WorkspaceListing, error.

ListOptions

type ListOptions struct {
	Prefix	string
	Cursor	string
	Limit	int
}

ListRecoveryHolds

func ListRecoveryHolds(ctx context.Context, registryDir string, query RecoveryHoldQuery) (RecoveryHoldPage, error)

Returns: RecoveryHoldPage, error.

ListWorkspacesOptions

ListWorkspacesOptions bounds a workspace listing.

type ListWorkspacesOptions struct {
	RegistryDir	string
	Team		string

	Now	time.Time
}

LoadCheckpoint

func LoadCheckpoint(registryDir, id string) (CheckpointManifest, error)

Returns: CheckpointManifest, error.

LookupWorkspace

LookupWorkspace reads one workspace's registry entry: no process, no claims, no writes.

func LookupWorkspace(registryDir, id string) (WorkspaceReference, error)

Returns: WorkspaceReference, error.

MaxDeltaBytes

MaxDeltaBytes is the largest content a delta document may declare, on the way out and on the way in.

const MaxDeltaBytes int64 = 16 << 20

MaxRecoveryHoldBytes

const MaxRecoveryHoldBytes = workspace.MaxRecoveryHoldBytes

MaxRecoveryHoldPeakBytes

const MaxRecoveryHoldPeakBytes = workspace.MaxRecoveryHoldPeakBytes

MaxRecoveryHolds

const MaxRecoveryHolds = workspace.MaxRecoveryHolds

MaxRecoveryReferences

const MaxRecoveryReferences = workspace.MaxRecoveryReferences

MultipartOptions

MultipartOptions are the object properties a multipart upload fixes at initiation.

type MultipartOptions struct {
	ContentType	string
	Metadata	map[string]string
}

MultipartStore

MultipartStore is the optional extension: a store that can stream an object larger than memory.

type MultipartStore interface {
	CreateMultipartUpload(ctx context.Context, bucket, key string, options MultipartOptions) (MultipartUpload, error)
	UploadPart(ctx context.Context, uploadID string, partNumber int, data []byte) (Part, error)
	CompleteMultipartUpload(ctx context.Context, uploadID string, parts []Part) (Object, error)
	AbortMultipartUpload(ctx context.Context, uploadID string) error

	GetMultipartUpload(ctx context.Context, uploadID string) (MultipartUpload, error)
	ListParts(ctx context.Context, uploadID string) ([]Part, error)
	ListMultipartUploads(ctx context.Context, bucket string) ([]MultipartUpload, error)
}

MultipartUpload

MultipartUpload is an in-flight upload.

type MultipartUpload struct {
	UploadID	string
	Bucket		string
	Key		string
	Initiated	time.Time
	ContentType	string
	Metadata	map[string]string
}

Object

type Object struct {
	Bucket		string
	Key		string
	Data		[]byte
	Size		int64
	ETag		string
	ContentType	string
	Metadata	map[string]string
	LastModified	time.Time
}

ObjectDelete

const ObjectDelete = authority.ObjectDelete

ObjectList

const ObjectList = authority.ObjectList

ObjectPage

type ObjectPage struct {
	Objects		[]Object
	Truncated	bool
	NextCursor	string
}

ObjectRange

type ObjectRange struct {
	Offset	int64
	Length	int64
}

ObjectRead

const ObjectRead = authority.ObjectRead

ObjectRecoveryHoldOptions

type ObjectRecoveryHoldOptions struct {
	ID, Owner	string
	Objects		[]ObjectRecoveryReference
}

ObjectRecoveryReference

type ObjectRecoveryReference struct {
	Bucket, Key	string
	Condition	SaveCondition
}

ObjectWrite

const ObjectWrite = authority.ObjectWrite

Open

Open a handle. Retain it until operations finish, then close it.

func Open(options Options) (*Runtime, error)

Returns: *Runtime, error.

OpenCapacityHost

func OpenCapacityHost(options CapacityHostOptions) (*CapacityHost, error)

Returns: *CapacityHost, error.

OpenFilesystem

OpenFilesystem owns one exclusively locked durable directory; Reset is unavailable.

func OpenFilesystem(options FilesystemOptions) (*Runtime, error)

Returns: *Runtime, error.

OpenWorkspace

OpenWorkspace opens a workspace rooted at options.Dir.

func OpenWorkspace(options WorkspaceOptions) (*Workspace, error)

Returns: *Workspace, error.

Operation

Operation is a single permission.

type Operation string

Options

type Options struct {
	Backend			Backend
	MaxBytes		int64
	MaxObjects		int64
	MaxMultipartUploads	int64

	Store	Store

	Authority	*Authority
}

Part

Part is one uploaded piece of a multipart upload.

type Part struct {
	PartNumber	int
	ETag		string
	Size		int64
}

PortableCheckpointDiff

type PortableCheckpointDiff struct {
	Version	int				`json:"version"`
	Files	[]CheckpointChange		`json:"files"`
	Buckets	[]CheckpointBucketChange	`json:"buckets"`
	Objects	[]CheckpointObjectChange	`json:"objects"`
}

PreparedRepository

PreparedRepository records the immutable revision selected for one input.

type PreparedRepository struct {
	Source		string	`json:"source"`
	Destination	string	`json:"destination"`
	Ref		string	`json:"ref"`
	Commit		string	`json:"commit"`
}

PreparedWorkspace

PreparedWorkspace is the ready-to-launch result.

type PreparedWorkspace struct {
	Workspace		*Workspace
	WorkingDirectory	string
	SeededBytes		int64
	SeededObjects		int64
	BaseIdentity		string
	Repositories		[]PreparedRepository

	RegistryEntries	int64

	MaxWorkspaces	int64
}

PrepareOptions

PrepareOptions describes a local, deterministic workspace seed.

type PrepareOptions struct {
	WorkspaceOptions
	WorkingDirectory	string			`json:"working_directory,omitempty"`
	Inputs			[]WorkspaceInput	`json:"inputs,omitempty"`
	Repositories		[]GitRepositoryInput	`json:"repositories,omitempty"`
	IncludeSensitiveInputs	bool			`json:"include_sensitive_inputs,omitempty"`

	MaxWorkspaces	int64	`json:"max_workspaces,omitempty"`
}

PrepareWorkspace

PrepareWorkspace creates a Stow-owned workspace, stages declared local files and selected Git refs, checks the seed against effective runtime limits, then returns the directory an agent can use.

func PrepareWorkspace(options PrepareOptions) (_ *PreparedWorkspace, resultErr error)

Returns: *PreparedWorkspace, error.

PreviewCheckpointArchive

PreviewCheckpointArchive validates archive structure, file paths, limits, content digests, and the gzip trailer without extracting or publishing files.

func PreviewCheckpointArchive(ctx context.Context, input io.Reader, options CheckpointArchiveOptions) (CheckpointArchivePreview, error)

Returns: CheckpointArchivePreview, error.

Prune

Prune removes registry entries whose workspace directory no longer exists.

func Prune(options PruneOptions) ([]PruneResult, error)

Returns: []PruneResult, error.

PruneOptions

PruneOptions bounds a prune.

type PruneOptions struct {
	RegistryDir	string
	Team		string

	IncludeAdopted	bool
}

PruneResult

PruneResult is one registry entry prune considered, and what it did about it.

type PruneResult struct {
	ID	string	`json:"id"`
	Dir	string	`json:"dir"`

	Removed	bool	`json:"removed"`

	Reason	string	`json:"reason"`
}

PutOptions

type PutOptions struct {
	ContentType	string
	Metadata	map[string]string

	IfMatch		string
	IfNoneMatch	string
}

RangeStore

type RangeStore interface {
	OpenObjectRange(context.Context, string, string, ObjectRange) (io.ReadCloser, Object, error)
}

ReadCheckpointFile

ReadCheckpointFile reads one file's bytes out of a published checkpoint, verifying the digest the manifest recorded.

func ReadCheckpointFile(registryDir, checkpointID, path string) ([]byte, error)

Returns: []byte, error.

ReadHandoff

func ReadHandoff(path string) (Handoff, error)

Returns: Handoff, error.

ReadHandoffReader

func ReadHandoffReader(reader io.Reader) (Handoff, error)

Returns: Handoff, error.

ReadOnly

ReadOnly returns an Authority that can read and list but change nothing.

func ReadOnly() Authority

ReadWrite

ReadWrite returns an Authority for local work with no reach outside the environment.

func ReadWrite() Authority

RecoveryHold

type RecoveryHold struct {
	RecoveryHoldRequest
	Meaning		string		`json:"meaning"`
	State		string		`json:"state"`
	Created		time.Time	`json:"created"`
	FinishedAt	time.Time	`json:"finished_at,omitempty"`
}

RecoveryHoldPage

type RecoveryHoldPage struct {
	Holds		[]RecoveryHold	`json:"holds"`
	NextCursor	string		`json:"next_cursor,omitempty"`
	ReservedBytes	int64		`json:"reserved_bytes"`

	PeakReservedBytes	int64	`json:"peak_reserved_bytes"`
}

RecoveryHoldQuery

type RecoveryHoldQuery struct {
	Cursor		string
	Limit		int
	WorkspaceID	string
	IncludeFinished	bool
}

RecoveryHoldRequest

type RecoveryHoldRequest struct {
	ID		string			`json:"id"`
	Owner		string			`json:"owner"`
	References	[]RecoveryReference	`json:"references"`
	ExpiresAt	time.Time		`json:"expires_at,omitempty"`
}

RecoveryReference

type RecoveryReference struct {
	WorkspaceID	string	`json:"workspace_id"`
	CheckpointID	string	`json:"checkpoint_id,omitempty"`
}

RegistryPolicy

type RegistryPolicy struct {
	Version			int	`json:"version"`
	MaxWorkspaces		int64	`json:"max_workspaces"`
	MaxCheckpoints		int64	`json:"max_checkpoints"`
	MaxCheckpointBytes	int64	`json:"max_checkpoint_bytes"`
}

RegistryPolicy.Validate

func (p RegistryPolicy) Validate() error

Returns: error.

ReleaseRecoveryHold

func ReleaseRecoveryHold(ctx context.Context, registryDir, id, owner string) (RecoveryHold, error)

Returns: RecoveryHold, error.

ReplacementCondition

Request unconditional replacement while preserving authorization and quota checks.

func ReplacementCondition() SaveCondition

ResolveCheckpoint

Resolve an existing capture request without making another checkpoint.

func ResolveCheckpoint(ctx context.Context, registryDir, workspaceID string, request CheckpointRequest) (CheckpointResult, error)

Returns: CheckpointResult, error.

ResolveRegistryDir

ResolveRegistryDir is the one rule for where a workspace's metadata lives.

func ResolveRegistryDir(dir, team string) (string, error)

Returns: string, error.

RestoreCheckpoint

func RestoreCheckpoint(registryDir, id string, options WorkspaceOptions) (*Workspace, error)

Returns: *Workspace, error.

RestoreCheckpointWithGit

RestoreCheckpointWithGit rebuilds repository metadata from explicit local sources.

func RestoreCheckpointWithGit(registryDir, id string, options WorkspaceOptions, sources []GitRepositoryInput) (*Workspace, error)

Returns: *Workspace, error.

Resume

Resume reopens a workspace by the identity it was given when it was created.

func Resume(id string) (*Workspace, error)

Returns: *Workspace, error.

ResumeIn

ResumeIn is Resume against a chosen registry.

func ResumeIn(registryDir, id string) (*Workspace, error)

Returns: *Workspace, error.

ResumeWith

ResumeWith is Resume with options, chiefly so the registry location and the clock can be chosen.

func ResumeWith(options WorkspaceOptions, id string) (*Workspace, error)

Returns: *Workspace, error.

Runtime

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

Runtime.Authority

Authority reports what this environment permits.

func (r *Runtime) Authority() Authority

Returns: Authority.

Runtime.Authorize

Authorize is the decision for one operation on one resource this Runtime's verbs do not cover.

func (r *Runtime) Authorize(op authority.Operation, res policy.Resource) error

Returns: error.

Runtime.BeginObjectRecoveryHold

BeginObjectRecoveryHold protects observed bytes by refusing their mutation until release.

func (r *Runtime) BeginObjectRecoveryHold(ctx context.Context, options ObjectRecoveryHoldOptions) error

Returns: error.

Runtime.Capabilities

Return the operations and limits supported by this handle.

func (r *Runtime) Capabilities() Capabilities

Returns: Capabilities.

Runtime.Close

Release this handle. Do not submit new operations after closing it.

func (r *Runtime) Close() error

Returns: error.

Runtime.CopyObject

Copy source bytes and metadata to the destination object.

func (r *Runtime) CopyObject(ctx context.Context, sourceBucket, sourceKey, destinationBucket, destinationKey string) (Object, error)

Returns: Object, error.

Runtime.CreateBucket

Create the named bucket before storing objects.

func (r *Runtime) CreateBucket(ctx context.Context, name string) error

Returns: error.

Runtime.DeleteBucket

Remove an empty bucket; a nonempty bucket is refused.

func (r *Runtime) DeleteBucket(ctx context.Context, name string) error

Returns: error.

Runtime.DeleteObject

Delete the selected object; deleting a missing object is idempotent.

func (r *Runtime) DeleteObject(ctx context.Context, bucket, key string) error

Returns: error.

Runtime.GetObject

Return complete object bytes and metadata.

func (r *Runtime) GetObject(ctx context.Context, bucket, key string) (Object, error)

Returns: Object, error.

Runtime.HeadObject

Return object metadata without reading the body into the result.

func (r *Runtime) HeadObject(ctx context.Context, bucket, key string) (Object, error)

Returns: Object, error.

Runtime.ListBuckets

Return the buckets visible to the handle.

func (r *Runtime) ListBuckets(ctx context.Context) ([]Bucket, error)

Returns: []Bucket, error.

Runtime.ListObjects

Return one page. Pass nextCursor to continue when truncated is true.

func (r *Runtime) ListObjects(ctx context.Context, bucket string, options ListOptions) (ObjectPage, error)

Returns: ObjectPage, error.

Runtime.OpenObject

func (r *Runtime) OpenObject(ctx context.Context, bucket, key string) (io.ReadCloser, Object, error)

Returns: io.ReadCloser, Object, error.

Runtime.OpenObjectRange

func (r *Runtime) OpenObjectRange(ctx context.Context, bucket, key string, span ObjectRange) (io.ReadCloser, Object, error)

Returns: io.ReadCloser, Object, error.

Runtime.PutObject

Store complete bytes and metadata, subject to write conditions and quotas.

func (r *Runtime) PutObject(ctx context.Context, bucket, key string, data []byte, options PutOptions) (Object, error)

Returns: Object, error.

Runtime.PutObjectStream

Stage exactly options.size bytes and atomically publish after validation.

func (r *Runtime) PutObjectStream(ctx context.Context, bucket, key string, body io.Reader, options StreamPutOptions) (Object, error)

Returns: Object, error.

Runtime.ReadForSave

Read bytes and metadata with an opaque condition, including observed absence. The condition grants no permission.

func (r *Runtime) ReadForSave(ctx context.Context, bucket, key string) (Object, SaveCondition, error)

Returns: Object, SaveCondition, error.

Runtime.ReleaseObjectRecoveryHold

func (r *Runtime) ReleaseObjectRecoveryHold(ctx context.Context, id, owner string) error

Returns: error.

Runtime.Reset

Clear storage state where the backend supports reset.

func (r *Runtime) Reset(ctx context.Context) error

Returns: error.

Runtime.ResolveSave

Resolve the original request key without starting another save. Missing evidence leaves the effect unknown.

func (r *Runtime) ResolveSave(ctx context.Context, bucket, key, requestKey string) (SaveResult, error)

Returns: SaveResult, error.

Runtime.SaveObject

Compare the observation at publication. Inspect Outcome even when an error is returned. Qualified filesystem stores retain keyed receipts.

func (r *Runtime) SaveObject(ctx context.Context, bucket, key string, data []byte, options SaveOptions) (SaveResult, error)

Returns: SaveResult, error.

Runtime.SupportsConditionalWrites

func (r *Runtime) SupportsConditionalWrites() bool

Returns: bool.

Runtime.SupportsDurableSaveRequests

func (r *Runtime) SupportsDurableSaveRequests() bool

Returns: bool.

Runtime.SupportsGuardedSaves

func (r *Runtime) SupportsGuardedSaves() bool

Returns: bool.

Runtime.SupportsRecoveryHolds

func (r *Runtime) SupportsRecoveryHolds() bool

Returns: bool.

Runtime.Usage

Return current storage accounting.

func (r *Runtime) Usage() Usage

Returns: Usage.

SaveCommitted

const SaveCommitted = stowruntime.SaveCommitted

SaveCondition

SaveCondition is opaque and valid only for its issuing runtime and resource.

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

SaveCondition.ObservedAbsence

func (c SaveCondition) ObservedAbsence() bool

Returns: bool.

SaveNotCommitted

const SaveNotCommitted = stowruntime.SaveNotCommitted

SaveOptions

type SaveOptions struct {
	Condition	SaveCondition
	PutOptions	PutOptions
	RequestKey	string
}

SaveOutcome

type SaveOutcome string

SaveResult

type SaveResult struct {
	Object		Object
	Outcome		SaveOutcome
	Replayed	bool
}

SaveUnknown

const SaveUnknown = stowruntime.SaveUnknown

SetRegistryPolicy

SetRegistryPolicy persists standing limits; zero is unlimited.

func SetRegistryPolicy(registryDir string, policy RegistryPolicy) error

Returns: error.

StagedObject

type StagedObject interface {
	Commit(context.Context) (Object, error)
	Abort(context.Context) error
}

StagedWriteStore

type StagedWriteStore interface {
	StageObject(context.Context, string, string, io.Reader, PutOptions) (StagedObject, error)
}

Store

Store supplies object storage to Open.

type Store interface {
	CreateBucket(ctx context.Context, name string) error
	DeleteBucket(ctx context.Context, name string) error
	ListBuckets(ctx context.Context) ([]Bucket, error)

	PutObject(ctx context.Context, bucket, key string, data []byte, options PutOptions) (Object, error)
	GetObject(ctx context.Context, bucket, key string) (Object, error)
	HeadObject(ctx context.Context, bucket, key string) (Object, error)
	DeleteObject(ctx context.Context, bucket, key string) error
	ListObjects(ctx context.Context, bucket string, options ListOptions) (ObjectPage, error)

	Close() error
}

StreamingStore

type StreamingStore interface {
	OpenObject(context.Context, string, string) (io.ReadCloser, Object, error)
}

StreamingWriteStore

type StreamingWriteStore interface {
	PutObjectStream(context.Context, string, string, io.Reader, PutOptions) (Object, error)
}

StreamPutOptions

type StreamPutOptions struct {
	Size	int64
	PutOptions
}

UpstreamRead

const UpstreamRead = authority.UpstreamRead

UpstreamWrite

const UpstreamWrite = authority.UpstreamWrite

Usage

Return current storage accounting.

type Usage struct {
	Bytes	int64
	Objects	int64
}

ValidateHandoff

func ValidateHandoff(document Handoff) error

Returns: error.

VerifyDeltaDigest

VerifyDeltaDigest refuses a document that does not hash to what the sender said it hashes to.

func VerifyDeltaDigest(encoded []byte, expected string) error

Returns: error.

Workspace

Workspace is a bounded artifact workspace: a real directory a caller works in, and a bucket over the same bytes.

type Workspace struct {
	*Runtime
	// contains filtered or unexported fields
}

Workspace.Bucket

Bucket is the bucket over the workspace's bytes.

func (w *Workspace) Bucket() string

Returns: string.

Workspace.Close

Release this handle. Do not submit new operations after closing it.

func (w *Workspace) Close() error

Returns: error.

Workspace.CreateCheckpoint

CreateCheckpoint captures immutable project files outside the mutable workspace.

func (w *Workspace) CreateCheckpoint(ctx context.Context, options CheckpointOptions) (CheckpointInfo, error)

Returns: CheckpointInfo, error.

Workspace.Destroy

Delete only an eligible owned workspace with EnvironmentDestroy authority. Adopted and protected directories are refused.

func (w *Workspace) Destroy(ctx context.Context) error

Returns: error.

Workspace.Dir

Dir is the absolute workspace directory, stable for the workspace's life.

func (w *Workspace) Dir() string

Returns: string.

Workspace.Facade

Start or reuse a loopback S3 endpoint over this workspace's runtime.

func (w *Workspace) Facade() (*WorkspaceFacade, error)

Returns: *WorkspaceFacade, error.

Workspace.FacadeWithOptions

Start the workspace S3 facade with explicit request and concurrency limits.

func (w *Workspace) FacadeWithOptions(options WorkspaceFacadeOptions) (*WorkspaceFacade, error)

Returns: *WorkspaceFacade, error.

Workspace.ID

ID is the workspace's durable identity, which outlives this handle.

func (w *Workspace) ID() string

Returns: string.

Workspace.MaxCheckpointBytes

MaxCheckpointBytes is the cumulative payload-byte cap for retained checkpoints; zero means unlimited.

func (w *Workspace) MaxCheckpointBytes() int64

Returns: int64.

Workspace.MaxCheckpoints

MaxCheckpoints is the retained checkpoint count cap; zero means unlimited.

func (w *Workspace) MaxCheckpoints() int64

Returns: int64.

Workspace.Path

Path returns where a key's bytes live, and whether they are there.

func (w *Workspace) Path(key string) (string, bool)

Returns: string, bool.

Workspace.RefreshUsage

Reconcile direct filesystem writes at a quiescent boundary before quota-sensitive operations.

func (w *Workspace) RefreshUsage(ctx context.Context) error

Returns: error.

Workspace.Touch

Touch records that the workspace was used, which is what a TTL is measured from.

func (w *Workspace) Touch() error

Returns: error.

Workspace.WorkingDirectory

WorkingDirectory is the directory an external task runner should use as its current working directory.

func (w *Workspace) WorkingDirectory() string

Returns: string.

WorkspaceFacade

WorkspaceFacade describes the loopback S3 endpoint owned by a Workspace.

type WorkspaceFacade struct {
	MaxMultipartUploads	int64	`json:"max_multipart_uploads"`
	MaxConcurrentRequests	int	`json:"max_concurrent_requests"`
	MaxRequestBytes		int64	`json:"max_request_bytes"`
	Endpoint		string	`json:"endpoint"`
	Region			string	`json:"region"`
	AccessKeyID		string	`json:"access_key_id"`
	SecretAccessKey		string	`json:"secret_access_key"`
}

WorkspaceFacadeOptions

Facade starts one authenticated loopback server sharing this workspace's runtime.

type WorkspaceFacadeOptions struct {
	MaxRequestBytes		int64
	MaxConcurrentRequests	int
}

WorkspaceInput

WorkspaceInput copies one local file or directory into a prepared workspace.

type WorkspaceInput struct {
	Source		string	`json:"source"`
	Destination	string	`json:"destination"`
}

WorkspaceListing

WorkspaceListing is what a listing resolved to: the registry it actually read, and what that registry holds.

type WorkspaceListing struct {
	Registry	string

	Team	string

	Workspaces	[]WorkspaceSummary
}

WorkspaceOptions

WorkspaceOptions configures a workspace.

type WorkspaceOptions struct {
	Dir	string

	Bucket	string

	MaxBytes		int64
	MaxObjects		int64
	MaxMultipartUploads	int64

	MaxCheckpointBytes	int64
	MaxCheckpoints		int64

	Authority	*Authority

	Policy	policy.Source

	TTL	time.Duration

	RegistryDir	string

	Team	string

	Adopted	bool

	Now	func() time.Time
	// contains filtered or unexported fields
}

WorkspaceReference

WorkspaceReference is what the registry records about a workspace, read without opening it.

type WorkspaceReference struct {
	WorkingDirectory	string
	ID			string
	Dir			string
	Bucket			string

	MaxCheckpointBytes	int64
	MaxCheckpoints		int64
}

WorkspaceSummary

WorkspaceSummary is one workspace as a caller can see it without resuming it.

type WorkspaceSummary struct {
	ID	string	`json:"id"`
	Dir	string	`json:"dir"`
	Bucket	string	`json:"bucket"`
	Created	string	`json:"created"`

	LastUsed	string	`json:"last_used"`

	AgeSeconds	int64	`json:"age_seconds"`
	IdleSeconds	int64	`json:"idle_seconds"`
	TTLSeconds	int64	`json:"ttl_seconds"`

	ExpiresInSeconds	int64	`json:"expires_in_seconds"`
	HasTTL			bool	`json:"has_ttl"`
	Owned			bool	`json:"owned"`

	Readable	bool	`json:"readable"`
}

WorkspaceTaskManifest

WorkspaceTaskManifest is the versioned JSON input accepted by workspace preparation tools.

type WorkspaceTaskManifest struct {
	Version			int			`json:"version"`
	Root			string			`json:"root"`
	WorkingDirectory	string			`json:"working_directory,omitempty"`
	Inputs			[]WorkspaceInput	`json:"inputs,omitempty"`
	Repositories		[]GitRepositoryInput	`json:"repositories,omitempty"`
	MaxBytes		int64			`json:"max_bytes,omitempty"`
	MaxObjects		int64			`json:"max_objects,omitempty"`
	MaxCheckpointBytes	int64			`json:"max_checkpoint_bytes,omitempty"`
	MaxCheckpoints		int64			`json:"max_checkpoints,omitempty"`

	MaxWorkspaces	int64	`json:"max_workspaces,omitempty"`
	TTLSeconds	int64	`json:"ttl_seconds,omitempty"`

	Team			string	`json:"team,omitempty"`
	RegistryDir		string	`json:"registry_dir,omitempty"`
	Bucket			string	`json:"bucket,omitempty"`
	IncludeSensitiveInputs	bool	`json:"include_sensitive_inputs,omitempty"`
}