runtimecell

package
v0.3.1 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package runtimecell builds and resolves packed extension runtime cells.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ArtifactIdentity

func ArtifactIdentity(entryDir string) (string, bool)

ArtifactIdentity returns the immutable digest recorded when an entry was published.

func CurrentGoPackedCellEntry

func CurrentGoPackedCellEntry(cacheRoot, key string, extensions []GoExtension) (string, bool, error)

CurrentGoPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildGoPackedCell, without building it.

func CurrentPythonPackedCellEntry

func CurrentPythonPackedCellEntry(cacheRoot, key string, extensions []PythonExtension) (string, bool, error)

CurrentPythonPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildPythonPackedCell, without building it.

func CurrentRustPackedCellEntry

func CurrentRustPackedCellEntry(cacheRoot, key string, extensions []RustExtension) (string, bool, error)

CurrentRustPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildRustPackedCell, without building it.

func ExtPackageName

func ExtPackageName(name string) string

ExtPackageName returns a deterministic import alias for a generated packed or fused extension registry.

func GoSDKPathOverride

func GoSDKPathOverride(root string) string

GoSDKPathOverride returns an extension module's explicit local SDK replace.

func HasCacheEntries

func HasCacheEntries(cacheRoot string) (bool, error)

HasCacheEntries reports whether PruneCaches and InspectCache would classify at least one entry under cacheRoot.

func MarkArtifactUsed

func MarkArtifactUsed(artifactPath string, now time.Time) error

func ResolvePrebuilt

func ResolvePrebuilt(req PrebuiltRequest) (string, bool)

ResolvePrebuilt exposes the process-wide prebuilt-cell resolver to other host packages (e.g. the source-mode subprocess builder). Returns ("", false) when no resolver is registered, so stock pig behavior is unchanged.

func RustSDKPathOverride

func RustSDKPathOverride(root string) string

RustSDKPathOverride returns an extension crate's explicit local SDK path.

func SetPrebuiltResolver

func SetPrebuiltResolver(r PrebuiltResolver)

SetPrebuiltResolver installs the process-wide prebuilt-cell resolver, or nil to restore the default from-source behavior.

func SocketEnvName

func SocketEnvName(name string) string

SocketEnvName returns the environment variable used to pass one extension's socket into a packed-cell runner.

func StageLegacyGoSDK

func StageLegacyGoSDK(sdkRoot, dst string) error

StageLegacyGoSDK copies the SDK module and its subpackages into dst under the legacy import path. Self-imports follow the alias, including internal packages. Authored SDK sources remain untouched. pig additive (D19): legacy Go imports use the running host's SDK contract.

func TouchUsage

func TouchUsage(entryDir string, now time.Time) error

func ValidEntry

func ValidEntry(entryDir string, want EntryIdentity) (string, bool)

ValidEntry reports whether a cache directory contains a complete artifact published for want on this platform.

Types

type CacheClass

type CacheClass string
const (
	CacheActive           CacheClass = "active"
	CacheCurrent          CacheClass = "current"
	CacheBuilding         CacheClass = "building"
	CacheInactiveRetained CacheClass = "inactive-retained"
	CacheInactiveExpired  CacheClass = "inactive-expired"
	CacheInvalid          CacheClass = "incomplete/invalid"
)

type CacheEntry

type CacheEntry struct {
	Path     string     `json:"path"`
	Class    CacheClass `json:"class"`
	Bytes    int64      `json:"bytes"`
	LastUsed int64      `json:"lastUsed,omitempty"`
	Reason   string     `json:"reason,omitempty"`
}

type CacheLifecycleOptions

type CacheLifecycleOptions struct {
	CacheRoot        string
	Current          map[string]struct{}
	LiveFingerprints map[string]struct{}
	Now              func() time.Time
	Retention        time.Duration
	CrashGrace       time.Duration
	MaxSize          *int64
	DryRun           bool
	Rename           func(string, string) error
	RemoveAll        func(string) error
}

type CacheReport

type CacheReport struct {
	Entries        []CacheEntry       `json:"entries"`
	ByClass        map[CacheClass]int `json:"byClass"`
	TotalBytes     int64              `json:"totalBytes"`
	RemovedBytes   int64              `json:"removedBytes"`
	Removed        int                `json:"removed"`
	ProtectedBytes int64              `json:"protectedBytes"`
	LimitSatisfied bool               `json:"limitSatisfied"`
	Errors         []string           `json:"errors,omitempty"`
}

func InspectCache

func InspectCache(options CacheLifecycleOptions) (CacheReport, error)

func PruneCaches

func PruneCaches(options CacheLifecycleOptions) (CacheReport, error)

type EntryIdentity

type EntryIdentity struct {
	InputDigest string
	Artifact    string
	Language    string
}

EntryIdentity is the publication identity a caller expects of a cache entry: the input digest that names it, its canonical artifact filename, and the language that built it.

type GoExtension

type GoExtension struct {
	Name             string
	Root             string
	ModulePath       string
	Package          string
	Factory          string
	Hash             string
	WorkspaceModules []string
}

GoExtension describes one factory-style Go SDK extension that can be packed into a generated subprocess runner. The extension package must expose a factory function with signature:

func Extension() *sdk.Extension

or the Factory name supplied here.

type GoPackedCell

type GoPackedCell struct {
	Key           string
	Hash          string
	CacheDir      string
	BinaryPath    string
	Cached        bool
	BuildDuration time.Duration
	Extensions    []GoExtension
	// Generation is this spawn attempt's packed-cell generation number
	// (pig additive, CNC-002), claimed by the caller before any build work so
	// an async crash report for a process this attempt is replacing cannot
	// mistake itself for still current. Zero (the default, for callers that
	// never claim one) makes the host claim the generation at spawn.
	Generation int
}

