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
- func Build(ctx context.Context, store Store, o BuildOptions) (v1.Descriptor, error)
- func BuildIndex(ctx context.Context, store Store, descriptorFiles []string) (v1.Descriptor, error)
- func CopyGraph(ctx context.Context, source, destination Store, target v1.Descriptor) error
- func MaterializeLayers(ctx context.Context, sources []LayerSource, destination string) error
- func ParseImage(data []byte) (v1.Image, error)
- func ParsePlatform(s string) (v1.Platform, error)
- func Reason(err error) string
- func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string
- func StrictJSON(data []byte, dst any) error
- func ValidateComposition(ctx context.Context, sources []LayerSource) error
- func ValidateMirror(l *Launch, image v1.Image) error
- func ValidateRuntimeImageID(id string) error
- func VerifyGraph(ctx context.Context, store Store, target v1.Descriptor) error
- type ApplicationReport
- type BlobOpener
- type BuildOptions
- type BuiltLayer
- type CacheReceipt
- type ContentCache
- type ContentReceipt
- type Entry
- type Env
- type Error
- type Fixture
- type FixtureEntry
- type FixtureResult
- type Launch
- type LayerCache
- type LayerInfo
- type LayerSource
- type LayerSpec
- type Process
- type Registry
- func (r *Registry) FetchBlob(ctx context.Context, d digest.Digest, max int64) ([]byte, error)
- func (r *Registry) FetchManifest(ctx context.Context, key string) (v1.Descriptor, []byte, error)
- func (r *Registry) Pull(ctx context.Context, store Store) (v1.Descriptor, error)
- func (r *Registry) Push(ctx context.Context, store Store, target v1.Descriptor) error
- func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)
- type Resolved
- type Store
- func (s Store) Open(d v1.Descriptor) (io.ReadCloser, error)
- func (s Store) Put(media string, r io.Reader) (v1.Descriptor, error)
- func (s Store) PutJSON(media string, v any) (v1.Descriptor, error)
- func (s Store) Read(d v1.Descriptor) ([]byte, error)
- func (s Store) RecordReferrer(subject, descriptor v1.Descriptor) error
- func (s Store) Referrers(subject v1.Descriptor) ([]v1.Descriptor, error)
- func (s Store) Target(ref string) (v1.Descriptor, error)
- func (s Store) WriteIndex(target v1.Descriptor, ref string) error
Constants ¶
const ( MediaTypeCycloneDX = "application/vnd.cyclonedx+json" AnnotationReferrerSubject = "brewlet.sh/referrer-subject" )
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 ¶
BuildIndex accepts only explicitly supplied descriptors. Their blobs must already be present in the store, and each selected artifact is verified.
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 ¶
ParseImage validates image execution fields which OCI's Image type intentionally does not model (for example Docker Healthcheck) before typed decoding drops them.
func ReferrerTag ¶
func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string
func StrictJSON ¶
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 ValidateRuntimeImageID ¶
func VerifyGraph ¶
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 BuiltLayer ¶
type BuiltLayer struct {
Descriptor v1.Descriptor `json:"descriptor"`
DiffID digest.Digest `json:"diffId"`
}
func BuildLayer ¶
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 ¶
func (c *ContentCache) Open(ctx context.Context, source BlobOpener, d ocispec.Descriptor) (io.ReadCloser, error)
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 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 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 (*Launch) ImageConfig ¶
func (l *Launch) ImageConfig() v1.ImageConfig
func (Launch) MarshalJSON ¶
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 LayerSource ¶
type LayerSource struct {
Descriptor v1.Descriptor
DiffID digest.Digest
Open func() (io.ReadCloser, error)
}
type LayerSpec ¶
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 ¶
ParseLayerSpec parses [OS/ARCH[/VARIANT]:]SOURCE:/app/PATH as app payload.
type Registry ¶
type Registry struct {
Origin *url.URL
Repository, Reference string
Username, Password string
Client *http.Client
// contains filtered or unexported fields
}
func (*Registry) FetchBlob ¶
FetchBlob fetches a small blob such as an image config, bounded by max bytes, and verifies its digest.
func (*Registry) FetchManifest ¶
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) Referrers ¶
func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)
type Resolved ¶
type Store ¶
type Store struct{ Dir string }
func (Store) Open ¶
func (s Store) Open(d v1.Descriptor) (io.ReadCloser, 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) WriteIndex ¶
func (s Store) WriteIndex(target v1.Descriptor, ref string) error