tsruntime

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package tsruntime selects the runtime that runs PiG's TypeScript and JavaScript extension host.

pig additive (D19): Pi runs extensions inside its own Node process. PiG runs them in a subprocess, which Node runs by default. A user may request another runtime that an extension or Piglet installed into the runtime slot; PiG itself downloads nothing. The slot is a directory per runtime under Root, each holding a runtime.json Manifest. A requested runtime that cannot be used falls back to Node once, with a typed Reason.

Index

Constants

View Source
const EnvRoot = "PIG_TS_RUNTIMES_DIR"

EnvRoot replaces the slot root, for CI rows and evaluation arms that keep runtimes outside the agent directory.

View Source
const EnvRuntime = "PIG_TS_RUNTIME"

EnvRuntime names the requested runtime for this process. It takes precedence over the setting.

View Source
const ManifestFile = "runtime.json"

ManifestFile is the manifest file name inside a runtime's directory.

View Source
const Node = "node"

Node is the default runtime: the node executable on PATH.

View Source
const NodeOnlyDir = ".node-only"

NodeOnlyDir is the directory inside the slot root where PiG records the extension sets that only Node runs.

View Source
const RequestsDir = "requests"

RequestsDir is the directory inside an executable runtime's directory where PiG records the extension sets it lacked an image for.

View Source
const UsedFile = ".used"

UsedFile is the file inside an image's directory whose modification time records when PiG last started a set from the image. A provider that prunes images reads it to evict the least recently used first.

Variables

View Source
var Lock = []LockEntry{
	{Runtime: "bun", Version: "1.4.2", Platform: "linux-x64", Variant: "bun-linux-x64", SHA256: "a83d263767d839e4d2649ca8e35d07159c7afc99afdc96d731ced29e056dda0c"},
	{Runtime: "bun", Version: "1.4.2", Platform: "linux-x64", Variant: "bun-linux-x64-musl", SHA256: "16b72935ffd7a503b978c186874539c92aade4e3515b70a5abf5db2581fdef7d"},
	{Runtime: "bun", Version: "1.4.2", Platform: "linux-arm64", Variant: "bun-linux-aarch64", SHA256: "616f267a34278ff5ac282df37ffdfba1d7141f4f6926bca99af2cd6ef3ad32b1"},
	{Runtime: "bun", Version: "1.4.2", Platform: "linux-arm64", Variant: "bun-linux-aarch64-musl", SHA256: "1101cd0aa92ea214c2aaf4bb3761ca3c76a90aae0e6f94c07efb4e8c4f18a8fc"},
	{Runtime: "bun", Version: "1.4.2", Platform: "darwin-x64", Variant: "bun-darwin-x64", SHA256: "2fa513af22ac59e03aae640cad302e73cb1ddb0f6398501e2ddccf7dcd613596"},
	{Runtime: "bun", Version: "1.4.2", Platform: "darwin-arm64", Variant: "bun-darwin-aarch64", SHA256: "35d20dd0263e5c950194434b925454fdfa9ba6e4467da960410fa05b08a7a5b5"},
	{Runtime: "bun", Version: "1.4.2", Platform: "android-x64", Variant: "bun-linux-x64-android", SHA256: "12222610d9a72265ecb5955e09e009bc2b32cd9624427f8a76bec34965917054"},
	{Runtime: "bun", Version: "1.4.2", Platform: "android-arm64", Variant: "bun-linux-aarch64-android", SHA256: "f2970336bfccf36e4e8a408b25c627122f210e941672f184198c31f4dbd377a0"},
	{Runtime: "bun", Version: "1.4.2", Platform: "windows-x64", Variant: "bun-windows-x64", SHA256: "15277c59ccd6c6c20f8dc9716c2b59c1776320d606b6a8658f70be8799519ca4"},
	{Runtime: "bun", Version: "1.4.2", Platform: "windows-arm64", Variant: "bun-windows-aarch64", SHA256: "3d7e98d3201c55c3bde6c069a5dfa0d34da9edc9145187c76594f685f8aa54c6"},
}

Lock is the runtime lock. Each digest is the SHA-256 of the bun executable inside the release archive https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/<variant>.zip, whose digest SHASUMS256.txt lists; that file carries a valid OpenPGP signature by Robobun <robobun@oven.sh>, key F3DCC08A8572C0749B3E18888EAB4D40A7B22B59. Bun 1.4.2's baseline archives carry the same executable as their default archives.

Functions

func Platform

func Platform() string

Platform names the running platform as PiG's release targets do: <os>-<arch> with os linux, darwin, windows or android and arch x64 or arm64.

func ReadNodeOnly

func ReadNodeOnly(root string, set Set) (string, bool)