GoPackedCell describes a generated runner artifact. Packing is an execution optimization only: the generated binary is still a subprocess and each contained extension uses its own host socket.

func BuildGoPackedCell

func BuildGoPackedCell(ctx context.Context, cacheRoot, key string, extensions []GoExtension) (*GoPackedCell, error)

BuildGoPackedCell generates and builds a Go runner that hosts multiple factory-style Go SDK extensions in one subprocess artifact. The artifact is cached by a deterministic cell hash derived from the extension hashes and factory/package metadata.

func BuildGoPackedCellWithSDKRoot

func BuildGoPackedCellWithSDKRoot(ctx context.Context, cacheRoot, key string, extensions []GoExtension, preferredSDKRoot string) (*GoPackedCell, error)

BuildGoPackedCellWithSDKRoot builds a packed cell using preferredSDKRoot when the extensions do not declare their own valid SDK replacement. Hosts use this to keep packed builds on the running process's resolved config root.

type PrebuiltExtension

type PrebuiltExtension struct {
	Name string
	Hash string
}

PrebuiltExtension identifies one extension inside a cell composition.

type PrebuiltRequest

type PrebuiltRequest struct {
	Language   string // "go" | "rust" | "python"
	Key        string // cell key (pack group)
	GOOS       string
	GOARCH     string
	Extensions []PrebuiltExtension
}

PrebuiltRequest describes the packed cell the host is about to build.

type PrebuiltResolver

type PrebuiltResolver interface {
	ResolvePrebuilt(PrebuiltRequest) (binaryPath string, ok bool)
}

PrebuiltResolver maps a cell composition to an already-built binary. The resolver owns the match policy (e.g. how strictly to compare pinned hashes); the host only supplies the composition it is about to build.

type PublishedEntry

type PublishedEntry struct {
	Dir          string
	ArtifactPath string
	Reused       bool // an existing valid entry satisfied the request without building
}

PublishedEntry is the result of resolving a content-addressed cache entry.

func PublishArtifact

func PublishArtifact(ctx context.Context, finalDir, canonicalName, inputDigest, language string, build func(scratch string) (artifactPath string, err error), keepAlso ...string) (PublishedEntry, error)

PublishArtifact deduplicates construction of a content-addressed cache entry across processes, for packed runtime cells and for compiled source-mode extension binaries alike. finalDir is the entry directory (named by inputDigest); canonicalName is the single published artifact's filename. build runs inside a private scratch directory and returns the finished primary artifact. The artifact can live in an external compiler cache; publication copies it into scratch before atomically renaming the complete entry.

Exactly one process builds a given finalDir: callers take a per-digest advisory lock (released automatically on process death, so a crash never wedges the cache), re-check the cache under the lock, then build into private scratch and publish with a single atomic rename. Readers therefore never observe a half-written entry, distinct Pig instances share one built artifact instead of each rebuilding it, and only {canonicalName, ready.json} is retained - compiler intermediates (generated source, Rust target/) are discarded.

func ReusePublishedArtifact

func ReusePublishedArtifact(finalDir string, want EntryIdentity) (PublishedEntry, bool)

ReusePublishedArtifact returns the complete entry at finalDir published for want, if one exists, and records its use. It never builds or waits for a lock.

type PythonExtension

type PythonExtension struct {
	Name    string
	Root    string
	Package string
	Factory string
	Hash    string
}

PythonExtension describes one factory-style Python SDK extension that can be packed into a generated subprocess runner. The module must expose a factory returning pig_sdk.Extension, typically:

def new_extension() -> pig_sdk.Extension

The generated runner is a Python subprocess and uses one socket per contained extension.

type PythonPackedCell

type PythonPackedCell struct {
	Key           string
	Hash          string
	CacheDir      string
	BinaryPath    string
	Cached        bool
	BuildDuration time.Duration
	Extensions    []PythonExtension
}

PythonPackedCell describes a generated Python packed-cell artifact.

func BuildPythonPackedCell

func BuildPythonPackedCell(ctx context.Context, cacheRoot, key string, extensions []PythonExtension) (*PythonPackedCell, error)

type RustExtension

type RustExtension struct {
	Name    string
	Root    string
	Package string
	Crate   string
	Factory string
	Hash    string
}

RustExtension describes one factory-style Rust SDK extension that can be packed into a generated subprocess runner. The crate must expose a factory function returning pig_sdk::Extension, typically:

pub fn new_extension() -> pig_sdk::Extension

The generated runner still runs as a subprocess and uses one socket per contained extension.

type RustPackedCell

type RustPackedCell struct {
	Key           string
	Hash          string
	CacheDir      string
	BinaryPath    string
	Cached        bool
	BuildDuration time.Duration
	Extensions    []RustExtension
}

RustPackedCell describes a generated Rust packed-cell artifact.

func BuildRustPackedCell

func BuildRustPackedCell(ctx context.Context, cacheRoot, key string, extensions []RustExtension) (*RustPackedCell, error)

BuildRustPackedCell generates and builds a Cargo runner that hosts multiple factory-style Rust SDK extensions in one subprocess artifact.

type UsageLease

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

func AcquireArtifactUsageLease

func AcquireArtifactUsageLease(artifactPath string) (*UsageLease, error)

func AcquireUsageLease

func AcquireUsageLease(entryDir string) (*UsageLease, error)

func (*UsageLease) Release

func (l *UsageLease) Release() error

type UsageMetadata

type UsageMetadata struct {
	LastUsed int64 `json:"lastUsed"`
}

Jump to

Keyboard shortcuts

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