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

bale

package module
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: MIT Imports: 10 Imported by: 0

README

Bale

Bale bundles OCI images and artifacts for registry and offline transfer.

Install

curl -fsSL https://bale.strio.dev/install.sh | sh
bale --version

See getting started for requirements, exact versions, the container image and Nix.

Quick start

Save this as bale.yaml:

include:
  - docker.io/library/busybox:1.37

Lock the image references, then download an offline archive:

bale create -f bale.yaml -t release:v1
bale save release:v1 -o release.tar

Follow the first-bundle tutorial to inspect, restore and deliver it. The documentation covers registry transfers, Helm, Flux and the Go SDK.

Development

Development uses the pinned Nix environment. See contributing for source builds, tests and documentation checks.

Bale is licensed under the MIT License.

Documentation

Overview

Package bale relocates immutable OCI artifact graphs and captures portable Bale bundles. Callers may supply registry references or their own ORAS content stores. The package preserves artifact bytes and delegates application-specific dependency discovery and reference rewriting to the calling application.

NewClient uses only explicitly supplied credentials and network options. Plan performs inspection without publishing; Execute returns confirmed publication locations, including partial progress when execution fails. Progress callbacks run synchronously and are serialized per client. Inspect, InspectLayout and InspectRoot verify existing bundles and expose captured inventory, dependency resolutions and selected declarations without refreshing selectors. Inspection reads the complete captured content graph.

Attach publishes a caller-prepared OCI manifest or index into its existing subject's repository and verifies referrer discovery. ListReferrers validates remote envelopes before returning them. Attachment schemas remain caller-owned. Registry publication through Attach, Create, Execute and Push serializes per client; waiting callers may cancel. Read-only registry operations and dry runs do not acquire the publication permit. Callers coordinate overlapping writes through other clients or processes.

Index

Examples

Constants

View Source 
const (
	DependencyArtifactType  = dependency.ArtifactType
	DependencyVersion       = dependency.Version
	DependencyMaxBytes      = dependency.MaxBytes
	DestinationArtifactType = destination.ArtifactType
	DestinationVersion      = destination.Version
	DestinationMaxBytes     = destination.MaxBytes
	PullLocked              = transport.PullLocked
	PullLatest              = transport.PullLatest
	BundleArtifactType      = bundle.BundleArtifactType
	MetadataArtifactType    = bundle.MetadataArtifactType
	MetadataMediaType       = bundle.MetadataMediaType
	MetadataDigestKey       = bundle.MetadataDigestKey
	MetadataVersion         = bundle.MetadataVersion
)

Variables

View Source 
var (
	ErrInvalid     = transport.ErrInvalid
	ErrUnsupported = transport.ErrUnsupported
	ErrNotFound    = transport.ErrNotFound
	ErrIntegrity   = transport.ErrIntegrity
	ErrConflict    = transport.ErrConflict
)

Functions

func EncodeDeliveryFile 

func EncodeDeliveryFile(file DeliveryFile) ([]byte, error)

EncodeDeliveryFile produces deterministic YAML without mutating the caller.

func EncodeDependencyDeclaration 

func EncodeDependencyDeclaration(declaration DependencyDeclaration) ([]byte, error)

EncodeDependencyDeclaration validates and deterministically encodes inclusion metadata. It defaults an omitted version and encodes nil dependencies as [].

func EncodeDestinationRecord 

func EncodeDestinationRecord(record DestinationRecord) ([]byte, error)

EncodeDestinationRecord validates and deterministically encodes destination metadata. It does not verify availability or publish the referenced content.

Types

type ArchiveResult 

type ArchiveResult = transport.ArchiveResult

type ArtifactChange 

type ArtifactChange = transport.ArtifactChange

type ArtifactID 

type ArtifactID = transport.ArtifactID

type Association 

type Association = bundle.Association

type AttachRequest 

type AttachRequest = transport.AttachRequest

func PrepareDependencyDeclaration 

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

PrepareDependencyDeclaration creates a deterministic, metadata-only OCI attachment for an already pinned subject. It neither reads subject.Store nor resolves the subject or declared dependencies. Pass its result to Client.Attach to publish it to the subject's repository.

type AttachResult 

type AttachResult = transport.AttachResult

type BundleRoot 

type BundleRoot = bundle.Root

type CaptureState 

type CaptureState = transport.CaptureState

type Client 

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

Client transports immutable OCI graphs and Bale bundles. Authentication, network policy, and progress reporting are supplied by its caller. Registry publication through Attach, Create, Execute, and Push is serialized per client; callers coordinate overlapping publication by other clients or processes.

func NewClient 

func NewClient(options ClientOptions) (*Client, error)

NewClient constructs a client without reading ambient credential files.

func (*Client) Attach 

func (c *Client) Attach(ctx context.Context, request AttachRequest) (AttachResult, error)

Attach publishes a prepared immutable OCI attachment to its existing subject's repository and verifies discoverability. The result retains completed work on failure. It shares this client's cancellable publication permit with Create, Execute, and Push.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, recipe Recipe, storageReference string, options CreateOptions) (CreateResult, error)

Create captures a normalized recipe as a registry-native bundle. On failure, its result retains completed work; Published confirms completion-tag readback.

func (*Client) CreateInto 

func (c *Client) CreateInto(ctx context.Context, recipe Recipe, target content.Storage, options CreateOptions) (CreateResult, *CaptureState, error)

CreateInto locks a recipe into caller-owned OCI storage without fetching ordinary payloads. The caller publishes its own root references only after success and retains the returned local source state for missing payloads.

func (*Client) CreateLayout 

func (c *Client) CreateLayout(ctx context.Context, recipe Recipe, layoutPath string, options CreateOptions) (CreateResult, error)

CreateLayout captures a recipe directly into a new local OCI directory. Source registries are read only. LayoutPath confirms completed local output; Published remains reserved for registry publication. DryRun writes no layout.

func (*Client) CreateLocal 

func (c *Client) CreateLocal(ctx context.Context, recipe Recipe, path string, options CreateOptions) (CreateResult, error)

CreateLocal locks a recipe into a source-dependent local metadata capture. It retains manifests and interpreted metadata without downloading ordinary image payloads. Discovery may read chart or plugin bytes. Save or Push reads missing payloads by pinned digest; neither refreshes tags nor runs plugins.

func (*Client) Diff 

func (c *Client) Diff(ctx context.Context, beforeRef, afterRef string) (DiffResult, error)

Diff compares captured metadata from two registry bundles. Each reference is resolved once; identical reference strings share one inspection. It does not refresh source selectors, discover attachments, execute plugins, or publish. Opaque payloads are not read or checked for availability or integrity.

func (*Client) DiffLayouts 

func (c *Client) DiffLayouts(ctx context.Context, beforePath, afterPath string) (DiffResult, error)

DiffLayouts compares two single-root OCI bundle layouts without network access or writes. It validates envelopes and interpreted metadata, including nested bundle metadata, without checking opaque payloads.

func (*Client) DiffRoots 

func (c *Client) DiffRoots(ctx context.Context, beforeRoot, afterRoot Root) (DiffResult, error)

DiffRoots compares captured metadata in caller-owned stores without closing or modifying them. Detailed observations describe each root bundle; nested bundles can be compared separately by their pinned descriptors.

func (*Client) Execute 

func (c *Client) Execute(ctx context.Context, plan *Plan) (Result, error)

Execute publishes an in-memory plan and reports confirmed relocations.

func (*Client) ExportDelivery 

func (c *Client) ExportDelivery(ctx context.Context, reference string) (DeliveryFile, error)

ExportDelivery resolves a registry bundle once and exports its default paths after validating captured manifests, indexes, and Bale metadata. It does not fetch or check opaque application configs or payloads, discover referrers, or resolve original source selectors. It does not prove payload availability or integrity; use Inspect for complete captured-graph verification.

func (*Client) ExportDeliveryLayout 

func (c *Client) ExportDeliveryLayout(ctx context.Context, path string) (DeliveryFile, error)

ExportDeliveryLayout exports default paths from a verified local bundle, without network access or changes to the layout.

func (*Client) ExportDeliveryRoot 

func (c *Client) ExportDeliveryRoot(ctx context.Context, root Root) (DeliveryFile, error)

ExportDeliveryRoot exports a pinned bundle in caller-owned read-only storage.

func (*Client) Inspect 

func (c *Client) Inspect(ctx context.Context, reference string) (InspectResult, error)

Inspect resolves a remote bundle once and verifies its full captured graph. It does not refresh source selectors or discover additional referrers.

func (*Client) InspectDependencies 

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

InspectDependencies pins a registry subject once and reads all its verified dependency declarations. It neither resolves declared dependencies nor reads application payloads. An error returns no declarations; an empty inventory returns a nonnil empty slice.

func (*Client) InspectDestinations 

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

InspectDestinations pins a subject once and reads its verified destination records without resolving their locations or reading application payloads. Local identifies records for this repository and digest, not a newest record. Callers select the intended source, bundle, capture and declaration explicitly.

func (*Client) InspectDestinationsWithOptions 

func (c *Client) InspectDestinationsWithOptions(ctx context.Context, reference string, options DestinationInspectionOptions) ([]InspectedDestination, error)

InspectDestinationsWithOptions bounds aggregate metadata reads and referrer inventory counts. An error returns no partial records; zero limits preserve the existing InspectDestinations behavior.

func (*Client) InspectLayout 

func (c *Client) InspectLayout(ctx context.Context, layoutPath string) (InspectResult, error)

InspectLayout verifies local bundle content without network access or writes. Marked metadata-only captures verify their interpreted graph and report MetadataOnly; complete layouts additionally verify every payload.

func (*Client) InspectRoot 

func (c *Client) InspectRoot(ctx context.Context, root Root) (InspectResult, error)

InspectRoot verifies a pinned bundle in a caller-owned content store, without resolving references, discovering referrers, or taking ownership of the store.

func (*Client) ListReferrers 

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

ListReferrers returns validated, sorted referrers of a pinned subject. It makes no registry writes. On error, the result may contain validated earlier entries.

func (*Client) Load 

func (c *Client) Load(ctx context.Context, archivePath, layoutPath string) (ArchiveResult, error)

Load restores a verified OCI tar archive to a new bundle layout directory. It leaves the archive unchanged and performs no network or plugin operations.

func (*Client) LoadFrom 

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

LoadFrom verifies an OCI tar from in before publishing a new layout directory. It stages the stream for random access and does not close the caller's reader.

func (*Client) MaterializeInto 

func (c *Client) MaterializeInto(ctx context.Context, root Root, state *CaptureState, target content.Storage) (PullResult, error)

MaterializeInto completes a pinned local capture in caller-owned OCI storage. Missing payloads use only the captured sources; tags and plugins are unchanged.

func (*Client) Plan 

func (c *Client) Plan(ctx context.Context, request TransferRequest) (*Plan, error)

Plan inspects the graph and validates relocation without publishing content.

func (*Client) PlanPush 

func (c *Client) PlanPush(ctx context.Context, layoutPath, destination string, options PushOptions) (DeliveryPlan, error)

PlanPush validates a bundle layout and its destination repository mapping.

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, reference, layoutPath string, mode PullMode) (PullResult, error)

Pull materializes a bundle as a complete local OCI layout. Failed pulls retain completed download accounting; LayoutPath is set only after atomic publication.

func (*Client) PullInto 

func (c *Client) PullInto(ctx context.Context, reference string, target content.Storage, mode PullMode, options PullOptions) (PullResult, error)

PullInto downloads a registry bundle into caller-owned OCI storage. Existing blobs are reused, and the complete graph is verified before success.

func (*Client) PullWithOptions 

func (c *Client) PullWithOptions(ctx context.Context, reference, layoutPath string, mode PullMode, options PullOptions) (PullResult, error)

PullWithOptions explicitly permits configured producers during latest refresh. Locked pulls never execute plugins.

func (*Client) Push 

func (c *Client) Push(ctx context.Context, plan DeliveryPlan) (PushResult, error)

Push publishes a validated bundle delivery plan. Tags and Relocations report confirmed publications, including on failure. Repositories, RepositoryMap, and Referrers describe the planned delivery and do not imply successful publication.

func (*Client) Resolve 

func (c *Client) Resolve(ctx context.Context, reference string) (Root, error)

Resolve pins a registry reference and returns its content source.

func (*Client) Save 

func (c *Client) Save(ctx context.Context, layoutPath, archivePath string) (ArchiveResult, error)

Save writes a verified bundle to a new, deterministic OCI tar archive. Metadata-only captures fetch missing payloads from their pinned sources; complete layouts are saved offline. The source is unchanged, the bundle digest is preserved, and plugins are never executed.

func (*Client) SaveTo 

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

SaveTo writes a verified OCI tar to out without closing it. The bundle digest is preserved; a failed stream can contain a partial archive.

func (*Client) UpdateDelivery 

func (c *Client) UpdateDelivery(ctx context.Context, beforeRef, afterRef string, file DeliveryFile) (DeliveryUpdateResult, error)

UpdateDelivery carries explicit delivery paths between captured registry snapshots. Exact identities and unambiguous selector changes preserve paths. It validates interpreted metadata without reading opaque payloads or refreshing sources. Identical references share one pinned read. Conflicts return diagnostics with ErrConflict and no candidate Delivery; other failures return an empty result.

func (*Client) UpdateDeliveryLayouts 

func (c *Client) UpdateDeliveryLayouts(ctx context.Context, beforePath, afterPath string, file DeliveryFile) (DeliveryUpdateResult, error)

UpdateDeliveryLayouts updates paths using two local OCI bundle layouts without network access or writes. Only envelopes and interpreted metadata are read; this does not prove opaque payload availability or integrity.

func (*Client) UpdateDeliveryRoots 

func (c *Client) UpdateDeliveryRoots(ctx context.Context, beforeRoot, afterRoot Root, file DeliveryFile) (DeliveryUpdateResult, error)

UpdateDeliveryRoots compares pinned snapshots in caller-owned read-only stores without closing them. Inventories and selector sets include nested bundles.

type ClientOptions 

type ClientOptions = transport.Options

type CreateOptions 

type CreateOptions = transport.CreateOptions

type CreateResult 

type CreateResult = transport.CreateResult

type DeclarationChange 

type DeclarationChange = transport.DeclarationChange

type DeclarationState 

type DeclarationState = transport.DeclarationState

type DeliveryArtifact 

type DeliveryArtifact = deliveryfile.Artifact

type DeliveryFile 

type DeliveryFile = deliveryfile.File

func DecodeDeliveryFile 

func DecodeDeliveryFile(data []byte) (DeliveryFile, error)

DecodeDeliveryFile parses strict YAML path overrides bound to a bundle digest.

type DeliveryPathChange 

type DeliveryPathChange = transport.DeliveryPathChange

type DeliveryPathConflict 

type DeliveryPathConflict = transport.DeliveryPathConflict

type DeliveryPlan 

type DeliveryPlan = transport.DeliveryPlan

type DeliveryRepository 

type DeliveryRepository = transport.DeliveryRepository

type DeliveryUpdateResult 

type DeliveryUpdateResult = transport.DeliveryUpdateResult

type DependencyDeclaration 

type DependencyDeclaration = dependency.Declaration

func DecodeDependencyDeclaration 

func DecodeDependencyDeclaration(raw []byte) (DependencyDeclaration, error)

DecodeDependencyDeclaration strictly validates declaration JSON and returns canonical, deduplicated entries. It does not resolve any references.

func ParseDependencyDeclaration 

func ParseDependencyDeclaration(data []byte) (DependencyDeclaration, error)

ParseDependencyDeclaration parses strict user-authored YAML with an implicit schema version, using the same selector semantics as registry JSON. References are normalized and deduplicated without network access.

type DependencyPolicy 

type DependencyPolicy = dependency.Policy

type DependencyReference 

type DependencyReference = dependency.Reference

type DependencyResolution 

type DependencyResolution = bundle.DependencyResolution

type DependencySelector 

type DependencySelector = dependency.Selector

type DestinationAttachment 

type DestinationAttachment = transport.DestinationAttachment

type DestinationDeclaration 

type DestinationDeclaration = destination.Declaration

type DestinationDependency 

type DestinationDependency = destination.Dependency

type DestinationInspectionOptions 

type DestinationInspectionOptions = transport.DestinationInspectionOptions

type DestinationRecord 

type DestinationRecord = destination.Record

func DecodeDestinationRecord 

func DecodeDestinationRecord(raw []byte) (DestinationRecord, error)

DecodeDestinationRecord strictly validates registry JSON and returns its canonical records without making network requests.

type DestinationResolution 

type DestinationResolution = destination.Resolution

type DiffResult 

type DiffResult = transport.DiffResult

type Error 

type Error = transport.Error

type InspectResult 

type InspectResult = transport.InspectResult

type InspectedDeclaration 

type InspectedDeclaration = transport.InspectedDeclaration

type InspectedDestination 

type InspectedDestination = transport.InspectedDestination

type ListReferrersOptions 

type ListReferrersOptions = transport.ListReferrersOptions

type Metadata 

type Metadata = bundle.Metadata

type Origin 

type Origin = bundle.Origin

type Plan 

type Plan = transport.TransferPlan

type PlanView 

type PlanView = transport.PlanView

type Plugin 

type Plugin = config.Plugin

type PluginBlob 

type PluginBlob = config.PluginBlob

type PluginRequest 

type PluginRequest = transport.PluginRequest

type PluginResolution 

type PluginResolution = bundle.PluginResolution

type PluginRunner 