ReadNodeOnly returns the detail recorded for set when none of the files it was recorded from changed since.

func RecordNodeOnly

func RecordNodeOnly(root string, set Set, detail string) error

RecordNodeOnly remembers that set started on Node after a slot runtime failed to start it, so later launches of the set run on Node. pig additive (D19): Pi has one runtime, so it has no runtime to fall back from.

func Root

func Root(agentDir string) string

Root is the slot root for an agent directory: PIG_TS_RUNTIMES_DIR when set, else <agentDir>/runtimes/typescript. It returns "" when neither is known.

func SetKey

func SetKey(runtimeDigest []byte, members []Member) string

SetKey identifies an extension set: the digest of the runtime tree it runs with and its members in admission order.

func ValidID

func ValidID(id string) bool

ValidID reports whether id can name a runtime in the slot. Node is a valid request but never a slot directory.

Types

type Fallback

type Fallback struct {
	Reason Reason `json:"reason"`
	Detail string `json:"detail"`
}

Fallback records why a requested runtime was not used.

type Image

type Image struct {
	// Executable is the path of the executable relative to the runtime's directory.
	Executable string `json:"executable"`
	// SHA256 is the lowercase hex SHA-256 digest of the executable.
	SHA256 string `json:"sha256"`
	// Inputs are the files the image was built from; empty for a runtime that compiles nothing in.
	//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
	Inputs []Input `json:"inputs,omitempty"`
}

Image is one executable of a runtime.

type Input

type Input struct {
	Path    string `json:"path"`
	Size    int64  `json:"size"`
	MtimeNs int64  `json:"mtimeNs"`
}

Input is a file an executable image was built from. PiG treats the image as stale once the file's size or modification time differs.

type Installed

type Installed struct {
	ID       string    `json:"id"`
	Manifest *Manifest `json:"manifest,omitempty"`
	// Error is why the directory's manifest is not usable.
	Error string `json:"error,omitempty"`
}

Installed is one directory of the slot.

func List

func List(root string) ([]Installed, error)

List returns the slot's runtime directories in name order. A missing root lists nothing.

type Kind

type Kind string

Kind is how PiG launches a runtime.

const (
	// KindBun is a stock Bun executable that runs PiG's runtime tree: <exe> --no-install --no-env-file --config=<empty> --preload <loader> <cli.mjs|cell.mjs> <args>.
	KindBun Kind = "bun"
	// KindExecutable is a host executable built from PiG's runtime tree: <exe> cli|cell <args>, with the runtime tree in PIG_TS_RUNTIME_TREE.
	KindExecutable Kind = "executable"
)

type LockEntry

type LockEntry struct {
	Runtime  string
	Version  string
	Platform string
	// Variant names the release archive the executable comes from, for review.
	Variant string
	SHA256  string
}

LockEntry pins one executable PiG runs as a Bun runtime. A Bun runtime whose executable digest is not in the lock for its version and platform does not run: the lock, not the manifest, decides which Bun binaries PiG trusts.

type Manifest

type Manifest struct {
	ID       string `json:"id"`
	Kind     Kind   `json:"kind"`
	Version  string `json:"version"`
	Platform string `json:"platform"`
	// Provider names the extension or Piglet that installed the runtime, for status output.
	Provider string `json:"provider"`
	// Image is the executable for any extension set. A Bun runtime has exactly this one.
	Image *Image `json:"image,omitempty"`
	// Sets holds an executable runtime's images per extension set, keyed by SetKey.
	//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
	Sets map[string]Image `json:"sets,omitempty"`
	// Fallback names the slot runtime PiG tries when this one cannot run a set, before Node. Empty means Node.
	Fallback string `json:"fallback,omitempty"`
}

Manifest is <root>/<id>/runtime.json. The shape is strict: an unknown field is an invalid manifest.

func ParseManifest

func ParseManifest(id string, data []byte) (Manifest, error)

ParseManifest decodes and validates a manifest for runtime id.

func ReadManifest

func ReadManifest(root, id string) (Manifest, error)

ReadManifest reads and validates the manifest of runtime id under root.

type Member

type Member struct {
	Name  string `json:"name"`
	Entry string `json:"entry"`
}

Member is one extension of a set, as the host admits it.

type NodeOnlyEntry

type NodeOnlyEntry struct {
	Members []Member `json:"members"`
	Detail  string   `json:"detail"`
}

NodeOnlyEntry is one recorded Node-only extension set, for status output.

func ListNodeOnly

func ListNodeOnly(root string) []NodeOnlyEntry

ListNodeOnly returns the current Node-only records in file name order.

type Reason

type Reason string

Reason is why a requested runtime was not used.

