releasecontract

package
v0.31.0 Latest Latest
Warning

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

 Go to latest Published: Nov 7, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package releasecontract defines the public, provider-neutral identity of a SecondBox release.

Index

Constants

View Source 
const (
	ArtifactManifestSchema = "secondbox.release/artifact-manifest/v7"
	// SignedArtifactManifestSchema is accepted for recorded releases that
	// still carried a microVM signing key fingerprint; a newer updater still
	// authenticates them.
	SignedArtifactManifestSchema = "secondbox.release/artifact-manifest/v6"
	// LegacyArtifactManifestSchema is accepted for recorded releases that
	// predate the gVisor artifact section and also carried the signing key.
	LegacyArtifactManifestSchema               = "secondbox.release/artifact-manifest/v5"
	QualificationEvidenceSchema                = "secondbox.release/qualification-evidence/v2"
	LegacyQualificationEvidenceSchema          = "secondbox.release/qualification-evidence/v1"
	InstallerQualificationEvidenceSchema       = "secondbox.release/installer-qualification-evidence/v2"
	LegacyInstallerQualificationEvidenceSchema = "secondbox.release/installer-qualification-evidence/v1"

	TypeScriptPackage   = "@secondstack-ai/secondbox"
	GoModule            = "github.com/SecondStack-AI/SecondBox"
	ControlPlaneImage   = "ghcr.io/secondstack-ai/secondbox/control-plane"
	RunnerImage         = "ghcr.io/secondstack-ai/secondbox/runner"
	MicroVMImage        = "ghcr.io/secondstack-ai/secondbox/microvm-artifacts"
	InstallerToolsImage = "ghcr.io/secondstack-ai/secondbox/installer-tools"
	GVisorRunnerImage   = "ghcr.io/secondstack-ai/secondbox/runner-gvisor"
	GVisorImage         = "ghcr.io/secondstack-ai/secondbox/gvisor-artifacts"
)
View Source 
const (
	SharedArtifactsSchema         = "secondbox.release/shared-artifacts/v1"
	SharedArtifactsRecordFileName = "shared-artifacts.json"
)

The architecture-neutral files of a release are built once and published byte for byte by every guest architecture's artifact set. The shared artifacts record binds that directory to one version, tag and source commit.

View Source 
const GVisorMaterializationSchema = "secondbox.runner/backend-materialization/v1"

GVisorMaterializationSchema is the runner's backend materialization schema.

Variables

View Source 
var (
	HostBinaryNames     = []string{"secondbox", "secondbox-deploy"}
	HostBinaryPlatforms = []string{"linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64"}
)

Functions

func ArchitectureAssetSuffix added in v0.24.0 

func ArchitectureAssetSuffix(guestArchitecture string) string

ArchitectureAssetSuffix qualifies the release files that belong to one guest architecture. A release publishes one artifact set per guest architecture under the same tag: amd64 keeps the unqualified names and shares its architecture-neutral files (SDKs, binaries, OpenAPI, SBOM) with the others.

func ArtifactManifestFileName added in v0.24.0 

func ArtifactManifestFileName(version, guestArchitecture string) string

func ArtifactManifestLocation 

func ArtifactManifestLocation(version, guestArchitecture string) string

func BinaryLocation 

func BinaryLocation(version, name, platform string) string

func CompareVersions added in v0.6.0 

func CompareVersions(left, right string) (int, error)

CompareVersions orders two canonical release versions according to SemVer precedence. It rejects build metadata because release tags do not admit it.

func Digest 

func Digest(data []byte) string

func GVisorMaterializationLocation added in v0.9.0 

func GVisorMaterializationLocation(version string) string

GVisorMaterializationLocation is the canonical release file carrying the gVisor backend materialization.

func GVisorQualificationEvidenceLocation added in v0.9.0 

func GVisorQualificationEvidenceLocation(version string, pod bool) string

GVisorQualificationEvidenceLocation is the canonical release file carrying the gVisor host (or pod) scenario evidence.

func GVisorQualificationSuite added in v0.9.0 

func GVisorQualificationSuite(pod bool) string

GVisorQualificationSuite names the evidence suite of a gVisor run.

func HostBinaryFileName added in v0.26.0 

func HostBinaryFileName(version, name, platform string) string

func InstallBootstrapLocation added in v0.4.0 

