artifact

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package artifact defines Brewlet application artifacts.

Producers supply explicit launch bytes, platforms and source/destination mappings. Build preserves launch bytes and source modes/mtimes, rejects all source xattrs, and uses sorted root-owned tar entries and fixed compression. ParseLaunch, ParseImage, ValidateMirror and RunFixtures are the shared wire validators. Resolve accepts a local BlobOpener and never contacts registries.

MaterializeLayers provides portable flattened composition in a new destination. LayerCache provides digest-and-policy-keyed persistent overlay lower directories; Linux whiteout conversion requires the corresponding host privileges. Callers run materializers as root to obtain ownership 0:0, validate cache-parent ownership, and own durable cache leases and mount-aware collection. The package does not implement node cache GC, CRI accounting, or runtime authorization.

Each layer is extracted independently. Its implicit upper directories shadow inherited directory symlinks, matching the reverse-ordered overlay lowers. Visible link targets are checked against the composed namespace without lexically collapsing ".." before preceding symlinks are resolved.

Libraries are ordinary application payload files in app layers. Referrers are discovered through OCI layout indexes, the paginated registry Referrers API, or paginated deterministic per-referrer digest tags.

VerifyGraph and the push CLI command are byte-preserving OCI transport, not Brewlet semantic validators. They can publish ordinary approved-runtime inputs and negative conformance fixtures. InspectApplication and runtime consumers independently enforce the launch and layer contract.

Package artifact implements the language-neutral Brewlet wire contract.

Index

Constants

View Source
const (
	MediaTypeCycloneDX        = "application/vnd.cyclonedx+json"
	AnnotationReferrerSubject = "brewlet.sh/referrer-subject"
)
View Source
const PolicyVersion = "v1-3"

Variables

This section is empty.

Functions

func Build

func Build(ctx context.Context, store Store, o BuildOptions) (v1.Descriptor, error)

func BuildIndex

func BuildIndex(ctx context.Context, store Store, descriptorFiles []string) (v1.Descriptor, error)

BuildIndex accepts only explicitly supplied descriptors. Their blobs must already be present in the store, and each selected artifact is verified.

func CopyGraph

func CopyGraph(ctx context.Context, source, destination Store, target v1.Descriptor) error

func MaterializeLayers

func MaterializeLayers(ctx context.Context, sources []LayerSource, destination string) error

MaterializeLayers creates a flattened, verified /app tree in a newly published destination. The caller must own the parent directory. No existing destination is ever replaced. Runtime roots and live stages must never be supplied here.

func ParseImage

func ParseImage(data []byte) (v1.Image, error)

ParseImage validates image execution fields which OCI's Image type intentionally does not model (for example Docker Healthcheck) before typed decoding drops them.

func ParsePlatform

func ParsePlatform(s string) (v1.Platform, error)

func Reason

func Reason(err error) string

func ReferrerTag

func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string

func StrictJSON

func StrictJSON(data []byte, dst any) error

StrictJSON rejects unknown fields, duplicate object members, and trailing data.

func ValidateComposition

func ValidateComposition(ctx context.Context, sources []LayerSource) error

ValidateComposition models reverse-ordered overlay lowers, including implicit upper directories which shadow inherited symlinks, then resolves every visible symlink against the composed namespace before a mount can expose it.

func ValidateMirror

func ValidateMirror(l *Launch, image v1.Image) error

func ValidateRuntimeImageID

func ValidateRuntimeImageID(id string) error

func VerifyGraph

func VerifyGraph(ctx context.Context, store Store, target v1.Descriptor) error

VerifyGraph checks the identity of every referenced OCI blob, including local referrers, without applying Brewlet launch or rootfs policy. Layers are hashed as streams and are never decompressed or rewritten.

Types

type ApplicationReport added in v0.11.0

type ApplicationReport struct {
	SchemaVersion int             `json:"schemaVersion"`
	Structural    bool            `json:"structural"`
	Root          v1.Descriptor   `json:"root"`
	Manifest      v1.Descriptor   `json:"manifest"`
	Config        v1.Descriptor   `json:"config"`
	Platform      v1.Platform     `json:"platform"`
	Layers        []v1.Descriptor `json:"layers"`
	Launch        json.RawMessage `json:"launch"`
}

ApplicationReport describes a structurally verified application graph. It makes no claim about publisher trust or vulnerability status.

func InspectApplication added in v0.11.0

