depot

package
v0.0.0-...-0fc9bd1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MarkerSchemaV2       = "aha-depot/v2" // readable pre-fence Archive
	LayoutVersionV2      = "v2"
	MarkerSchemaCurrent  = "aha-depot/v3"
	LayoutVersionCurrent = "v3"
	LatestPointerSchema  = "aha-depot-latest/v2"
	MachinesIndexSchema  = "aha-depot-machines/v2"
	MachinesIndexKey     = "machines/index.json"
	MarkerObjectKey      = "aha-depot.json"
)

Depot v2 layout (docs/depot-v2-spec.md). These constants and key builders are the locked pre-release contract, pinned by TestV2ObjectKeyGoldens: 

aha-depot/v2                                  marker
blobs/v2/<sha256>.zst                         one compressed file version, write-once
machines/index.json                           registry of machine namespaces
machines/<machine>/manifests/<sha256>.json    one snapshot manifest, write-once
machines/<machine>/latest                     pointer, conditional PUT
View Source 
const (

	// ArchiveWriterFenceFeature is required in every Archive this build may
	// open. The immediately preceding binary does not recognise it and
	// therefore refuses the Archive before publication.
	ArchiveWriterFenceFeature = "writer-fence-v1"
)
View Source 
const (
	DefaultR2Bucket = "aha-archive"
)

Variables

This section is empty.

Functions

func BlobObjectKey 

func BlobObjectKey(k model.BlobKey) string

BlobObjectKey is the object key for a stored file version. The key is derived from a validated BlobKey, so an unsafe or non-content-addressed blob key cannot be constructed.

func ConfigFromAddress 

func ConfigFromAddress(addr Address) model.ArchiveConfig

func DecodeLatestPointer 

func DecodeLatestPointer(b []byte) (model.ManifestSHA256, error)

DecodeLatestPointer parses and validates a latest-snapshot pointer.

func DecodeMachinesIndex 

func DecodeMachinesIndex(b []byte) ([]string, error)

DecodeMachinesIndex parses and validates the machine registry.

func EncodeLatestPointer 

func EncodeLatestPointer(sha model.ManifestSHA256) ([]byte, error)

EncodeLatestPointer serializes a machine's latest-snapshot pointer.

func EncodeMachinesIndex 

func EncodeMachinesIndex(machines []string) ([]byte, error)

EncodeMachinesIndex serializes the registry of machine namespaces, sorted and deduplicated. The index is what lets pull discover machines with a single GET instead of a LIST (invariant I6).

func LatestPointerKey 

func LatestPointerKey(machine string) string

LatestPointerKey is the object key of a machine's latest-snapshot pointer.

func ManifestObjectKey 

func ManifestObjectKey(machine string, sha model.ManifestSHA256) string

ManifestObjectKey is the object key for one snapshot manifest in a machine's namespace.

Types

type Address 

type Address struct {
	Type     string
	Location string
}

func AddressFromConfig 

func AddressFromConfig(cfg model.ArchiveConfig) (Address, error)

func ParseAddress 

func ParseAddress(s string) (Address, error)

func ParseExplicitAddress 

func ParseExplicitAddress(s string) (Address, error)

ParseExplicitAddress parses an address supplied at a CLI boundary. Unlike ParseAddress's backward-compatible config/default form, it cannot silently reinterpret a bucket-looking value as a local filesystem path.

func (Address) String 

func (a Address) String() string

type ArchiveLatestMetadata 

type ArchiveLatestMetadata struct {
	Machine        string
	ManifestSHA256 model.ManifestSHA256
	StateSHA256    string
	CapturedAt     string
	Files          int
}

type ArchiveMetadataReport 

type ArchiveMetadataReport struct {
	Initialised     bool
	UpgradeRequired bool
	Binding         model.ArchiveBinding
	Machines        int
	Latest          []ArchiveLatestMetadata
	Problems        []string
	// contains filtered or unexported fields
}

func (ArchiveMetadataReport) DownloadPlan 

func (r ArchiveMetadataReport) DownloadPlan() (DownloadPlan, bool)

DownloadPlan returns the frozen latest vector produced by the same metadata inspection, avoiding duplicate index/pointer requests in unified status.

type ArchiveWriteUpgradeRequiredError 