const (
	// ReasonInvalidRequest: the requested name is not a runtime name.
	ReasonInvalidRequest Reason = "invalid_request"
	// ReasonNotInstalled: the slot has no manifest for the requested runtime, or the slot root cannot be resolved.
	ReasonNotInstalled Reason = "not_installed"
	// ReasonInvalidManifest: the manifest cannot be read or does not have the current shape.
	ReasonInvalidManifest Reason = "invalid_manifest"
	// ReasonUnsupportedPlatform: the runtime was installed for another platform.
	ReasonUnsupportedPlatform Reason = "unsupported_platform"
	// ReasonNoImage: an executable runtime has no image for this extension set.
	ReasonNoImage Reason = "no_image"
	// ReasonStale: a file an executable image was built from changed since the build.
	ReasonStale Reason = "stale"
	// ReasonVerifyFailed: the executable's digest differs from its manifest, or a Bun executable is not in the lock.
	ReasonVerifyFailed Reason = "verify_failed"
	// ReasonStartFailed: the executable did not answer --version.
	ReasonStartFailed Reason = "start_failed"
	// ReasonNodeOnly: a launch of this extension set failed to start on a slot runtime and loaded on Node, and nothing it was built from changed since, so the set runs on Node.
	ReasonNodeOnly Reason = "node_only"
)

type Request

type Request struct {
	ID     string `json:"id"`
	Source Source `json:"source"`
}

Request is the runtime a process asks for.

func RequestFrom

func RequestFrom(env, setting string) Request

RequestFrom returns the request of a process: PIG_TS_RUNTIME when set, else the setting, else Node.

type Resolver

type Resolver struct {
	Root     string
	Platform string
	// contains filtered or unexported fields
}

Resolver resolves requests against one slot root and caches verification for the life of the process.

func NewResolver

func NewResolver(root string, v *Verifier) *Resolver

NewResolver returns a resolver over root for this platform that verifies through v.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, req Request, set Set) Selection

Resolve selects the runtime for set. A request for a slot runtime that cannot run the set falls back to Node with the reason. For an executable runtime without a current image for the set, it records the set under the runtime's requests directory so the runtime's provider can build one; the request file's write error, if any, is part of the fallback detail.

func (*Resolver) ResolveAfter

func (r *Resolver) ResolveAfter(ctx context.Context, sel Selection, set Set, detail string) Selection

ResolveAfter continues a selection whose runtime failed to start the set: the failed runtime is skipped with ReasonStartFailed and detail, then, when it was the requested runtime, the runtime its manifest names as fallback is tried, then Node.

type Selection

type Selection struct {
	Request Request `json:"request"`
	// Runtime is "node" or the id of the slot runtime that runs the set.
	Runtime string `json:"runtime"`
	Kind    Kind   `json:"kind,omitempty"`
	Version string `json:"version,omitempty"`
	// Executable is the absolute path of the slot runtime's executable; empty for Node.
	Executable string `json:"executable,omitempty"`
	// Fallback is set when the requested runtime does not run this set: why it does not.
	Fallback *Fallback `json:"fallback,omitempty"`
	// Skipped lists every runtime tried before the one that runs the set, in order: the requested one, then its manifest's fallback.
	//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
	Skipped []Skip `json:"skipped,omitempty"`
}

Selection is the runtime that runs one extension set.

func (Selection) IsNode

func (s Selection) IsNode() bool

IsNode reports whether the set runs on Node.

type Set

type Set struct {
	// Key identifies the set across processes: SetKey of the runtime tree's digest and the members.
	Key     string   `json:"key"`
	Members []Member `json:"members"`
	// RuntimeTree is the materialized runtime tree the process runs.
	RuntimeTree string `json:"runtimeTree"`
}

Set is the extension set one runtime process hosts.

type Skip

type Skip struct {
	Runtime string `json:"runtime"`
	Reason  Reason `json:"reason"`
	Detail  string `json:"detail"`
}

Skip is one runtime that a selection did not use, with the reason.

type Source

type Source string

Source is where a request came from.

const (
	SourceDefault Source = "default"
	SourceSetting Source = "setting"
	SourceEnv     Source = "env"
)

type Verifier

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

Verifier checks slot executables against their manifests and the lock, once per executable state for the life of the process.

func NewVerifier

func NewVerifier(lock []LockEntry) *Verifier

NewVerifier returns a verifier over the given lock that starts each executable with --version.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, m Manifest, executable, digest string) (Reason, error)

Verify checks that executable has the manifest's digest, that a Bun executable is in the lock, and that the executable starts and answers --version (a Bun executable with the manifest's version). It returns the reason with the error.

Jump to

Keyboard shortcuts

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