image

type APKArch string

type APKBuildRequest struct {
	// Config is the absolute Melange configuration path.
	Config string
	// VarsFile is the absolute Melange vars file path.
	VarsFile string
	// KeyPath is the absolute ephemeral signing key path the builder generates.
	KeyPath string
	// OutDir is the absolute APK repository output directory.
	OutDir string
	// Sources is the build order; Sources[0].Arch is also the compile-check architecture.
	Sources []APKBuildSource
	// Runner is the container runner, "docker".
	Runner string
	// Namespace is the APK namespace.
	Namespace string
	// BuildDate is the RFC 3339 reproducible build timestamp.
	BuildDate string
	// GitRepoURL is the provenance repository URL.
	GitRepoURL string
	// GitCommit is the provenance commit SHA.
	GitCommit string
}

type APKBuildSource struct {
	// Arch is the APK architecture built from this source tree.
	Arch APKArch
	// Dir is the absolute directory containing the staged binary files.
	Dir string
}

type APKBuilder interface {
	// Build compiles, signs, and writes APK repositories for request.
	//
	// request.Sources are built in order. The returned [APKRepositories.Dir]
	// must equal request.OutDir and [APKRepositories.PublicKey] must equal
	// request.KeyPath with a ".pub" suffix.
	Build(ctx context.Context, request APKBuildRequest) (APKRepositories, error)
}

type APKRepositories struct {
	// Dir is the repository root the build wrote.
	Dir string
	// PublicKey is the generated signing public key path.
	PublicKey string
}

type Annotation struct {
	// Key is the annotation name.
	Key string
	// Value is the annotation value.
	Value string
}

type BinaryDigest struct {
	// Name is the binary filename.
	Name string `json:"name"`
	// Digest is the verified canonical digest of the staged file.
	Digest string `json:"digest"`
}

type BuildBinary struct {
	// Platform is the Linux OCI platform this binary was built for.
	Platform Platform
	// Name is the binary filename for this platform.
	Name string
	// Path is the Source-relative confined path of the staged file.
	Path string
	// Digest is the expected canonical digest of the file at Path.
	Digest rel.Digest
}

type BuildInput struct {
	// Binaries are the canonical Linux facts. [Build] requires a nonempty
	// identical name set on [PlatformAMD64] and [PlatformARM64].
	Binaries []BuildBinary
	// Source is the extracted oci-input artifact root.
	Source fs.FS
	// Work is the scratch workspace root.
	Work *os.Root
	// Output is the authoritative artifact output root.
	Output *os.Root
	// Version is the candidate MAJOR.MINOR.PATCH release.
	Version rel.Version
	// BuildDate is the RFC 3339 reproducible build timestamp.
	BuildDate string
	// Namespace is the APK namespace, typically the GitHub owner.
	Namespace string
	// SourceURL is the provenance repository URL.
	SourceURL string
	// Commit is the provenance commit SHA.
	Commit string
	// Reference is the local image reference, e.g. "local/release:1.2.3".
	Reference string
	// MelangeConfig is the Melange configuration document to copy.
	MelangeConfig io.Reader
	// ApkoConfig is the apko configuration document to copy.
	ApkoConfig io.Reader
}

type BuildResult struct {
	// Schema identifies the image-build result version and is always [BuildSchema].
	Schema string `json:"schema"`
	// Version is the candidate MAJOR.MINOR.PATCH version.
	Version string `json:"version"`
	// Binaries are the staged binary filenames, sorted name-ascending.
	Binaries []string `json:"binaries"`
	// Work is the scratch workspace path, [os.Root.Name] of the work root.
	Work string `json:"work"`
	// Output is the authoritative output path, [os.Root.Name] of the output root.
	Output string `json:"output"`
	// BuildDate is the RFC 3339 reproducible build timestamp.
	BuildDate string `json:"build_date"`
	// Packages are the per-architecture APK facts in canonical platform order.
	Packages []PackageResult `json:"packages"`
}