type ArchiveWriteUpgradeRequiredError struct{}

func (*ArchiveWriteUpgradeRequiredError) Error 

func (*ArchiveWriteUpgradeRequiredError) Error() string

type BlobSource 

type BlobSource interface {
	BlobPath(key model.BlobKey) (string, error)
}

BlobSource provides the uncompressed bytes of blobs a push needs to upload. It is consulted only for content the parent snapshot does not already carry, so an unchanged push never reads file content.

type ContentionError 

type ContentionError struct {
	Key      string
	Attempts int
}

func (*ContentionError) Error 

func (e *ContentionError) Error() string

type CorruptArchiveObjectError 

type CorruptArchiveObjectError struct {
	Object string
	Cause  error
}

func (*CorruptArchiveObjectError) Error 

func (e *CorruptArchiveObjectError) Error() string

func (*CorruptArchiveObjectError) Unwrap 

func (e *CorruptArchiveObjectError) Unwrap() error

type DamagedArchiveError 

type DamagedArchiveError struct{ Problems []string }

DamagedArchiveError prevents writer-capability construction from a metadata graph that status classifies as damaged.

func (*DamagedArchiveError) Error 

func (e *DamagedArchiveError) Error() string

type DownloadPlan 

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

DownloadPlan freezes the Archive latest vector before any Workspace is opened. Effectful download code accepts this opaque plan, not raw addresses.

func (DownloadPlan) ArchiveBinding 

func (p DownloadPlan) ArchiveBinding() (model.ArchiveBinding, error)

func (DownloadPlan) Latest 

func (p DownloadPlan) Latest(machine string) (model.ManifestSHA256, bool, error)

func (DownloadPlan) LatestVector 

func (p DownloadPlan) LatestVector() (map[string]string, error)

func (DownloadPlan) Machines 

func (p DownloadPlan) Machines() ([]string, error)

func (DownloadPlan) PrepareMaterialisation 

func (p DownloadPlan) PrepareMaterialisation(ctx context.Context, materialised map[string]string, supported map[string]string, known func(model.BlobKey) (bool, error)) (*MaterialisationPlan, error)

func (DownloadPlan) RequireAdapters 

func (p DownloadPlan) RequireAdapters(ctx context.Context, materialised map[string]string, supported map[string]string) error

RequireAdapters checks only changed-machine manifests and does so before a writable Workspace is opened. Unsupported snapshots remain durable in the Archive but cannot make this Workspace falsely current.

func (DownloadPlan) SelectedManifest 

func (p DownloadPlan) SelectedManifest(ctx context.Context, machine string) (model.SnapshotManifest, error)

SelectedManifest returns only the manifest named by this plan's frozen latest vector; callers cannot supply a historical identity.

func (DownloadPlan) Summary 

func (p DownloadPlan) Summary(ctx context.Context, known func(model.BlobKey) (bool, error)) (DownloadPlanSummary, error)

func (DownloadPlan) SummaryDelta 

func (p DownloadPlan) SummaryDelta(ctx context.Context, materialised map[string]string, known func(model.BlobKey) (bool, error)) (DownloadPlanSummary, error)

SummaryDelta examines manifests only for machines whose planned latest identity differs from the Workspace materialised vector.

type DownloadPlanSummary 

type DownloadPlanSummary struct {
	Machines        int   `json:"machines"`
	LatestSnapshots int   `json:"latest_snapshots"`
	UnknownBlobs    int64 `json:"unknown_blobs"`
	UnknownBytes    int64 `json:"unknown_bytes"`
}

type ExplicitAddressError 

type ExplicitAddressError struct{}

ExplicitAddressError means a CLI destination omitted its Archive kind. It carries no rejected value, so it is safe for public presentation.

func (*ExplicitAddressError) Error 

func (*ExplicitAddressError) Error() string

type LegacyArchiveError 

type LegacyArchiveError struct{}

ContentionError means a conditional object update kept losing races after the bounded retry policy. It is typed so callers can distinguish contention from corruption, credentials, and transport failures.

func (*LegacyArchiveError) Error 

func (*LegacyArchiveError) Error() string

type MaterialisationPlan 

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

MaterialisationPlan is a disk-spooled, latest-vector-scoped capability. Changed manifests are validated before Workspace mutation, but are not retained together on the heap. The zero value authorises no blob access.