func InstallBootstrapLocation(version string) string

func InstallerQualificationEvidenceLocation added in v0.4.0 

func InstallerQualificationEvidenceLocation(version string) string

func ParseTag 

func ParseTag(tag string) (string, error)

func QualificationEvidenceFileName added in v0.24.0 

func QualificationEvidenceFileName(version, guestArchitecture string) string

func QualificationEvidenceLocation added in v0.2.0 

func QualificationEvidenceLocation(version, guestArchitecture string) string

func ReleaseFileLocation added in v0.24.0 

func ReleaseFileLocation(version, name string) string

ReleaseFileLocation is the public download location of one release file.

func SharedArtifactFileModes added in v0.26.0 

func SharedArtifactFileModes(version string) map[string]fs.FileMode

SharedArtifactFileModes names every shared file of version with the mode it is staged and published with: host binaries are executable, documents are not.

func SharedArtifactFileNames added in v0.26.0 

func SharedArtifactFileNames(version string) []string

func SourceFreeSuiteLocation 

func SourceFreeSuiteLocation(version string) string

func StandardBundleFileName added in v0.24.0 

func StandardBundleFileName(name, guestArchitecture string) string

Types

type ArtifactManifest 

type ArtifactManifest struct {
	SchemaVersion string `json:"schemaVersion"`
	Candidate     bool   `json:"candidate,omitempty"`
	Identity
	OpenAPI                        OpenAPIArtifact          `json:"openapi"`
	RunnerProtocol                 ProtocolWindow           `json:"runnerProtocol"`
	GuestProtocol                  ProtocolWindow           `json:"guestProtocol"`
	Platforms                      PlatformMatrix           `json:"platforms"`
	GoSDK                          SDKArtifact              `json:"goSdk"`
	TypeScriptSDK                  SDKArtifact              `json:"typeScriptSdk"`
	ControlPlane                   OCIArtifact              `json:"controlPlane"`
	Runner                         OCIArtifact              `json:"runner"`
	InstallerTools                 OCIArtifact              `json:"installerTools"`
	BundledServices                BundledServiceImages     `json:"bundledServices"`
	InstallBootstrap               Reference                `json:"installBootstrap"`
	MicroVM                        MicroVMArtifact          `json:"microvm"`
	GVisor                         *GVisorArtifact          `json:"gvisor,omitempty"`
	Binaries                       []BinaryArtifact         `json:"binaries"`
	SBOMs                          []Reference              `json:"sboms"`
	ArtifactAttestations           []Reference              `json:"artifactAttestations,omitempty"`
	SourceFreeSuite                Reference                `json:"sourceFreeSuite,omitempty"`
	QualificationEvidence          Reference                `json:"qualificationEvidence"`
	InstallerQualificationEvidence Reference                `json:"installerQualificationEvidence"`
	StandardBundles                []StandardBundleArtifact `json:"standardBundles"`
}

ArtifactManifest contains immutable release artifact identity.

func DecodeArtifactManifest 

func DecodeArtifactManifest(data []byte) (ArtifactManifest, error)

func (ArtifactManifest) GuestArchitecture added in v0.23.0 

func (manifest ArtifactManifest) GuestArchitecture() (string, error)

GuestArchitecture returns the one guest architecture a release's microVM artifacts, Runner and standard Profiles target.

func (ArtifactManifest) InstallerQualificationSubjectDigest added in v0.4.0 

func (manifest ArtifactManifest) InstallerQualificationSubjectDigest() (string, error)

InstallerQualificationSubjectDigest identifies all public release contract fields except the installer-evidence reference itself. Omitting that one reference avoids a digest cycle while still binding qualification to the exact binaries, images, protocols, bundles, and other immutable release objects that the final manifest publishes.

func (ArtifactManifest) RequiresInstallerQualification added in v0.23.0 

func (manifest ArtifactManifest) RequiresInstallerQualification() (bool, error)

RequiresInstallerQualification reports whether the release carries installer qualification evidence: final releases for amd64 guests, the only releases the guided installer installs.

func (ArtifactManifest) Validate 

func (manifest ArtifactManifest) Validate() error

type BinaryArtifact 

type BinaryArtifact struct {
	Identity Identity `json:"identity"`
	Name     string   `json:"name"`
	Platform string   `json:"platform"`
	Location string   `json:"location"`
	SHA256   string   `json:"sha256"`
}

