bundle

Documentation

Index

• Constants
• Variables
• func ArtifactDigest(data []byte) string
• func CanonicalJSON(v any) ([]byte, error)
• func DescriptorDigest(raw []byte) string
• func IsDataArtifact(name string) bool
• func ModuleChecksum(module []byte) string
• func VerifyModuleChecksum(module []byte, expected string) error
• type ArtifactRef
• type Bundle
• type ChannelPointer
  • func ParseChannelPointer(data []byte) (ChannelPointer, error)
• type Descriptor
  • func NewDescriptor(identity ManifestIdentity, artifacts map[string][]byte) Descriptor
  • func ParseDescriptor(data []byte) (Descriptor, error)
  • func (d Descriptor) BundleID() (string, error)
  • func (d Descriptor) Verify(files map[string][]byte) error
• type Manifest
  • func ParseManifest(data []byte) (Manifest, error)
• type ManifestIdentity
• type Provenance
• type Revision
  • func ParseRevision(data []byte) (Revision, error)

Constants

const (
	ArtifactModule = "module.wasm"
	ArtifactTests  = "tests.yaml"
	// DataPrefix marks descriptor artifacts that are read-only data files
	// bundled with the rule and exposed to the guest via the data ABI.
	DataPrefix = "data/"
)

const ABIVersion = "switchboard/v4"

const DescriptorSchema = "switchboard.descriptor/v1"

const RevisionSchema = "switchboard.revision/v1"

Variables

var ErrInvalid = errors.New("invalid bundle")

ErrInvalid marks a bundle that can never activate as-is; the reconciler quarantines it instead of retrying.

Functions

func ArtifactDigest

func ArtifactDigest(data []byte) string

func CanonicalJSON

func CanonicalJSON(v any) ([]byte, error)

CanonicalJSON encodes v deterministically (sorted keys, no whitespace, no HTML escaping) so digests over the output are stable.

func DescriptorDigest

func DescriptorDigest(raw []byte) string

func IsDataArtifact

func IsDataArtifact(name string) bool

IsDataArtifact reports whether an artifact name is a bundled data file.

func ModuleChecksum

func ModuleChecksum(module []byte) string

func VerifyModuleChecksum

func VerifyModuleChecksum(module []byte, expected string) error

Types

type ArtifactRef

type ArtifactRef struct {
	Digest string `json:"digest"`
	Size   int64  `json:"size"`
}

type Bundle

type Bundle struct {
	ID            string
	Module        []byte
	Manifest      Manifest
	Checksum      string
	Tests         []byte
	Descriptor    Descriptor
	DescriptorRaw []byte
	// Data holds read-only bundled data files keyed by their descriptor
	// artifact name (e.g. "data/allowlist.txt").
	Data map[string][]byte
}

type ChannelPointer

type ChannelPointer struct {
	Namespace        string    `json:"namespace,omitempty"`
	Channel          string    `json:"channel"`
	BundleID         string    `json:"bundle_id"`
	Checksum         string    `json:"checksum"`
	Generation       uint64    `json:"generation,omitempty"`
	DescriptorDigest string    `json:"descriptor_digest,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
}

func ParseChannelPointer

func ParseChannelPointer(data []byte) (ChannelPointer, error)

type Descriptor

type Descriptor struct {
	Schema     string                 `json:"schema"`
	ABI        string                 `json:"abi"`
	Manifest   ManifestIdentity       `json:"manifest"`
	Artifacts  map[string]ArtifactRef `json:"artifacts"`
	Provenance Provenance             `json:"provenance,omitempty"`
	// Signatures is reserved for future bundle signing; never verified yet.
	Signatures []json.RawMessage `json:"signatures"`
}

Descriptor's identity zone (schema, abi, manifest, artifacts) derives the bundle ID; provenance and signatures are annotations that never change it.

func NewDescriptor

func NewDescriptor(identity ManifestIdentity, artifacts map[string][]byte) Descriptor

func ParseDescriptor

func ParseDescriptor(data []byte) (Descriptor, error)

func (Descriptor) BundleID

func (d Descriptor) BundleID() (string, error)

func (Descriptor) Verify

func (d Descriptor) Verify(files map[string][]byte) error

type Manifest

type Manifest struct {
	Name       string `json:"name"`
	Version    string `json:"version"`
	ABI        string `json:"abi_version"`
	Entrypoint string `json:"entrypoint"`
	Language   string `json:"language"`
}

func ParseManifest

func ParseManifest(data []byte) (Manifest, error)

type ManifestIdentity

type ManifestIdentity struct {
	Name       string `json:"name"`
	ABI        string `json:"abi"`
	Entrypoint string `json:"entrypoint"`
	Language   string `json:"language"`
}

ManifestIdentity excludes the manifest version field because it is set to the bundle ID itself after hashing.

type Provenance

type Provenance struct {
	BuiltAt      time.Time `json:"built_at,omitempty"`
	Builder      string    `json:"builder,omitempty"`
	SourceCommit string    `json:"source_commit,omitempty"`
	SourceDirty  bool      `json:"source_dirty,omitempty"`
	CIRun        string    `json:"ci_run,omitempty"`
}

type Revision

type Revision struct {
	Schema             string    `json:"schema"`
	Namespace          string    `json:"namespace,omitempty"`
	Channel            string    `json:"channel"`
	Generation         uint64    `json:"generation"`
	BundleID           string    `json:"bundle_id"`
	DescriptorDigest   string    `json:"descriptor_digest,omitempty"`
	PreviousGeneration uint64    `json:"previous_generation,omitempty"`
	DeployedAt         time.Time `json:"deployed_at"`
	DeployedBy         string    `json:"deployed_by,omitempty"`
	SourceCommit       string    `json:"source_commit,omitempty"`
	CIRun              string    `json:"ci_run,omitempty"`
	Message            string    `json:"message,omitempty"`
}

Revision is an append-only deployment record; generations only ever grow.

func ParseRevision

func ParseRevision(data []byte) (Revision, error)