manifest

package
v0.1.7 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package manifest defines the OCI manifest types and cocoonstack artifact-classification helpers used by epoch.

Epoch stores three kinds of artifacts in the same OCI registry:

  • Container images — standard OCI / Docker images. Epoch is a transparent mirror; no cocoonstack-specific shape.
  • Cloud images — disk-only OCI artifacts published via `oras push`, with artifactType ArtifactTypeOSImage. The windows builder is the canonical producer (split qcow2 parts).
  • VM snapshots — full cocoon VM state captured by `cocoon vm save` and uploaded by `epoch push` as an OCI artifact with artifactType ArtifactTypeSnapshot.

All three are stored as OCI 1.1 image manifests. The classification function Classify looks at top-level artifactType first, then falls back to the config blob mediaType for plain container images.

Index

Constants

View Source 
const (
	MediaTypeOCIManifest    = "application/vnd.oci.image.manifest.v1+json"
	MediaTypeOCIIndex       = "application/vnd.oci.image.index.v1+json"
	MediaTypeDockerManifest = "application/vnd.docker.distribution.manifest.v2+json"
	MediaTypeDockerIndex    = "application/vnd.docker.distribution.manifest.list.v2+json"

	MediaTypeOCIImageConfig = "application/vnd.oci.image.config.v1+json"
	MediaTypeDockerConfig   = "application/vnd.docker.container.image.v1+json"
	MediaTypeOCIEmpty       = "application/vnd.oci.empty.v1+json"

	ArtifactTypeOSImage      = "application/vnd.cocoonstack.os-image.v1+json"
	ArtifactTypeWindowsImage = "application/vnd.cocoonstack.windows-image.v1+json"
	ArtifactTypeSnapshot     = "application/vnd.cocoonstack.snapshot.v1+json"

	MediaTypeSnapshotConfig = "application/vnd.cocoonstack.snapshot.config.v1+json"

	MediaTypeDiskQcow2     = "application/vnd.cocoonstack.disk.qcow2"
	MediaTypeDiskQcow2Part = "application/vnd.cocoonstack.disk.qcow2.part"
	MediaTypeDiskRaw       = "application/vnd.cocoonstack.disk.raw"
	MediaTypeDiskRawPart   = "application/vnd.cocoonstack.disk.raw.part"

	MediaTypeWindowsDiskQcow2     = "application/vnd.cocoonstack.windows.disk.qcow2"
	MediaTypeWindowsDiskQcow2Part = "application/vnd.cocoonstack.windows.disk.qcow2.part"
	MediaTypeWindowsDiskRaw       = "application/vnd.cocoonstack.windows.disk.raw"
	MediaTypeWindowsDiskRawPart   = "application/vnd.cocoonstack.windows.disk.raw.part"

	MediaTypeVMConfig = "application/vnd.cocoonstack.vm.config+json"
	MediaTypeVMState  = "application/vnd.cocoonstack.vm.state+json"
	MediaTypeVMMemory = "application/vnd.cocoonstack.vm.memory"
	MediaTypeVMCidata = "application/vnd.cocoonstack.vm.cidata"

	MediaTypeGeneric = "application/octet-stream"
	MediaTypeTar     = "application/x-tar"

	AnnotationTitle       = "org.opencontainers.image.title"
	AnnotationCreated     = "org.opencontainers.image.created"
	AnnotationSource      = "org.opencontainers.image.source"
	AnnotationRevision    = "org.opencontainers.image.revision"
	AnnotationDescription = "org.opencontainers.image.description"

	AnnotationSnapshotID        = "cocoonstack.snapshot.id"
	AnnotationSnapshotBaseImage = "cocoonstack.snapshot.baseimage"
)

Cocoonstack and OCI media type / artifactType / annotation constants used across epoch. They are grouped by purpose, not by occurrence.

Variables

This section is empty.

Functions

func IsDiskMediaType added in v0.1.7 

func IsDiskMediaType(mt string) bool

IsDiskMediaType reports whether mt is a cocoonstack disk layer mediaType (qcow2/raw, whole or split, generic or windows-specific legacy). Used by cloudimg.Stream to decide which layers to concatenate.

func MediaTypeForCocoonFile added in v0.1.7 

func MediaTypeForCocoonFile(name string) string

MediaTypeForCocoonFile returns the OCI layer mediaType for a file inside a cocoon snapshot tar. Unknown filenames fall back to a qcow2/raw suffix match, then to MediaTypeGeneric.

Types

type Catalog 

type Catalog struct {
	Repositories map[string]*Repository `json:"repositories"`
	UpdatedAt    time.Time              `json:"updatedAt"`
}

Catalog is epoch's global index of repositories under `epoch/catalog.json`. It is internal to epoch's storage layer; OCI clients use `/v2/_catalog` instead.

type Descriptor added in v0.1.7 

type Descriptor struct {
	MediaType    string            `json:"mediaType"`
	Digest       string            `json:"digest"`
	Size         int64             `json:"size"`
	Annotations  map[string]string `json:"annotations,omitempty"`
	ArtifactType string            `json:"artifactType,omitempty"`
}