func InspectApplication(ctx context.Context, store Store, target v1.Descriptor, platform v1.Platform) (ApplicationReport, error)

type BlobOpener

type BlobOpener func(v1.Descriptor) (io.ReadCloser, error)

type BuildOptions

type BuildOptions struct {
	Launch    []byte
	Platforms []v1.Platform
	Layers    []LayerSpec
}

type BuiltLayer

type BuiltLayer struct {
	Descriptor v1.Descriptor `json:"descriptor"`
	DiffID     digest.Digest `json:"diffId"`
}

func BuildLayer

func BuildLayer(ctx context.Context, store Store, spec LayerSpec) (BuiltLayer, error)

type CacheReceipt

type CacheReceipt struct {
	Policy      string    `json:"policy"`
	Digest      string    `json:"digest"`
	DiffID      string    `json:"diffId"`
	PublishedAt time.Time `json:"publishedAt"`
}

func VerifyCachedEntry

func VerifyCachedEntry(directory string) (string, CacheReceipt, error)

VerifyCachedEntry checks a canonical published entry without following a symlink for its directory, receipt, or rootfs. The caller supplies a trusted root-owned parent and holds its GC/start barrier for the entire decision. Missing or malformed receipts are uncertainty, never permission to collect.

type ContentCache

type ContentCache struct {
	Dir       string
	IsMissing func(error) bool
	// contains filtered or unexported fields
}

func (*ContentCache) Open

Open always checks the source first. Only a genuinely absent source permits retained bytes; corrupt/present, inaccessible and rejected content fails. Compressed payloads are copied/hashed as streams, never loaded into memory.

func (*ContentCache) References

func (c *ContentCache) References() []string

func (*ContentCache) Target

func (c *ContentCache) Target(ctx context.Context, target digest.Digest) (ocispec.Descriptor, error)

Target supplies the ORIGINAL target descriptor only when the caller has independently established genuine absence of the protected CRI target.

type ContentReceipt

type ContentReceipt struct {
	Policy      string             `json:"policy"`
	Descriptor  ocispec.Descriptor `json:"descriptor"`
	PublishedAt time.Time          `json:"publishedAt"`
}

ContentReceipt binds retained ORIGINAL bytes to their declaring descriptor. It is never a reconstructed manifest, config, launch document or layer.

func VerifyContentEntry

func VerifyContentEntry(ctx context.Context, entry string) (ContentReceipt, error)

type Entry

type Entry struct {
	Path, Link string
	Type       byte
	Mode       int64
	ModTime    time.Time
}

type Env

type Env struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type Error

type Error struct{ Reason, Detail string }

func (*Error) Error

func (e *Error) Error() string

type Fixture

type Fixture struct {
	Name    string           `json:"name"`
	Kind    string           `json:"kind"`
	Launch  json.RawMessage  `json:"launch,omitempty"`
	Image   json.RawMessage  `json:"image,omitempty"`
	Value   string           `json:"value,omitempty"`
	Entries []FixtureEntry   `json:"entries,omitempty"`
	Layers  [][]FixtureEntry `json:"layers,omitempty"`
	Process *Process         `json:"process,omitempty"`
	Reason  string           `json:"reason,omitempty"`
}

type FixtureEntry

type FixtureEntry struct {
	Path   string            `json:"path"`
	Type   string            `json:"type"`
	Mode   int64             `json:"mode"`
	Data   string            `json:"data,omitempty"`
	Link   string            `json:"link,omitempty"`
	Xattrs map[string]string `json:"xattrs,omitempty"`
}

type FixtureResult

type FixtureResult struct {
	Name    string   `json:"name"`
	Process *Process `json:"process,omitempty"`
	Reason  string   `json:"reason,omitempty"`
	Passed  bool     `json:"passed"`
}

func EvaluateFixture

func EvaluateFixture(ctx context.Context, f Fixture) (FixtureResult, error)

EvaluateFixture is shared by producer, shim, and cross-language conformance tests.

func RunFixtures

func RunFixtures(ctx context.Context, data []byte) ([]FixtureResult, error)

type Launch

type Launch struct {
	SchemaVersion int      `json:"schemaVersion"`
	Process       Process  `json:"process"`
	RuntimeImages []string `json:"runtimeImages,omitempty"`
}

func ParseLaunch

func ParseLaunch(data []byte) (*Launch, error)

func (*Launch) Allows

func (l *Launch) Allows(id string) bool

func (*Launch) ImageConfig