type BundleComponent added in v0.25.0 

type BundleComponent struct {
	ArtifactID             string   `json:"artifactId"`
	ManifestDigest         string   `json:"manifestDigest"`
	MandatoryGuestFeatures []string `json:"mandatoryGuestFeatures"`
}

BundleComponent is one independently selected component bound by the top-level microVM bundle manifest.

type BundledServiceImages added in v0.4.0 

type BundledServiceImages struct {
	Postgres string `json:"postgres"`
}

type GVisorArtifact added in v0.9.0 

type GVisorArtifact struct {
	Identity                 Identity  `json:"identity"`
	RunnerReference          string    `json:"runnerReference"`
	ImageReference           string    `json:"imageReference"`
	Materialization          Reference `json:"materialization"`
	MaterializationDigest    string    `json:"materializationDigest"`
	FlatRootDigest           string    `json:"flatRootDigest"`
	RunscRelease             string    `json:"runscRelease"`
	QualificationEvidence    Reference `json:"qualificationEvidence"`
	PodQualificationEvidence Reference `json:"podQualificationEvidence"`
}

GVisorArtifact names the gVisor backend distribution: the runner image and the artifact transport carrying the prepared flat root, the launch artifacts, and the backend materialization whose canonical digest runners and platform operators pin. The materialization is also a release file.

func (GVisorArtifact) VerifyGVisorMaterialization added in v0.9.0 

func (artifact GVisorArtifact) VerifyGVisorMaterialization(data []byte) error

VerifyGVisorMaterialization checks that a published materialization agrees with the identities the artifact manifest records for it.

type GVisorLaunchArtifact added in v0.9.0 

type GVisorLaunchArtifact struct {
	ID     string `json:"id"`
	SHA256 string `json:"sha256"`
}

type GVisorMaterialization added in v0.9.0 

type GVisorMaterialization struct {
	SchemaVersion           string                   `json:"schemaVersion"`
	Key                     GVisorMaterializationKey `json:"key"`
	SourceOCIManifestDigest string                   `json:"sourceOciManifestDigest,omitempty"`
	FlatRootDigest          string                   `json:"flatRootDigest,omitempty"`
	LaunchArtifacts         []GVisorLaunchArtifact   `json:"launchArtifacts"`
	AgentProtocolGeneration uint32                   `json:"agentProtocolGeneration"`
	AgentFeatures           []string                 `json:"agentFeatures"`
	BackendBuildID          string                   `json:"backendBuildId"`
	HelperBuildID           string                   `json:"helperBuildId,omitempty"`
}

GVisorMaterialization mirrors the runner's backend materialization document field for field, so its canonical digest here equals the runner's.

func DecodeGVisorMaterialization added in v0.9.0 

func DecodeGVisorMaterialization(data []byte) (GVisorMaterialization, error)

DecodeGVisorMaterialization strictly decodes a published materialization.

func (GVisorMaterialization) Digest added in v0.9.0 

func (materialization GVisorMaterialization) Digest() (string, error)

Digest is the canonical digest runners pin: sha256 over the compact JSON encoding of the validated typed document.

func (GVisorMaterialization) Validate added in v0.9.0 

func (materialization GVisorMaterialization) Validate() error

Validate applies the runner's materialization invariants for the gVisor backend, so a release cannot publish a document a runner would refuse.

type GVisorMaterializationKey added in v0.9.0 

type GVisorMaterializationKey struct {
	BackendKind             string `json:"backendKind"`
	GuestArchitecture       string `json:"guestArchitecture"`
	RuntimeManifestDigest   string `json:"runtimeManifestDigest"`
	ToolchainManifestDigest string `json:"toolchainManifestDigest"`
}

type GVisorQualificationDeviceEvidence added in v0.9.0 

type GVisorQualificationDeviceEvidence struct {
	Required bool `json:"required"`
	Present  bool `json:"present"`
}

type GVisorQualificationEvidence added in v0.9.0 

type GVisorQualificationEvidence struct {
	Skipped          []string                        `json:"skipped,omitempty"`
	SchemaVersion    string                          `json:"schemaVersion"`
	SourceCommit     string                          `json:"sourceCommit"`
	RepositoryDirty  bool                            `json:"repositoryDirty"`
	Suite            string                          `json:"suite"`
	Backend          string                          `json:"backend"`
	PassCount        int64                           `json:"passCount"`
	WallClockSeconds int64                           `json:"wallClockSeconds"`
	Host             GVisorQualificationHostEvidence `json:"host"`
	QualifiedAt      string                          `json:"qualifiedAt"`
}

