Help us shape the future of Go! Take the 2026 Go Developer Survey

transport

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package transport captures and delivers complete, immutable OCI graphs.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalid     = errors.New("invalid request")
	ErrUnsupported = errors.New("unsupported operation")
	ErrNotFound    = errors.New("artifact not found")
	ErrIntegrity   = errors.New("artifact integrity failure")
	ErrConflict    = errors.New("publication conflict")
)

Functions

func ValidateCaptureState 

func ValidateCaptureState(ctx context.Context, store content.ReadOnlyStorage, snapshot bundle.Snapshot, state CaptureState) error

ValidateCaptureState checks source locators against locally verified capture metadata. Opaque payloads already present in a shared store remain valid.

Types

type ArchiveResult 

type ArchiveResult struct {
	Descriptor  v1.Descriptor `json:"descriptor"`
	LayoutPath  string        `json:"layoutPath,omitempty"`
	ArchivePath string        `json:"archivePath,omitempty"`
}

ArchiveResult identifies the unchanged bundle carried by an OCI layout tar.

type ArtifactChange 

type ArtifactChange struct {
	Change     string        `json:"change"`
	Repository string        `json:"repository"`
	Descriptor v1.Descriptor `json:"descriptor"`
}

ArtifactChange identifies a manifest or index added to or removed from a source repository. Configs and payload blobs are not artifacts.

type ArtifactID 

type ArtifactID struct {
	Repository string        `json:"repository"`
	Digest     digest.Digest `json:"digest"`
}

ArtifactID identifies an immutable artifact in a particular repository.

type AttachRequest 

type AttachRequest struct {
	Subject    string
	Descriptor v1.Descriptor
	Store      content.ReadOnlyStorage
}

AttachRequest supplies a prepared OCI manifest or index with a subject. Store must contain its strong dependency closure and remains owned by the caller.

func PrepareDependencyDeclaration 

func PrepareDependencyDeclaration(ctx context.Context, subject Root, declaration dependency.Declaration) (AttachRequest, error)

PrepareDependencyDeclaration prepares a local, deterministic inclusion attachment.

type AttachResult 

type AttachResult struct {
	Repository   string        `json:"repository"`
	Subject      v1.Descriptor `json:"subject"`
	Descriptor   v1.Descriptor `json:"descriptor"`
	Stats        Stats         `json:"stats"`
	Published    bool          `json:"published"`
	Discoverable bool          `json:"discoverable"`
}

AttachResult distinguishes complete publication from confirmed discovery. Both flags retain confirmed work when Attach fails. Stats counts completed SDK copy operations; interrupted inventory updates can leave accepted manifest writes outside that accounting.

type CaptureState 

type CaptureState struct {
	SchemaVersion int                      `json:"schemaVersion"`
	Bundle        digest.Digest            `json:"bundle"`
	Sources       map[digest.Digest]string `json:"sources"`
}

CaptureState records pinned payload locations outside the transferable bundle graph. Locators remain valid as a shared store hydrates their payloads.

type CreateOptions 

type CreateOptions struct {
	DryRun         bool
	ExportDelivery bool
}

type CreateResult 

type CreateResult struct {
	MetadataOnly bool               `json:"metadataOnly,omitempty"`
	LayoutPath   string             `json:"layoutPath,omitempty"`
	Published    bool               `json:"published"`
	Descriptor   v1.Descriptor      `json:"descriptor"`
	Metadata     bundle.Metadata    `json:"metadata"`
	Stats        Stats              `json:"stats"`
	DryRun       bool               `json:"dryRun"`
	Delivery     *deliveryfile.File `json:"delivery,omitempty"`
}

type DeclarationChange 

type DeclarationChange struct {
	Subject string             `json:"subject"`
	Before  []DeclarationState `json:"before"`
	After   []DeclarationState `json:"after"`
}

DeclarationChange compares observation sets for a stable subject selector. Subjects without a captured selector use repository@digest instead.

type DeclarationState 

type DeclarationState struct {
	Policy     dependency.Policy `json:"policy"`
	Outcome    string            `json:"outcome"`
	Descriptor *v1.Descriptor    `json:"descriptor,omitempty"`
	Context    string            `json:"context,omitempty"`
}

DeclarationState records an observed dependency policy and its outcome.

type DeliveryPathChange 

type DeliveryPathChange struct {
	Change string `json:"change"`
	Before string `json:"before,omitempty"`
	After  string `json:"after,omitempty"`
	Path   string `json:"path,omitempty"`
}

DeliveryPathChange identifies a preserved, moved, defaulted, or removed path.

type DeliveryPathConflict 

type DeliveryPathConflict struct {
	Reason    string                  `json:"reason"`
	Sources   []deliveryfile.Artifact `json:"sources"`
	Targets   []string                `json:"targets"`
	Selectors []string                `json:"selectors"`
}

DeliveryPathConflict records the explicit assignments and selector evidence that prevent a safe update.

type DeliveryPlan 

type DeliveryPlan struct {
	MetadataOnly bool `json:"metadataOnly,omitempty"`

	Destinations []DestinationAttachment `json:"destinations"`
	// Relocations lists planned canonical placements; Push confirms them after verification.
	Relocations   Relocations          `json:"relocations"`
	LayoutPath    string               `json:"layoutPath"`
	Destination   string               `json:"destination"`
	Descriptor    v1.Descriptor        `json:"descriptor"`
	Repositories  []DeliveryRepository `json:"repositories"`
	Tags          []Tag                `json:"tags"`
	RepositoryMap map[string]string    `json:"repositoryMap"`
	Referrers     []bundle.Association `json:"referrers"`
	// contains filtered or unexported fields
}

type DeliveryRepository 

type DeliveryRepository struct {
	Repository string          `json:"repository"`
	Roots      []v1.Descriptor `json:"roots"`
}

type DeliveryUpdateResult 

type DeliveryUpdateResult struct {
	Before    v1.Descriptor          `json:"before"`
	After     v1.Descriptor          `json:"after"`
	Delivery  *deliveryfile.File     `json:"delivery,omitempty"`
	Changes   []DeliveryPathChange   `json:"changes"`
	Conflicts []DeliveryPathConflict `json:"conflicts"`
}

DeliveryUpdateResult reports the path assignments carried into a refreshed bundle. Delivery is absent when any assignment is ambiguous.

type DestinationAttachment 

type DestinationAttachment struct {
	Repository string             `json:"repository"`
	Subject    v1.Descriptor      `json:"subject"`
	Descriptor v1.Descriptor      `json:"descriptor"`
	Record     destination.Record `json:"record"`
}

type DestinationInspectionOptions 

type DestinationInspectionOptions struct {
	MaxMetadataBytes int64
	MaxReferrers     int
}

DestinationInspectionOptions bounds a single read-only inspection. Zero limits preserve existing behavior. Metadata bytes include inventory responses and attachment manifest/config/payload reads, including validation rereads.

type DiffResult 

type DiffResult struct {
	Before        v1.Descriptor       `json:"before"`
	After         v1.Descriptor       `json:"after"`
	Changed       bool                `json:"changed"`
	RecipeChanged bool                `json:"recipeChanged"`
	Artifacts     []ArtifactChange    `json:"artifacts"`
	Resolutions   []ResolutionChange  `json:"resolutions"`
	Declarations  []DeclarationChange `json:"declarations"`
}

DiffResult compares the captured inventories of two inspected bundles. Changes belong to the root bundle; nested bundles can be compared separately.

type Error 

type Error struct {
	Op         string
	Repository string
	Descriptor v1.Descriptor
	Kind       error
	Cause      error
}

Error identifies the operation and artifact while preserving its original cause.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

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

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type InspectResult 

type InspectResult struct {
	MetadataOnly bool                   `json:"metadataOnly,omitempty"`
	Descriptor   v1.Descriptor          `json:"descriptor"`
	Metadata     bundle.Metadata        `json:"metadata"`
	Declarations []InspectedDeclaration `json:"declarations"`
}

InspectResult contains verified captured metadata, without refreshing selectors or discovering additional referrers. Declarations belong to the root bundle; nested native bundles can be inspected separately using their pinned roots.

type InspectedDeclaration 

type InspectedDeclaration struct {
	Repository  string                 `json:"repository"`
	Subject     v1.Descriptor          `json:"subject"`
	Descriptor  v1.Descriptor          `json:"descriptor"`
	Declaration dependency.Declaration `json:"declaration"`
}

InspectedDeclaration pairs a verified declaration with its pinned subject and repository. InspectDependencies reads live attachments; bundle inspection returns declarations selected in that bundle's captured inventory.

type InspectedDestination 

type InspectedDestination struct {
	Repository string             `json:"repository"`
	Subject    v1.Descriptor      `json:"subject"`
	Descriptor v1.Descriptor      `json:"descriptor"`
	Record     destination.Record `json:"record"`
	Local      bool               `json:"local"`
}

InspectedDestination pairs a verified record with its exact registry subject. Local means the record's destination names this repository and digest. It makes no claim about recency, bundle completion or current target availability.

type ListReferrersOptions 

type ListReferrersOptions struct {
	ArtifactType string
}