type PluginRunner = transport.PluginRunner

type Progress 

type Progress = transport.Progress

type PullMode 

type PullMode = transport.PullMode

type PullOptions 

type PullOptions = transport.PullOptions

type PullResult 

type PullResult = transport.PullResult

type PushOptions 

type PushOptions = transport.PushOptions

type PushResult 

type PushResult = transport.PushResult

type Recipe 

type Recipe = config.Recipe

func NormalizeRecipe 

func NormalizeRecipe(recipe Recipe) (Recipe, error)

NormalizeRecipe applies defaults and validates a deep copy of a Go recipe.

Example 
package main

import (
	"fmt"

	"github.com/strio-dev/bale"
)

func main() {
	recipe, err := bale.NormalizeRecipe(bale.Recipe{
		Include: []bale.Selection{{Ref: "registry.example.com/team/component:v1"}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(recipe.Include[0].Referrers.Include)
}

Output:
all

func ParseRecipe 

func ParseRecipe(data []byte) (Recipe, error)

ParseRecipe parses strict YAML and resolves authoring defaults.

type ReferrerPage added in v0.1.2 

type ReferrerPage = transport.ReferrerPage

type ReferrerPolicy 

type ReferrerPolicy = config.Policy

type RegistryBlobStore added in v0.1.2 

type RegistryBlobStore = transport.RegistryBlobStore

type RegistryRepository added in v0.1.2 

type RegistryRepository = transport.RegistryRepository

type Relocation 

type Relocation = transport.Relocation

type Relocations 

type Relocations = transport.Relocations

type RepositoryFactory added in v0.1.2 

type RepositoryFactory = transport.RepositoryFactory

type RequiredReferrer 

type RequiredReferrer = config.RequiredReferrer

type ResolutionChange 

type ResolutionChange = transport.ResolutionChange

type ResolvedDependency 

type ResolvedDependency = bundle.ResolvedDependency

type Result 

type Result = transport.Result

type Root 

type Root = transport.Root

type Selection 

type Selection = config.Selection

type Snapshot 

type Snapshot = bundle.Snapshot

type Stats 

type Stats = transport.Stats

type Tag 

type Tag = transport.Tag

type TransferRequest 

type TransferRequest = transport.TransferRequest

Source Files

View all Source files

Directories

Path Synopsis
cmd
bale command
internal
bundle
Package bundle implements Bale's registry-native OCI snapshot format.
 Package bundle implements Bale's registry-native OCI snapshot format.
config
Package config parses the portable, destination-free Bale recipe.
 Package config parses the portable, destination-free Bale recipe.
deliveryfile
Package deliveryfile defines editable, bundle-bound OCI publication paths.
 Package deliveryfile defines editable, bundle-bound OCI publication paths.
dependency
Package dependency defines generic OCI dependency inclusion declarations.
 Package dependency defines generic OCI dependency inclusion declarations.
destination
Package destination describes confirmed artifact delivery locations.
 Package destination describes confirmed artifact delivery locations.
jsonutil
Package jsonutil validates JSON distinctions that struct decoding would discard.
 Package jsonutil validates JSON distinctions that struct decoding would discard.
localstore
Package localstore owns Bale's shared OCI content and local root references.
 Package localstore owns Bale's shared OCI content and local root references.
pluginoci
Package pluginoci reads and writes archive-based OCI discovery plugins.
 Package pluginoci reads and writes archive-based OCI discovery plugins.
transport
Package transport captures and delivers complete, immutable OCI graphs.
 Package transport captures and delivers complete, immutable OCI graphs.
wasm
Package wasm executes portable WASI command modules behind an internal engine boundary.
 Package wasm executes portable WASI command modules behind an internal engine boundary.
wasmtest
Package wasmtest builds tiny, self-contained WASI command fixtures for tests.
 Package wasmtest builds tiny, self-contained WASI command fixtures for tests.
yamlutil
Package yamlutil validates the strict YAML subset used by authoring files.
 Package yamlutil validates the strict YAML subset used by authoring files.
Package plugin runs portable WASIp1 dependency producers.
 Package plugin runs portable WASIp1 dependency producers.
Package store manages local Bale bundles by name or immutable ID in one OCI content store.
 Package store manages local Bale bundles by name or immutable ID in one OCI content store.
tests
kubernetes/fixture command
Command fixture prepares runnable OCI artifacts for the Kubernetes acceptance test.
 Command fixture prepares runnable OCI artifacts for the Kubernetes acceptance test.
kubernetes/workload command

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.