Descriptor is the OCI Content Descriptor used by manifests to reference blobs (config or layers). Only the fields epoch needs are present.

func (Descriptor) Title added in v0.1.7 

func (d Descriptor) Title() string

Title returns the layer's `org.opencontainers.image.title` annotation, or the empty string. Used to recover filenames for snapshot tar reassembly and to order cloudimg split parts.

type IndexManifest added in v0.1.7 

type IndexManifest struct {
	MediaType string    `json:"mediaType"`
	Digest    string    `json:"digest"`
	Size      int64     `json:"size"`
	Platform  *Platform `json:"platform,omitempty"`
}

IndexManifest is a single entry in an OCI image index's `manifests[]` array — a content-addressed pointer to a per-platform image manifest plus the platform metadata that lets clients (and the epoch UI) know which architecture/OS each child targets.

type Kind added in v0.1.7 

type Kind int

Kind classifies an OCI manifest by what it stores. The zero value is KindUnknown, which means the bytes parsed as JSON but no recognized discriminator was present. 

const (
	KindUnknown Kind = iota
	KindContainerImage
	KindCloudImage
	KindSnapshot
	// KindImageIndex is an OCI image index or Docker manifest list — a
	// multi-arch envelope that references one image manifest per platform
	// (e.g. ghcr.io/cocoonstack/cocoon/ubuntu:24.04). The index itself has
	// no layers; epoch's sync layer walks the children to compute aggregate
	// size and surface a per-platform breakdown in the UI.
	KindImageIndex
)

func Classify added in v0.1.7 

func Classify(raw []byte) (Kind, error)

Classify returns the artifact kind by inspecting the manifest in the following order of authority:

  1. Top-level `artifactType` (OCI 1.1) for cocoonstack-specific values.
  2. `config.mediaType` for plain OCI / Docker container image manifests.
  3. Top-level `mediaType` for OCI image indexes / Docker manifest lists, classified as KindImageIndex so the UI and sync layer can render the per-platform breakdown instead of treating them as a single image.

The function does not validate the manifest against the OCI spec — malformed JSON returns KindUnknown plus the parse error.

func ClassifyParsed added in v0.1.7 

func ClassifyParsed(m *OCIManifest) Kind

ClassifyParsed returns the artifact kind of an already-parsed manifest. Callers that have already called Parse use this to avoid a second JSON unmarshal of the same bytes. The ordering of authority matches Classify.

func (Kind) String added in v0.1.7 

func (k Kind) String() string

String returns a short human-readable name for the kind.

type OCIManifest added in v0.1.7 

type OCIManifest struct {
	SchemaVersion int               `json:"schemaVersion"`
	MediaType     string            `json:"mediaType,omitempty"`
	ArtifactType  string            `json:"artifactType,omitempty"`
	Config        Descriptor        `json:"config"`
	Layers        []Descriptor      `json:"layers"`
	Manifests     []IndexManifest   `json:"manifests,omitempty"`
	Subject       *Descriptor       `json:"subject,omitempty"`
	Annotations   map[string]string `json:"annotations,omitempty"`
}

OCIManifest is a parsed OCI 1.1 image manifest OR an OCI image index. The two share enough structure that we use one type for both: image manifests populate Config + Layers; image indexes populate Manifests (the per-platform child descriptors). Mutually exclusive in practice — callers branch on ClassifyParsed to know which fields to read.

func Parse added in v0.1.7 

func Parse(raw []byte) (*OCIManifest, error)

Parse decodes raw manifest bytes into an OCIManifest. Wraps the JSON error with a stable prefix so callers can match cleanly.

type Platform added in v0.1.7 

type Platform struct {
	Architecture string `json:"architecture,omitempty"`
	OS           string `json:"os,omitempty"`
	OSVersion    string `json:"os.version,omitempty"`
	Variant      string `json:"variant,omitempty"`
}

Platform describes the OS / architecture target of an image manifest inside an OCI image index. Variant is populated for arches that have sub-flavors (e.g. arm/v7, arm/v8).

type Repository 

type Repository struct {
	Tags      map[string]string `json:"tags"`
	UpdatedAt time.Time         `json:"updatedAt"`
}

Repository tracks the tags currently in use for a single repository name. Tag values point at the manifest's storage key under `epoch/manifests/...`.

type SnapshotConfig added in v0.1.7 

type SnapshotConfig struct {
	SchemaVersion string    `json:"schemaVersion"`
	SnapshotID    string    `json:"snapshotId"`
	Image         string    `json:"image,omitempty"`
	CPU           int       `json:"cpu,omitempty"`
	Memory        int64     `json:"memory,omitempty"`
	Storage       int64     `json:"storage,omitempty"`
	NICs          int       `json:"nics,omitempty"`
	CreatedAt     time.Time `json:"createdAt"`
}

SnapshotConfig is the JSON shape of the config blob referenced by a snapshot OCI manifest's `config` descriptor. Wire mediaType: MediaTypeSnapshotConfig.

The config blob captures the cocoon VM metadata that is too structured for annotations (numeric resource values, base image hex IDs). It is written as a single content-addressable blob and referenced from the manifest like any other OCI config.

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.