type Options 

type Options struct {
	PluginRunner        PluginRunner
	PlainHTTPRegistries []string
	HTTPClient          *http.Client
	Credentials         auth.CredentialFunc
	OnProgress          func(Progress)
}

type PlanView 

type PlanView struct {
	Destination   string               `json:"destination"`
	Repositories  []DeliveryRepository `json:"repositories"`
	RepositoryMap map[string]string    `json:"repositoryMap"`
	Tags          []Tag                `json:"tags"`
	Referrers     []bundle.Association `json:"referrers"`
	Relocations   Relocations          `json:"relocations"`
}

type PluginRequest 

type PluginRequest struct {
	ModulePath string
	Input      json.RawMessage
}

PluginRequest supplies a verified portable WASI module and its JSON input.

type PluginRunner 

type PluginRunner func(context.Context, PluginRequest) (dependency.Declaration, error)

PluginRunner is a caller-owned dependency producer; transport is engine agnostic.

type Progress 

type Progress struct {
	// Input identifies the zero-based recipe selection; nil marks non-recipe work.
	Input      *int
	Reference  string
	Plugin     string
	Operation  string
	Repository string
	Descriptor v1.Descriptor
	Stats      Stats
}

type PullMode 

type PullMode string
const (
	PullLocked PullMode = "locked"
	PullLatest PullMode = "latest"
)

type PullOptions 

type PullOptions struct {
	AllowPlugins bool
}

PullOptions grants execution only for this explicit latest refresh.

type PullResult 

type PullResult struct {
	Descriptor v1.Descriptor `json:"descriptor"`
	LayoutPath string        `json:"layoutPath"`
	Mode       PullMode      `json:"mode"`
	Stats      Stats         `json:"stats"`
}

type PushOptions 

type PushOptions struct {
	RepositoryMap map[string]string
	Delivery      *deliveryfile.File
}

type PushResult 

type PushResult struct {
	Destinations  []AttachResult       `json:"destinations"`
	Relocations   Relocations          `json:"relocations"`
	Descriptor    v1.Descriptor        `json:"descriptor"`
	Stats         Stats                `json:"stats"`
	Warnings      []string             `json:"warnings"`
	Destination   string               `json:"destination"`
	Repositories  []DeliveryRepository `json:"repositories"`
	RepositoryMap map[string]string    `json:"repositoryMap"`
	Tags          []Tag                `json:"tags"`
	Referrers     []bundle.Association `json:"referrers"`
}

type Relocation 

type Relocation struct {
	Source      ArtifactID    `json:"source"`
	Destination ArtifactID    `json:"destination"`
	Descriptor  v1.Descriptor `json:"descriptor"`
}

type Relocations 

type Relocations []Relocation

func (Relocations) Lookup 

func (r Relocations) Lookup(id ArtifactID) (Relocation, bool)

type ResolutionChange 

type ResolutionChange struct {
	Kind   string          `json:"kind"`
	Ref    string          `json:"ref"`
	Before []v1.Descriptor `json:"before"`
	After  []v1.Descriptor `json:"after"`
}

ResolutionChange compares the descriptor sets pinned by an original input, dependency, or plugin selector. Repeated aliases and profiles form one set.

type Result 

type Result struct {
	Relocations Relocations `json:"relocations"`
	Tags        []Tag       `json:"tags"`
	Stats       Stats       `json:"stats"`
	Warnings    []string    `json:"warnings"`
}

type Root 

type Root struct {
	Repository     string
	Descriptor     v1.Descriptor
	Store          content.ReadOnlyStorage
	Aliases        []string
	Referrers      config.Policy
	ReferrerSource registry.ReferrerLister
}

type Service 

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

func NewService 

func NewService(opts Options) (*Service, error)

func (*Service) Attach 

func (s *Service) Attach(ctx context.Context, request AttachRequest) (AttachResult, error)

func (*Service) Create 

func (s *Service) Create(ctx context.Context, recipe config.Recipe, storageRef string, opts CreateOptions) (result CreateResult, retErr error)

func (*Service) CreateInto 

func (s *Service) CreateInto(ctx context.Context, recipe config.Recipe, target content.Storage, opts CreateOptions) (result CreateResult, state *CaptureState, retErr error)

CreateInto retains a source-dependent metadata capture in caller-owned storage. The caller owns publication of its root reference and coordination with GC. Failed calls may leave unreferenced verified objects in target.

func (*Service) CreateLayout 

func (s *Service) CreateLayout(ctx context.Context, recipe config.Recipe, layoutPath string, opts CreateOptions) (result CreateResult, retErr error)

CreateLayout captures the same immutable graph as Create directly into a new OCI layout, without requiring or publishing to a holding registry.

func (*Service) CreateLocal 

func (s *Service) CreateLocal(ctx context.Context, recipe config.Recipe, path string, opts CreateOptions) (result CreateResult, retErr error)

CreateLocal locks a recipe into a source-dependent local metadata capture. It retains verified envelopes and interpreted/generated metadata, while ordinary application payloads remain at their pinned source repositories.

func (*Service) Diff 

func (s *Service) Diff(ctx context.Context, beforeRef, afterRef string) (DiffResult, error)

Diff pins each remote operand once and compares captured metadata. Identical reference strings reuse one inspection, including one mutable-tag resolution. Opaque application payloads are neither read nor checked for availability.

func (*Service) DiffLayouts 

func (s *Service) DiffLayouts(ctx context.Context, beforePath, afterPath string) (DiffResult, error)

DiffLayouts compares completed single-root OCI bundle layouts without writes. It validates envelopes and interpreted metadata, but not opaque payloads.

func (*Service) DiffRoots 

func (s *Service) DiffRoots(ctx context.Context, beforeRoot, afterRoot Root) (DiffResult, error)

DiffRoots compares pinned bundles in caller-owned stores. It does not close stores, discover referrers, refresh source selectors, run plugins, or publish.

func (*Service) Execute 

func (s *Service) Execute(ctx context.Context, plan *TransferPlan) (result Result, retErr error)

Execute publishes pinned bytes, reporting only verified relocations and aliases.

func (*Service) ExportDelivery 

func (s *Service) ExportDelivery(ctx context.Context, reference string) (deliveryfile.File, error)

func (*Service) ExportDeliveryLayout 

func (s *Service) ExportDeliveryLayout(ctx context.Context, path string) (deliveryfile.File, error)

func (*Service) ExportDeliveryRoot 

func (s *Service) ExportDeliveryRoot(ctx context.Context, root Root) (deliveryfile.File, error)

func (*Service) Inspect 

func (s *Service) Inspect(ctx context.Context, reference string) (InspectResult, error)

Inspect pins a remote reference once and verifies only its captured graph.

func (*Service) InspectDependencies 

func (s *Service) InspectDependencies(ctx context.Context, subjectReference string) ([]InspectedDeclaration, error)

InspectDependencies discovers declarations of one pinned registry subject. It reuses capture's metadata limits and declaration validation without selecting a policy, expanding references, or verifying application payloads.

func (*Service) InspectDestinations 

func (s *Service) InspectDestinations(ctx context.Context, subjectReference string) ([]InspectedDestination, error)

InspectDestinations reads current and carried historical destination records. It resolves only the subject, validates metadata and returns all records in digest order. Errors return no partial results; no targets are contacted.

func (*Service) InspectDestinationsWithOptions 

func (s *Service) InspectDestinationsWithOptions(ctx context.Context, subjectReference string, options DestinationInspectionOptions) ([]InspectedDestination, error)

InspectDestinationsWithOptions applies explicit aggregate metadata and inventory limits before retaining descriptors or fetching additional attachment content. Errors return no partial results. The subject is resolved once.

func (*Service) InspectLayout 

func (s *Service) InspectLayout(ctx context.Context, path string) (InspectResult, error)

InspectLayout reads a completed single-root OCI bundle layout without writes.

func (*Service) InspectRoot 

func (s *Service) InspectRoot(ctx context.Context, root Root) (InspectResult, error)

InspectRoot verifies a pinned bundle in a caller-owned store. It does not discover referrers, resolve source selectors, publish content, or close Store.

func (*Service) ListReferrers 

func (s *Service) ListReferrers(ctx context.Context, subjectReference string, options ListReferrersOptions) ([]v1.Descriptor, error)

ListReferrers pins the subject once, then validates every returned descriptor against its actual remote envelope. It returns no unverified inventory hints.

func (*Service) Load 

func (s *Service) Load(ctx context.Context, archivePath, layoutPath string) (result ArchiveResult, retErr error)

Load validates a portable OCI tar before publishing a complete local layout. The archive is staged privately: ORAS may reopen its path while walking the graph, and must not observe changes made to the caller's archive meanwhile.

func (*Service) LoadFrom 

func (s *Service) LoadFrom(ctx context.Context, in io.Reader, layoutPath string) (ArchiveResult, error)

LoadFrom stages the input once for ORAS random access, verifies the complete archive, and only then publishes a local layout. The caller owns the reader.

func (*Service) MaterializeInto 

func (s *Service) MaterializeInto(ctx context.Context, root Root, state *CaptureState, target content.Storage) (result PullResult, retErr error)