GVisorQualificationEvidence is the scenario evidence of a gVisor host or pod run: the same schema as the Firecracker evidence, on a host without KVM and naming its backend.

func DecodeGVisorQualificationEvidence added in v0.9.0 

func DecodeGVisorQualificationEvidence(data []byte, pod bool) (GVisorQualificationEvidence, error)

func (GVisorQualificationEvidence) Validate added in v0.9.0 

func (evidence GVisorQualificationEvidence) Validate(pod bool) error

func (GVisorQualificationEvidence) ValidateForRelease added in v0.9.0 

func (evidence GVisorQualificationEvidence) ValidateForRelease(sourceCommit string, pod bool) error

type GVisorQualificationHostEvidence added in v0.9.0 

type GVisorQualificationHostEvidence struct {
	Platform            string                            `json:"platform"`
	KVM                 GVisorQualificationDeviceEvidence `json:"kvm"`
	TUN                 GVisorQualificationDeviceEvidence `json:"tun"`
	WorkspaceFilesystem QualificationFilesystemEvidence   `json:"workspaceFilesystem"`
}

type Identity 

type Identity struct {
	Version      string `json:"version"`
	Tag          string `json:"tag"`
	SourceCommit string `json:"sourceCommit"`
}

Identity is repeated on every independently inspectable release object.

type InstallerQualificationEvidence added in v0.4.0 

type InstallerQualificationEvidence struct {
	SchemaVersion         string                    `json:"schemaVersion"`
	SourceCommit          string                    `json:"sourceCommit"`
	RepositoryDirty       bool                      `json:"repositoryDirty"`
	Suite                 string                    `json:"suite"`
	PassCount             int64                     `json:"passCount"`
	WallClockSeconds      int64                     `json:"wallClockSeconds"`
	Host                  QualificationHostEvidence `json:"host"`
	ReleaseManifestDigest string                    `json:"releaseManifestDigest"`
	FilesystemIdentity    string                    `json:"filesystemIdentity"`
	RebootPassed          bool                      `json:"rebootPassed"`
	QualifiedAt           string                    `json:"qualifiedAt"`
}

func DecodeInstallerQualificationEvidence added in v0.4.0 

func DecodeInstallerQualificationEvidence(data []byte) (InstallerQualificationEvidence, error)

func (InstallerQualificationEvidence) Validate added in v0.4.0 

func (evidence InstallerQualificationEvidence) Validate() error

func (InstallerQualificationEvidence) ValidateForRelease added in v0.4.0 

func (evidence InstallerQualificationEvidence) ValidateForRelease(sourceCommit, qualificationSubjectDigest string) error

type MicroVMArtifact 

type MicroVMArtifact struct {
	Identity             Identity `json:"identity"`
	ImageReference       string   `json:"imageReference"`
	BundleManifestDigest string   `json:"bundleManifestDigest,omitempty"`
	// Recorded v5 and v6 manifests name the bundle manifest digest
	// signedManifestDigest and carry the retired signing key fingerprint. The
	// field order keeps their re-encoding byte-identical to the recorded shape,
	// which installer qualification evidence digests.
	LegacySignedManifestDigest  string          `json:"signedManifestDigest,omitempty"`
	LegacySigningKeyFingerprint string          `json:"signingKeyFingerprint,omitempty"`
	RuntimeBundle               BundleComponent `json:"runtimeBundle"`
	ToolchainBundle             BundleComponent `json:"toolchainBundle"`
}

func (MicroVMArtifact) ManifestDigest added in v0.25.0 

func (artifact MicroVMArtifact) ManifestDigest() string

ManifestDigest returns the bundle manifest digest under either recorded name.

type OCIArtifact 

type OCIArtifact struct {
	Identity  Identity `json:"identity"`
	Reference string   `json:"reference"`
}

type OpenAPIArtifact 

type OpenAPIArtifact struct {
	Identity Identity `json:"identity"`
	Reference
}

type PlatformMatrix 