func (l *Launch) ImageConfig() v1.ImageConfig

func (Launch) MarshalJSON

func (l Launch) MarshalJSON() ([]byte, error)

Preserve an explicit deny-all [] rather than dropping it through omitempty.

type LayerCache

type LayerCache struct{ Dir string }

LayerCache stores immutable per-compressed-digest overlay lowers. Its trusted, root-owned parent must live on persistent storage. The node owns cache leases and must not collect entries with live mounts or durable task references.

func (LayerCache) Materialize

func (c LayerCache) Materialize(ctx context.Context, source LayerSource) (string, error)

type LayerInfo

type LayerInfo struct {
	DiffID  digest.Digest
	Entries []Entry
	Launch  []byte
}

func WalkLayer

func WalkLayer(ctx context.Context, src LayerSource, visit func(*tar.Header, io.Reader) error) (*LayerInfo, error)

WalkLayer verifies compressed identity and diff ID while streaming. The visitor must consume each regular file before returning; unread bytes are drained.

type LayerSource

type LayerSource struct {
	Descriptor v1.Descriptor
	DiffID     digest.Digest
	Open       func() (io.ReadCloser, error)
}

type LayerSpec

type LayerSpec struct {
	Role, Source, Destination string
	Platform                  *v1.Platform
}

LayerSpec describes one producer layer. A nil Platform applies the layer to every declared platform; otherwise it belongs only to that platform manifest.

func ParseLayerSpec

func ParseLayerSpec(s string) (LayerSpec, error)

ParseLayerSpec parses [OS/ARCH[/VARIANT]:]SOURCE:/app/PATH as app payload.

type Process

type Process struct {
	Entrypoint []string `json:"entrypoint"`
	Args       []string `json:"args,omitempty"`
	WorkingDir string   `json:"workingDir,omitempty"`
	Env        []Env    `json:"env,omitempty"`
}

type Registry

type Registry struct {
	Origin                *url.URL
	Repository, Reference string
	Username, Password    string
	Client                *http.Client
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry(ref string, insecure bool) (*Registry, error)

func (*Registry) FetchBlob

func (r *Registry) FetchBlob(ctx context.Context, d digest.Digest, max int64) ([]byte, error)

FetchBlob fetches a small blob such as an image config, bounded by max bytes, and verifies its digest.

func (*Registry) FetchManifest

func (r *Registry) FetchManifest(ctx context.Context, key string) (v1.Descriptor, []byte, error)

FetchManifest fetches the manifest or index named by key (a tag or a digest) without importing its graph. The returned descriptor carries the digest of the exact bytes served, so a tag resolves to a canonical digest; digest keys are verified.

func (*Registry) Pull

func (r *Registry) Pull(ctx context.Context, store Store) (v1.Descriptor, error)

Pull imports a manifest/index and its full graph into a local layout CAS.

func (*Registry) Push

func (r *Registry) Push(ctx context.Context, store Store, target v1.Descriptor) error

func (*Registry) Referrers

func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)

type Resolved

type Resolved struct {
	Reference                  string
	Target, ManifestDescriptor v1.Descriptor
	Manifest                   v1.Manifest
	Image                      v1.Image
	Launch                     *Launch
	LaunchJSON                 []byte
	Layers                     []LayerSource
	ContentRoots               []string
}

func Resolve

func Resolve(ctx context.Context, open BlobOpener, target v1.Descriptor, platform v1.Platform) (*Resolved, error)

Resolve verifies a strict platform selection, config mirror and every streamed layer. open must read local content only; Resolve never accesses a registry.

type Store

type Store struct{ Dir string }

func (Store) Open

func (s Store) Open(d v1.Descriptor) (io.ReadCloser, error)

func (Store) Put

func (s Store) Put(media string, r io.Reader) (v1.Descriptor, error)

func (Store) PutJSON

func (s Store) PutJSON(media string, v any) (v1.Descriptor, error)

func (Store) Read

func (s Store) Read(d v1.Descriptor) ([]byte, error)

func (Store) RecordReferrer

func (s Store) RecordReferrer(subject, descriptor v1.Descriptor) error

func (Store) Referrers

func (s Store) Referrers(subject v1.Descriptor) ([]v1.Descriptor, error)

func (Store) Target

func (s Store) Target(ref string) (v1.Descriptor, error)

func (Store) WriteIndex

func (s Store) WriteIndex(target v1.Descriptor, ref string) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL