releasecontract

package
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2026 License: MIT Imports: 13 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/v6"
	// LegacyArtifactManifestSchema is accepted for recorded releases that
	// predate the gVisor artifact section; a newer updater still
	// authenticates them.
	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 GVisorMaterializationSchema = "secondbox.runner/backend-materialization/v1"

GVisorMaterializationSchema is the runner's backend materialization schema.

Variables

This section is empty.

Functions

func ArtifactManifestLocation 

func ArtifactManifestLocation(version 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 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 QualificationEvidenceLocation added in v0.2.0 

func QualificationEvidenceLocation(version string) string

func SourceFreeSuiteLocation 

func SourceFreeSuiteLocation(version 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) 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) 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 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 {
	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"`
	SignedManifestDigest  string          `json:"signedManifestDigest"`
	SigningKeyFingerprint string          `json:"signingKeyFingerprint"`
	RuntimeBundle         SignedComponent `json:"runtimeBundle"`
	ToolchainBundle       SignedComponent `json:"toolchainBundle"`
}

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 {
	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 string) error

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 SignedComponent added in v0.1.3 

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

SignedComponent is one independently selected component bound by the signed top-level microVM manifest.

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.