func (*MaterialisationPlan) ArchiveBinding 

func (p *MaterialisationPlan) ArchiveBinding() (model.ArchiveBinding, error)

func (*MaterialisationPlan) Close 

func (p *MaterialisationPlan) Close() error

func (*MaterialisationPlan) ForEachManifest 

func (p *MaterialisationPlan) ForEachManifest(ctx context.Context, apply func(machine string, prepared model.PreparedSnapshot, open func(model.BlobKey) (io.ReadCloser, error)) error) error

ForEachManifest loads at most one spooled manifest at a time and grants blob access only to content addressed by the frozen selected manifests.

func (*MaterialisationPlan) LatestVector 

func (p *MaterialisationPlan) LatestVector() (map[string]string, error)

func (*MaterialisationPlan) Summary 

func (p *MaterialisationPlan) Summary() (DownloadPlanSummary, error)

type PreparedPull 

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

PreparedPull is a read capability for an initialised depot whose marker and machine index were validated before any local corpus mutation. Its fields are private so pull code cannot manufacture the capability from an unchecked V2.

func (PreparedPull) ArchiveBinding 

func (p PreparedPull) ArchiveBinding() (model.ArchiveBinding, error)

func (PreparedPull) Machines 

func (p PreparedPull) Machines() ([]string, error)

func (PreparedPull) PlanDownload 

func (p PreparedPull) PlanDownload(ctx context.Context) (DownloadPlan, error)

type PreparedUpload 

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

PreparedUpload is an opaque write capability for an initialised Archive. The zero value cannot publish or expose an Archive identity.

func (PreparedUpload) ArchiveBinding 

func (p PreparedUpload) ArchiveBinding() (model.ArchiveBinding, error)

func (PreparedUpload) ArchiveState 

func (p PreparedUpload) ArchiveState() (model.ArchiveState, error)

func (PreparedUpload) PlanUpload 

func (p PreparedUpload) PlanUpload(ctx context.Context, manifest model.SnapshotManifest, source BlobSource) (UploadPlan, error)

func (PreparedUpload) Push 

func (p PreparedUpload) Push(ctx context.Context, manifest model.SnapshotManifest, src BlobSource, opts PushOptions) (PushResult, error)

Push publishes through a capability constructed only after Archive marker validation. Upload commands use this method rather than accepting a raw V2.

type PushOptions 

type PushOptions struct {
	Progress *ahaprogress.Tracker
}

type PushResult 

type PushResult struct {
	Reused        bool `json:"reused"`
	Files         int  `json:"files"`
	BlobsUploaded int  `json:"blobs_uploaded"`
	BlobsExisting int  `json:"blobs_existing"`
	BlobsCarried  int  `json:"blobs_carried"`
	// contains filtered or unexported fields
}

PushResult reports what one push did.

func (PushResult) ManifestSHA256 

func (r PushResult) ManifestSHA256() model.ManifestSHA256

ManifestSHA256 is the identity of the pushed (or reused) snapshot.

type R2 

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

func NewR2 

func NewR2(bucket R2Bucket, cfg R2Config) (*R2, error)

func NewR2WithClient 

func NewR2WithClient(bucket R2Bucket, client *s3.Client) (*R2, error)

NewR2WithClient binds a validated bucket to an existing S3 client. It is primarily the protocol-test seam; production configuration uses NewR2.

func (*R2) Address 

func (d *R2) Address() Address

func (*R2) Bucket 

func (d *R2) Bucket() R2Bucket

func (*R2) S3Client 

func (d *R2) S3Client() *s3.Client

type R2AccountID 

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

R2AccountID is a validated Cloudflare account identifier. Cloudflare account IDs are 32 lowercase hexadecimal characters.

func ParseR2AccountID 

func ParseR2AccountID(value string) (R2AccountID, error)

func (R2AccountID) String 

func (id R2AccountID) String() string

type R2AuthorizationError 

type R2AuthorizationError struct {
	Bucket string
	Cause  error
}

func (*R2AuthorizationError) Error 

func (e *R2AuthorizationError) Error() string

func (*R2AuthorizationError) Unwrap 

func (e *R2AuthorizationError) Unwrap() error

