Documentation
¶
Overview ¶
Package tpd is the launch engine for the tpd CLI.
It is in-module-only, not a public library API. The package exists to keep cmd/tpd thin and to make launch logic unit-testable; its exported names (Launch, LaunchOpts, Result, PortAllocator) are used by the CLI and by the package's own tests. The spec types it operates on (Spec, MountSpec, PortSpec, ...) live in internal/runtime and are deliberately not re-exported here — the type aliases that once surfaced them implied external consumers could construct them, so they were removed. The internal/ rule enforces the boundary: an external module cannot import internal/runtime, internal/approval, or internal/workspace, so it cannot name the spec types, implement the Runtime/Progress/approval interfaces, or satisfy LaunchOpts.Runtime/.Progress/.ApprovalStore/.ApprovalPrompt. LaunchOpts fields that carry only public types (ProfileName, Workspace, PortAllocator, ...) are the entire usable surface from outside the module. The fixture module under pkg/tpd/testdata/externalconsumer proves this by compiling an external consumer against the package and asserting the internal surface is unreachable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LaunchOpts ¶
type LaunchOpts struct {
ProfileName string
Args []string
Command string
Workspace string
ProfileDir string
ExtraTools []string
DryRun bool
Verbose bool
// Pull re-pulls the base image even when already present locally,
// refreshing mutable tags like latest.
Pull bool
Runtime runtime.Runtime
// Progress receives status lines during Prepare (image pull, mise
// install). If nil, progress goes to Stderr. Set to a no-op writer
// to silence progress entirely.
Progress runtime.ProgressWriter
// Stderr receives diagnostics during launch: spinner/progress output,
// stop-services and dbus-proxy warnings. Container stdout is unaffected:
// the runtime pumps it to os.Stdout directly; the writer passed to
// LaunchWithWriter carries only rendered preview output and approval
// prompts. If nil, diagnostics go to os.Stderr.
Stderr io.Writer
// PortAllocator reserves host ports for auto-allocated bindings. If
// nil, an ephemeral socket bind is used. Injectable for deterministic
// tests.
PortAllocator PortAllocator
In io.Reader
ApprovalStore approval.Store
ApprovalPrompt approval.Prompt
IsTTY func(io.Reader) bool
AssumeYes bool
AssumeNo bool
}
LaunchOpts carries the inputs to Launch. Runtime, Progress, ApprovalStore, and ApprovalPrompt are injection points for in-module fakes: their interfaces live in internal/ packages, so only code inside this module can provide them. The remaining fields carry only public types and are what the CLI and any future consumer can set.
type PortAllocator ¶
PortAllocator reserves an unused host port for a published binding. protocol is "tcp", "udp", or "sctp"; hostIP is the requested bind address ("" = all interfaces). Returns the allocated port as a string.
Allocation is necessarily best-effort: tpd binds an ephemeral socket to find a free port and closes it before the engine binds the real port at container start, so another process can claim the port in that window. The engine surfaces a collision only as a generic create/start failure, not a distinct tpd error, so no retry is attempted. This does not eliminate the race.
Source Files