MaterializeInto copies a pinned local bundle into caller-owned storage, fetching only missing opaque payloads allowed by its validated capture state. Root.Store and target may be the same CAS. Tags and plugins are never revisited.

func (*Service) Plan 

func (s *Service) Plan(ctx context.Context, request TransferRequest) (*TransferPlan, error)

Plan captures immutable graph metadata and checks destinations without writing.

func (*Service) PlanPush 

func (s *Service) PlanPush(ctx context.Context, layoutPath, destination string, opts PushOptions) (result DeliveryPlan, retErr error)

func (*Service) Pull 

func (s *Service) Pull(ctx context.Context, bundleRef, layoutPath string, mode PullMode) (PullResult, error)

func (*Service) PullInto 

func (s *Service) PullInto(ctx context.Context, reference string, target content.Storage, mode PullMode, options PullOptions) (result PullResult, retErr error)

PullInto retrieves a complete bundle into caller-owned storage. The caller publishes its retained root only after this method succeeds and coordinates concurrent garbage collection. Failed calls may leave reusable CAS content.

func (*Service) PullWithOptions 

func (s *Service) PullWithOptions(ctx context.Context, bundleRef, layoutPath string, mode PullMode, options PullOptions) (result PullResult, retErr error)

func (*Service) Push 

func (s *Service) Push(ctx context.Context, plan DeliveryPlan) (result PushResult, retErr error)

func (*Service) Resolve 

func (s *Service) Resolve(ctx context.Context, reference string) (Root, error)

func (*Service) Save 

func (s *Service) Save(ctx context.Context, layoutPath, archivePath string) (result ArchiveResult, retErr error)

Save writes the required bundle closure as a deterministic, uncompressed OCI layout tar. Unrelated files in the input layout are never archived.

func (*Service) SaveTo 

func (s *Service) SaveTo(ctx context.Context, layoutPath string, out io.Writer) (ArchiveResult, error)

SaveTo writes the same verified OCI tar as Save directly to out. The caller owns the writer; a write failure may leave a partial archive in that stream.

func (*Service) UpdateDelivery 

func (s *Service) UpdateDelivery(ctx context.Context, beforeRef, afterRef string, file deliveryfile.File) (DeliveryUpdateResult, error)

UpdateDelivery carries delivery paths between captured remote bundles. Each operand is pinned once; identical reference strings reuse the same snapshot. Only envelopes and interpreted metadata are read, without refreshing source selectors, discovering referrers, executing plugins, or checking payloads.

func (*Service) UpdateDeliveryLayouts 

func (s *Service) UpdateDeliveryLayouts(ctx context.Context, beforePath, afterPath string, file deliveryfile.File) (DeliveryUpdateResult, error)

UpdateDeliveryLayouts reads completed single-root OCI bundle layouts without writes or network access. Missing opaque application payloads are permitted; captured envelopes, dependency declarations and nested metadata are verified.

func (*Service) UpdateDeliveryRoots 

func (s *Service) UpdateDeliveryRoots(ctx context.Context, beforeRoot, afterRoot Root, file deliveryfile.File) (DeliveryUpdateResult, error)

UpdateDeliveryRoots carries paths between pinned bundles in caller-owned stores. Stores remain open and unchanged. Nested captured inventories are included; opaque payload availability and integrity are not checked.

type Stats 

type Stats struct {
	Accounting              string `json:"accounting"`
	BlobBytesDownloaded     int64  `json:"blobBytesDownloaded"`
	BlobBytesUploaded       int64  `json:"blobBytesUploaded"`
	ManifestBytesDownloaded int64  `json:"manifestBytesDownloaded"`
	ManifestBytesUploaded   int64  `json:"manifestBytesUploaded"`
	BlobsMounted            int    `json:"blobsMounted"`
	ObjectsSkipped          int    `json:"objectsSkipped"`
}

Stats accounts for graph capture and copy operations, not total HTTP traffic. Download counts exclude verification and latest-mode inspection rereads. Upload counts include generated Bale JSON; registry API overhead is excluded.

type Tag 

type Tag struct {
	Repository string        `json:"repository"`
	Reference  string        `json:"reference"`
	Descriptor v1.Descriptor `json:"descriptor"`
}

type TransferPlan 

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

TransferPlan holds pinned graph metadata. It is executable only in this process. Caller-owned stores must remain available until Execute completes.

func (*TransferPlan) View 

func (p *TransferPlan) View() PlanView

type TransferRequest 

type TransferRequest struct {
	Roots         []Root
	Destination   string
	RepositoryMap map[string]string
}

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.