type R2Bucket 

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

R2Bucket is a Cloudflare R2 bucket name that has passed syntax and placeholder validation. Its representation is opaque so networking code cannot be constructed with an unchecked bucket string.

func ParseR2Bucket 

func ParseR2Bucket(value string) (R2Bucket, error)

func (R2Bucket) String 

func (b R2Bucket) String() string

func (R2Bucket) Valid 

func (b R2Bucket) Valid() bool

type R2Config 

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

R2Config is a resolved, validated R2 client configuration. Secret-bearing fields are private and the type has no JSON representation, so config writers cannot accidentally persist credentials.

func ResolveR2Config 

func ResolveR2Config(cfg model.R2ArchiveConfig) (R2Config, error)

func ResolveR2ConfigExplicit 

func ResolveR2ConfigExplicit(cfg model.R2ArchiveConfig, creds R2Credentials) (R2Config, error)

ResolveR2ConfigExplicit resolves only its arguments. It never reads the process environment, which makes production-credential fallback impossible for smoke tests and other isolated callers.

func (R2Config) AccountID 

func (c R2Config) AccountID() string

func (R2Config) Endpoint 

func (c R2Config) Endpoint() string

func (R2Config) Region 

func (c R2Config) Region() string

func (R2Config) Valid 

func (c R2Config) Valid() bool

type R2ConfigError 

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

R2ConfigError reports only safe field/reason metadata. The rejected value is never retained, so downstream presentation cannot accidentally disclose a credential.

func (*R2ConfigError) Error 

func (e *R2ConfigError) Error() string

func (*R2ConfigError) Field 

func (e *R2ConfigError) Field() R2ConfigField

func (*R2ConfigError) Kind 

func (e *R2ConfigError) Kind() R2ConfigErrorKind

type R2ConfigErrorKind 

type R2ConfigErrorKind string

R2ConfigErrorKind is the finite set of locally correctable configuration failures. It intentionally excludes raw values. 

const (
	R2ConfigMissing     R2ConfigErrorKind = "missing"
	R2ConfigPlaceholder R2ConfigErrorKind = "placeholder"
	R2ConfigInvalid     R2ConfigErrorKind = "invalid"
)

type R2ConfigField 

type R2ConfigField string

R2ConfigField identifies a configuration field without carrying its value. Public error boundaries may safely expose this metadata. 

const (
	R2ConfigAccountID       R2ConfigField = "account_id"
	R2ConfigEndpoint        R2ConfigField = "endpoint"
	R2ConfigRegion          R2ConfigField = "region"
	R2ConfigAccessKeyID     R2ConfigField = "access_key_id"
	R2ConfigSecretAccessKey R2ConfigField = "secret_access_key"
)

type R2Credentials 

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

R2Credentials is an opaque matching S3 key pair. Explicit consumers such as live smoke tests can carry a test-only capability without consulting ambient production environment variables.

func NewR2Credentials 

func NewR2Credentials(accessKeyID, secretAccessKey string) (R2Credentials, error)

type StalePublicationError 

type StalePublicationError struct{ Machine string }

StalePublicationError means another publication changed the machine's latest pointer after this publication captured its opaque expected parent. The stale publication remains immutable history but cannot move latest.

func (*StalePublicationError) Error 

func (e *StalePublicationError) Error() string

type UnsupportedArchiveFeatureError 

type UnsupportedArchiveFeatureError struct {
	Feature string
}

UnsupportedArchiveFeatureError is returned before an Archive capability is constructed. This prevents an older reader or writer from partially interpreting a format that requires newer semantics.

func (*UnsupportedArchiveFeatureError) Error 

func (e *UnsupportedArchiveFeatureError) Error() string

type UnsupportedArchiveFormatError 

type UnsupportedArchiveFormatError struct {
	FoundMajor     int
	SupportedMajor int
	FoundMinor     int
	SupportedMinor int
}

func (*UnsupportedArchiveFormatError) Error 

func (e *UnsupportedArchiveFormatError) Error() string

type UnsupportedSnapshotAdapterError 

type UnsupportedSnapshotAdapterError struct {
	Adapter          string
	RequiredVersion  string
	SupportedVersion string
}

func (*UnsupportedSnapshotAdapterError) Error 