type ComposeRequest struct {
	// Dir is the absolute working directory both apko invocations run in.
	Dir string
	// Config is the Dir-relative apko configuration path.
	Config string
	// Repository is the Dir-relative APK repository path.
	Repository string
	// Keyring is the Dir-relative APK signing public key path.
	Keyring string
	// Lockfile is the Dir-relative lock output path.
	Lockfile string
	// SBOMPath is the Dir-relative SBOM output directory.
	SBOMPath string
	// Layout is the Dir-relative OCI layout output directory.
	Layout string
	// Reference is the local image reference, e.g. "local/release:1.2.3".
	Reference string
	// BuildDate is the RFC 3339 reproducible build timestamp.
	BuildDate string
	// Arches is the architecture list, one --arch flag per entry.
	Arches []APKArch
	// Annotations is the ordered annotation list applied to the image.
	Annotations []Annotation
}

type Composer interface {
	// Build locks request.Config and writes the OCI layout under request.Layout.
	//
	// Both invocations run with working directory request.Dir. Architecture
	// flags follow request.Arches in order.
	Build(ctx context.Context, request ComposeRequest) error
}

type ExpectedImage struct {
	// Version is the candidate MAJOR.MINOR.PATCH release.
	Version rel.Version
	// Binaries are the filenames that must appear at /usr/bin/<name> in each layer.
	Binaries []string
	// Revision is the expected org.opencontainers.image.revision, typically GITHUB_SHA.
	Revision string
	// Source is the expected org.opencontainers.image.source URL.
	Source string
	// Canonical maps each APK architecture onto per-name digests of
	// sources/<arch>/<name>.
	Canonical map[APKArch]map[string]rel.Digest
}

type Layout struct {
	// IndexBytes is the exact index.json contents, retained verbatim.
	IndexBytes []byte
	// IndexDigest is SHA-256 over IndexBytes, never over re-marshaled JSON.
	IndexDigest rel.Digest
	// Annotations are the index annotations as they appear on disk.
	Annotations map[string]string
	// Platforms are the index manifests in file order.
	Platforms []LayoutPlatform
}

type LayoutPlatform struct {
	// Platform is the Linux OCI platform recorded on the index descriptor.
	Platform Platform
	// Manifest is the digest of the platform manifest blob.
	Manifest rel.Digest
	// Config is the digest of the image config blob.
	Config rel.Digest
	// Layer is the digest of the single layer blob.
	Layer rel.Digest
	// LayerMedia is the layer descriptor media type.
	LayerMedia string
	// Annotations are the manifest annotations as they appear on disk.
	Annotations map[string]string
}

type PackageResult struct {
	// Platform is the Linux OCI platform, such as linux/amd64.
	Platform string `json:"platform"`
	// Arch is the APK architecture, such as x86_64.
	Arch string `json:"arch"`
	// Package is the output-relative APK path, packages/<arch>/<file>.apk.
	Package string `json:"package"`
	// BinaryDigests are the verified canonical digests, sorted by name.
	BinaryDigests []BinaryDigest `json:"binary_digests"`
}

type Platform string

type VerifiedImage struct {
	// contains filtered or unexported fields
}

type VerifiedPlatform struct {
	// Platform is the Linux OCI platform, such as linux/amd64.
	Platform string `json:"platform"`
	// Arch is the APK architecture, such as x86_64.
	Arch string `json:"arch"`
	// Manifest is the digest of the platform manifest blob.
	Manifest string `json:"manifest"`
	// Config is the digest of the image config blob.
	Config string `json:"config"`
	// Layer is the digest of the single layer blob.
	Layer string `json:"layer"`
	// BinaryDigests are the streamed SHA-256 of each usr/bin/<name> in that layer.
	BinaryDigests []BinaryDigest `json:"binary_digests"`
}

type VerifyResult struct {
	// Schema identifies the image-verify result version and is always [VerifySchema].
	Schema string `json:"schema"`
	// Version is the candidate MAJOR.MINOR.PATCH version.
	Version string `json:"version"`
	// Binaries are the staged binary filenames, sorted name-ascending.
	Binaries []string `json:"binaries"`
	// IndexDigest is SHA-256 over the exact index.json bytes.
	IndexDigest string `json:"index_digest"`
	// Platforms are the verified platforms in canonical order: linux/amd64, linux/arm64.
	Platforms []VerifiedPlatform `json:"platforms"`
}