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
- Variables
- func Platform() string
- func ReadNodeOnly(root string, set Set) (string, bool)
- func RecordNodeOnly(root string, set Set, detail string) error
- func Root(agentDir string) string
- func SetKey(runtimeDigest []byte, members []Member) string
- func ValidID(id string) bool
- type Fallback
- type Image
- type Input
- type Installed
- type Kind
- type LockEntry
- type Manifest
- type Member
- type NodeOnlyEntry
- type Reason
- type Request
- type Resolver
- type Selection
- type Set
- type Skip
- type Source
- type Verifier
Constants ¶
const EnvRoot = "PIG_TS_RUNTIMES_DIR"
EnvRoot replaces the slot root, for CI rows and evaluation arms that keep runtimes outside the agent directory.
const EnvRuntime = "PIG_TS_RUNTIME"
EnvRuntime names the requested runtime for this process. It takes precedence over the setting.
const ManifestFile = "runtime.json"
ManifestFile is the manifest file name inside a runtime's directory.
const Node = "node"
Node is the default runtime: the node executable on PATH.
const NodeOnlyDir = ".node-only"
NodeOnlyDir is the directory inside the slot root where PiG records the extension sets that only Node runs.
const RequestsDir = "requests"
RequestsDir is the directory inside an executable runtime's directory where PiG records the extension sets it lacked an image for.
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 ¶
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 ¶
ReadNodeOnly returns the detail recorded for set when none of the files it was recorded from changed since.
func RecordNodeOnly ¶
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 ¶
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.
Types ¶
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.
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 ¶
ParseManifest decodes and validates a manifest for runtime id.
func ReadManifest ¶
ReadManifest reads and validates the manifest of runtime id under root.
type NodeOnlyEntry ¶
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 ¶
Request is the runtime a process asks for.
func RequestFrom ¶
RequestFrom returns the request of a process: PIG_TS_RUNTIME when set, else the setting, else Node.
type Resolver ¶
Resolver resolves requests against one slot root and caches verification for the life of the process.
func NewResolver ¶
NewResolver returns a resolver over root for this platform that verifies through v.
func (*Resolver) Resolve ¶
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.
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 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 ¶
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.