type PlatformMatrix struct {
	HostBinaries         []string `json:"hostBinaries"`
	ControlPlane         []string `json:"controlPlane"`
	Runner               []string `json:"runner"`
	InstallerTools       []string `json:"installerTools"`
	Guest                []string `json:"guest"`
	QualifiedRunnerGuest []string `json:"qualifiedRunnerGuest"`
}

type ProtocolWindow 

type ProtocolWindow struct {
	Minimum uint32 `json:"minimum"`
	Maximum uint32 `json:"maximum"`
}

type QualificationDeviceEvidence added in v0.2.0 

type QualificationDeviceEvidence struct {
	Path     string `json:"path"`
	Present  bool   `json:"present"`
	Readable bool   `json:"readable"`
	Writable bool   `json:"writable"`
}

type QualificationEvidence added in v0.2.0 

type QualificationEvidence struct {
	Skipped          []string                  `json:"skipped,omitempty"`
	SchemaVersion    string                    `json:"schemaVersion"`
	SourceCommit     string                    `json:"sourceCommit"`
	RepositoryDirty  bool                      `json:"repositoryDirty"`
	Suite            string                    `json:"suite"`
	PassCount        int64                     `json:"passCount"`
	WallClockSeconds int64                     `json:"wallClockSeconds"`
	Host             QualificationHostEvidence `json:"host"`
	QualifiedAt      string                    `json:"qualifiedAt"`
}

func DecodeQualificationEvidence added in v0.2.0 

func DecodeQualificationEvidence(data []byte) (QualificationEvidence, error)

func (QualificationEvidence) Validate added in v0.2.0 

func (evidence QualificationEvidence) Validate() error

func (QualificationEvidence) ValidateForRelease added in v0.2.0 

func (evidence QualificationEvidence) ValidateForRelease(sourceCommit, guestArchitecture string) error

ValidateForRelease binds the evidence to one release: its source commit and its guest architecture. Legacy evidence records no host platform; it predates arm64 releases and qualifies amd64 guests only.

type QualificationFilesystemEvidence added in v0.2.0 

type QualificationFilesystemEvidence struct {
	Mount string `json:"mount"`
	Type  string `json:"type"`
}

type QualificationHostEvidence added in v0.2.0 

type QualificationHostEvidence struct {
	Platform            string                          `json:"platform"`
	KVM                 QualificationDeviceEvidence     `json:"kvm"`
	TUN                 QualificationDeviceEvidence     `json:"tun"`
	WorkspaceFilesystem QualificationFilesystemEvidence `json:"workspaceFilesystem"`
}

type Reference 

type Reference struct {
	Location string `json:"location"`
	Digest   string `json:"digest"`
}

Reference identifies immutable bytes at a public HTTPS location.

type SDKArtifact 

type SDKArtifact struct {
	Identity   Identity  `json:"identity"`
	Coordinate string    `json:"coordinate"`
	Package    Reference `json:"package"`
}

type SharedArtifactFile added in v0.26.0 

type SharedArtifactFile struct {
	Name   string `json:"name"`
	Digest string `json:"digest"`
}

type SharedArtifactsRecord added in v0.26.0 

type SharedArtifactsRecord struct {
	SchemaVersion string `json:"schemaVersion"`
	Identity
	PostgresImage string               `json:"postgresImage"`
	Files         []SharedArtifactFile `json:"files"`
}

func DecodeSharedArtifactsRecord added in v0.26.0 

func DecodeSharedArtifactsRecord(data []byte) (SharedArtifactsRecord, error)

func (SharedArtifactsRecord) Validate added in v0.26.0 

func (record SharedArtifactsRecord) Validate() error

Validate requires exactly the shared file set of the record's version, each named once, in byte order, with a canonical digest.

func (SharedArtifactsRecord) ValidateForRelease added in v0.26.0 

func (record SharedArtifactsRecord) ValidateForRelease(version, sourceCommit string) error

ValidateForRelease binds the record to the release a staging builds.

type StandardBundleArtifact 

type StandardBundleArtifact struct {
	Identity Identity                  `json:"identity"`
	Name     string                    `json:"name"`
	Document Reference                 `json:"document"`
	Profiles []StandardProfileIdentity `json:"profiles"`
}

type StandardProfileIdentity 

type StandardProfileIdentity struct {
	Name       string `json:"name"`
	Revision   int64  `json:"revision"`
	SpecDigest string `json:"specDigest"`
}

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.