speccompiler

package
v0.1.18-rc9 Latest Latest
Warning

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

Go to latest
Published: Oct 6, 2026 License: MIT Imports: 20 Imported by: 0

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

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

func ArchiveShortHash(data []byte) string

computeArchiveShortHash computes the SHA256 of data and returns the short hash prefix.

func BundleCID

func BundleCID(data []byte) string

computeSpecBundleCID computes the content identifier for a spec bundle archive using the same scheme as the server (bafy-prefixed SHA256 prefix).

func IsEnvironmentPlaceholderName

func IsEnvironmentPlaceholderName(name string) bool

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 New

func New(opts Options) (*Compiler, error)

func (*Compiler) Build

func (c *Compiler) Build(ctx context.Context, specFile string, overrides Overrides) ([]byte, error)

Build loads a spec and compiles it into canonical JSON.

Processing order:

  1. Load and compose the spec, then select a step when requested
  2. Apply step environment overrides before source placeholder expansion
  3. Expand image and environment placeholders, then apply the optional overlay
  4. Apply top-level caller overrides and compile local file records
  5. 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 (c *Compiler) BuildSelected(ctx context.Context, specFile string, stepSelector string, overrides Overrides) ([]byte, error)

func (*Compiler) Normalize

func (c *Compiler) Normalize(ctx context.Context, data []byte, specBaseDir string) (json.RawMessage, error)

func (*Compiler) Validate

func (c *Compiler) Validate(data []byte, specBaseDir string) (json.RawMessage, error)

Validate validates a JSON/YAML spec without persisting bundles.

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 Overrides

type Overrides struct {
	Envs     []string
	StepEnvs map[string][]string
	Image    string
	Command  string
}

Overrides contains caller-supplied values that take precedence over source values.

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) Stat

func (s *RepositorySource) Stat(path string) (fs.FileInfo, 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL