Documentation
¶
Overview ¶
Package bundle defines the Gemara OCI artifact format and provides Assemble, Pack, and Unpack operations for building, storing, and retrieving Gemara artifacts in OCI-compliant registries.
Index ¶
Constants ¶
const ( // MediaTypeBundle is the OCI artifactType written into the image manifest. MediaTypeBundle = "application/vnd.gemara.bundle.v1" // MediaTypeManifest is the media type for the bundle manifest blob. MediaTypeManifest = "application/vnd.gemara.manifest.v1+json" // MediaTypeArtifact is the media type for individual Gemara YAML layers. MediaTypeArtifact = "application/vnd.gemara.artifact.v1+yaml" )
OCI media types for the Gemara bundle format. All artifact layers are YAML; the assembler and resolver expect YAML input.
const ( // DefaultSizeLimitBytes caps bundle reads at 256 MB. DefaultSizeLimitBytes int64 = 256 * 1024 * 1024 )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Artifact ¶
type Artifact struct {
Name string `json:"name"`
Type string `json:"type"`
ID string `json:"id"`
Role string `json:"role"`
Dependencies []string `json:"dependencies,omitempty"`
}
Artifact describes a single file in the bundle and its position in the dependency tree, similar to rootfs in an OCI image config.
type AssembleOption ¶ added in v0.9.0
type AssembleOption func(*assembleOptions)
AssembleOption configures Assemble behaviour.
func WithContinueOnError ¶ added in v0.9.0
func WithContinueOnError() AssembleOption
WithContinueOnError makes Assemble populate Bundle.Warnings instead of returning an error when mapping-reference IDs don't match any artifact metadata.id in the assembled set.
type Assembler ¶
type Assembler struct {
// contains filtered or unexported fields
}
Assembler walks the full import graph of Gemara artifacts and produces a self-contained Bundle with all transitive dependencies fetched.
func NewAssembler ¶
NewAssembler creates an Assembler backed by the given Fetcher.
func (*Assembler) Assemble ¶
func (a *Assembler) Assemble(ctx context.Context, m Manifest, source File, opts ...AssembleOption) (*Bundle, error)
Assemble parses the source file, fetches every artifact referenced in its extends and imports via mapping-references URLs, then recursively parses fetched artifacts for their own references until the full dependency tree is resolved.
type Bundle ¶
type Bundle struct {
// Manifest is the OCI config blob describing the bundle contents.
Manifest Manifest
// Source is the primary artifact file that anchors this bundle.
Source File
// Imports are the resolved transitive dependency files.
Imports []File
// Warnings holds non-fatal issues found during assembly,
// such as mapping-reference IDs that don't match any artifact.
Warnings []MappingWarning
// Etag is the OCI manifest digest used for cache comparison.
Etag string
// contains filtered or unexported fields
}
Bundle is an in-memory representation of a Gemara OCI artifact.
func Unpack ¶
Unpack reads the OCI artifact at ref from target and returns a Bundle. The bundle's Etag is set to the hex digest of the resolved manifest.
func (*Bundle) SetSizeLimitBytes ¶
SetSizeLimitBytes configures the maximum allowed bundle size.
func (*Bundle) SizeLimitBytes ¶
SizeLimitBytes returns the configured size limit. If unset, DefaultSizeLimitBytes is returned.
type File ¶
type File struct {
// Name is the bundle-relative path, e.g. "controls.yaml".
Name string
// Type is the Gemara artifact type, e.g. "ControlCatalog".
Type string
// Data is the raw YAML content of the artifact.
Data []byte
}
File is a single Gemara YAML artifact within the bundle.
type Manifest ¶
type Manifest struct {
BundleVersion string `json:"bundle-version"`
GemaraVersion string `json:"gemara-version"`
Revision string `json:"revision,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
Artifacts []Artifact `json:"artifacts,omitempty"`
}
Manifest defines the OCI config blob stored in the bundle.
type MappingWarning ¶ added in v0.8.0
MappingWarning describes a mapping-reference whose id does not match any artifact metadata.id in the provided set.
func (MappingWarning) String ¶ added in v0.8.0
func (w MappingWarning) String() string
String formats the warning as a human-readable diagnostic message.
type PackOption ¶
type PackOption func(*packOptions)
PackOption configures Pack behaviour.
func WithAnnotations ¶
func WithAnnotations(annotations map[string]string) PackOption
WithAnnotations adds custom annotations to the OCI manifest.
func WithVersion ¶ added in v0.8.0
func WithVersion(v string) PackOption
WithVersion overrides the bundle's Manifest.BundleVersion at pack time. When not set, the version assembled from the main artifact metadata is used.
Source Files