func (e *UnsupportedSnapshotAdapterError) Error() string

type UploadPlan 

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

UploadPlan freezes validated publication inputs behind an opaque type.

func (UploadPlan) Execute 

func (p UploadPlan) Execute(ctx context.Context, opts PushOptions) (PushResult, error)

func (UploadPlan) Summary 

func (p UploadPlan) Summary() (UploadPlanSummary, error)

type UploadPlanSummary 

type UploadPlanSummary struct {
	Files         int `json:"files"`
	BlobsUpload   int `json:"blobs_upload"`
	BlobsExisting int `json:"blobs_existing"`
	BlobsCarried  int `json:"blobs_carried"`
}

type V2 

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

V2 is a depot in the v2 content-addressed layout (docs/depot-v2-spec.md): file-version blobs stored once under their content address, snapshot manifests in per-machine namespaces, and a per-machine latest pointer. Steady-state methods use only the objectStore primitives, which expose no delete and no list (I5, I6).

func NewLocalV2 

func NewLocalV2(root string) (*V2, error)

NewLocalV2 opens a local-filesystem depot v2 rooted at root.

func NewV2FromR2 

func NewV2FromR2(r *R2) *V2

NewV2FromR2 opens a depot v2 over an existing R2 driver's bucket+client.

func (*V2) Address 

func (v *V2) Address() Address

func (*V2) HasBlob 

func (v *V2) HasBlob(ctx context.Context, key model.BlobKey) (bool, error)

HasBlob reports whether a blob is present (one HEAD/stat, no bytes).

func (*V2) Init 

func (v *V2) Init(ctx context.Context) error

Init provisions the depot marker. It refuses to initialize over a v1 layout: the two layouts never silently mix, and there is no migration (pre-release decision; v1 bundles remain importable via `aha ingest`).

func (*V2) InspectMetadata 

func (v *V2) InspectMetadata(ctx context.Context) (ArchiveMetadataReport, error)

InspectMetadata validates marker, machine index, latest pointers, and latest manifests without probing every blob. It is the bounded status path; Verify owns full blob existence/content auditing.

func (*V2) Latest 

func (v *V2) Latest(ctx context.Context, machine string) (model.ManifestSHA256, bool, error)

Latest returns the machine's latest snapshot identity, if any.

func (*V2) Machines 

func (v *V2) Machines(ctx context.Context) ([]string, error)

Machines returns the registered machine namespaces (one GET, no LIST).

func (*V2) Manifest 

func (v *V2) Manifest(ctx context.Context, machine string, sha model.ManifestSHA256) (model.SnapshotManifest, error)

Manifest fetches and verifies one snapshot manifest: the bytes must be canonical, hash to the requested identity, and belong to the requested machine's namespace.

func (*V2) OpenBlob 

func (v *V2) OpenBlob(ctx context.Context, key model.BlobKey) (io.ReadCloser, error)

OpenBlob returns a verified reader over a blob's uncompressed content.

func (*V2) PreparePull 

func (v *V2) PreparePull(ctx context.Context) (PreparedPull, error)

PreparePull performs the complete metadata preflight required before a caller creates or opens a writable corpus.

func (*V2) PrepareUpload 

func (v *V2) PrepareUpload(ctx context.Context) (PreparedUpload, error)

func (*V2) Verify 

func (v *V2) Verify(ctx context.Context, deep bool) (VerifyReport, error)

Verify audits the depot without progress reporting.

func (*V2) VerifyWithOptions 

func (v *V2) VerifyWithOptions(ctx context.Context, deep bool, opts VerifyOptions) (VerifyReport, error)

VerifyWithOptions audits marker, index, pointers, manifests, and blobs. Deep mode additionally reads and hashes blob bytes and historical manifests.

type VerifyOptions 

type VerifyOptions struct {
	Progress *ahaprogress.Tracker
}

type VerifyReport 

type VerifyReport struct {
	Manifests       int      `json:"manifests"`
	Machines        int      `json:"machines"`
	Repaired        bool     `json:"repaired"`
	Deep            bool     `json:"deep"`
	BytesRead       int64    `json:"bytes_read"`
	BytesDownloaded int64    `json:"bytes_downloaded"`
	Problems        []string `json:"problems,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.