Documentation
¶
Overview ¶
bundle.go provides deterministic archive primitives for file records.
Package speccompiler compiles authoring specs into canonical run snapshots. Specs use a single canonical shape:
- steps[] array with one entry per step (even single-step runs)
- global build gate policy under build_gate
The compiler resolves authoring-form in/out/home/tmp entries into canonical shortHash:dst form suitable for contract validation and run persistence.
Authoring input formats:
- in: src:dst (right-biased split, dst treated as /in-relative)
- out: src:dst (right-biased split, dst treated as /out-relative)
- home: src:dst{:ro} (right-biased split, dst is $HOME-relative)
- tmp: src:dst (right-biased split, dst treated as /tmp-relative or /tmp absolute)
After compilation, entries are rewritten to:
- in: shortHash:/in/dst
- out: shortHash:/out/dst
- home: shortHash:dst{:ro}
- tmp: shortHash:/tmp/dst
Index ¶
- func ApplyBuildGateForcedOverrides(spec json.RawMessage, overrides BuildGateForcedOverrides) (json.RawMessage, error)
- func ApplyStepEnvOverrides(spec json.RawMessage, overrides map[string][]string) (json.RawMessage, error)
- func ArchiveShortHash(data []byte) string
- func BundleCID(data []byte) string
- func IsArchiveShortHash(value string) bool
- func IsEnvironmentPlaceholderName(name string) bool
- type BuildGateForcedOverrides
- type BundleStore
- type Compiler
- func (c *Compiler) Build(ctx context.Context, specFile string, overrides Overrides) ([]byte, error)
- func (c *Compiler) BuildSelected(ctx context.Context, specFile string, stepSelector string, overrides Overrides) ([]byte, error)
- func (c *Compiler) Normalize(ctx context.Context, data []byte, specBaseDir string) (json.RawMessage, error)
- func (c *Compiler) Validate(data []byte, specBaseDir string) (json.RawMessage, error)
- func (c *Compiler) ValidateFile(path string) (json.RawMessage, error)
- type Options
- type Overrides
- type RepositorySource
- func (s *RepositorySource) Close() error
- func (s *RepositorySource) ReadDir(path string) ([]fs.DirEntry, error)
- func (s *RepositorySource) ReadFile(path string) ([]byte, error)
- func (s *RepositorySource) ResolveBaseDir(path string) (string, error)
- func (s *RepositorySource) ResolveFileRecord(path, baseDir string) (string, error)
- func (s *RepositorySource) ResolveReference(path, baseDir string) (string, error)
- func (s *RepositorySource) ResolveSpec(path string) (string, error)
- func (s *RepositorySource) Stat(path string) (fs.FileInfo, error)
- func (s *RepositorySource) WorkingDir() (string, error)
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyBuildGateForcedOverrides ¶
func ApplyBuildGateForcedOverrides(spec json.RawMessage, overrides BuildGateForcedOverrides) (json.RawMessage, error)
func ApplyStepEnvOverrides ¶
func ApplyStepEnvOverrides(spec json.RawMessage, overrides map[string][]string) (json.RawMessage, error)
func ArchiveShortHash ¶
computeArchiveShortHash computes the SHA256 of data and returns the short hash prefix.
func BundleCID ¶
computeSpecBundleCID computes the content identifier for a spec bundle archive using the same scheme as the server (bafy-prefixed SHA256 prefix).
func IsArchiveShortHash ¶
Types ¶
type BuildGateForcedOverrides ¶
type BuildGateForcedOverrides struct {
Pre *contracts.BuildGateStackConfig
Post *contracts.BuildGateStackConfig
}
func (BuildGateForcedOverrides) HasAny ¶
func (o BuildGateForcedOverrides) HasAny() bool
type BundleStore ¶
type BundleStore interface {
Ensure(ctx context.Context, cid string, archive []byte) (string, error)
}
BundleStore persists a content-addressed source archive and returns its ID.
type Compiler ¶
type Compiler struct {
// contains filtered or unexported fields
}
Compiler is safe for concurrent use when its supplied dependencies are safe.
func (*Compiler) Build ¶
Build loads a spec and compiles it into canonical JSON.
Processing order:
- Load and compose the spec, then select a step when requested
- Apply step environment overrides before source placeholder expansion
- Expand image and environment placeholders, then apply the optional overlay
- Apply top-level caller overrides and compile local file records
- Validate the current spec contract
Returns nil payload when neither a spec file nor overrides are provided.
Multi-step semantics (steps[] array):
- Each entry in steps[] represents a sequential transformation step.
- All steps share the same repository and global build_gate policy.
- Image and command overrides do not apply when len(steps) > 1.
func (*Compiler) BuildSelected ¶
func (*Compiler) ValidateFile ¶
func (c *Compiler) ValidateFile(path string) (json.RawMessage, error)
ValidateFile validates a JSON/YAML spec without persisting bundles.
type Options ¶
type Options struct {
Source Source
LookupEnv func(string) (string, bool)
ApplyOverlay func(map[string]any) error
Bundles BundleStore
}
Options supplies the caller-owned dependencies used during compilation.
type RepositorySource ¶
type RepositorySource struct {
// contains filtered or unexported fields
}
RepositorySource confines every file operation to one repository checkout.
func NewRepositorySource ¶
func NewRepositorySource(path string) (*RepositorySource, error)
func (*RepositorySource) Close ¶
func (s *RepositorySource) Close() error
func (*RepositorySource) ReadDir ¶
func (s *RepositorySource) ReadDir(path string) ([]fs.DirEntry, error)
func (*RepositorySource) ReadFile ¶
func (s *RepositorySource) ReadFile(path string) ([]byte, error)
func (*RepositorySource) ResolveBaseDir ¶
func (s *RepositorySource) ResolveBaseDir(path string) (string, error)
func (*RepositorySource) ResolveFileRecord ¶
func (s *RepositorySource) ResolveFileRecord(path, baseDir string) (string, error)
func (*RepositorySource) ResolveReference ¶
func (s *RepositorySource) ResolveReference(path, baseDir string) (string, error)
func (*RepositorySource) ResolveSpec ¶
func (s *RepositorySource) ResolveSpec(path string) (string, error)
func (*RepositorySource) WorkingDir ¶
func (s *RepositorySource) WorkingDir() (string, error)
type Source ¶
type Source interface {
ResolveSpec(path string) (string, error)
ResolveBaseDir(path string) (string, error)
ResolveReference(path, baseDir string) (string, error)
ResolveFileRecord(path, baseDir string) (string, error)
ReadFile(path string) ([]byte, error)
Stat(path string) (fs.FileInfo, error)
ReadDir(path string) ([]fs.DirEntry, error)
WorkingDir() (string, error)
}
Source owns path policy and file access for one compilation source.