runtime

package
v0.0.16 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MPL-2.0 Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ServiceNetworkName  = "tpd-services"
	NetworkRoleLabel    = "tpd.network-role"
	NetworkRoleServices = "services"
)
View Source 
const (
	ServiceLabel       = "tpd.service"
	ServiceRoleLabel   = "tpd.service-role"
	ServiceRoleSidecar = "sidecar"
	ServiceHashLabel   = "tpd.service-hash"
	UsesServiceLabel   = "tpd.uses-service"
)
View Source 
const OwnershipLabel = "tpd.managed"

Variables

This section is empty.

Functions

func CacheSubpath 

func CacheSubpath(target string) string

CacheSubpath derives the stable per-target cache key: the first 8 hex chars of the sha256 of the target path. Hashing keeps the key order-independent and collision-safe as profiles add or remove cache paths.

func DaemonInfo added in v0.0.8 

func DaemonInfo(ctx context.Context, cli *client.Client) (system.Info, error)

DaemonInfo returns the engine's /info, bounded by daemonHTTPTimeout so a reachable-but-hung daemon cannot block the caller indefinitely. Exported for tpd doctor. The SDK client itself is unbounded: a client-level timeout would cut off its long-running streams (image pulls, container waits).

func DerivedRef 

func DerivedRef(repoTag string) string

DerivedRef normalizes a RepoTag from ImageList into the canonical tpd/packages:<hash> form, or "" if the tag doesn't belong to a derived image. Engines qualify RepoTags with their registry (docker.io/, localhost/, quay.io/, ...), so the match is on the reference path, not a string prefix — a locally built image keeps its tag even though its hash is what identifies it.

func DerivedTag 

func DerivedTag(baseID string, packages []string, repos map[string]Repo) string

DerivedTag returns the content-addressed tag tpd lays on a derived image built from baseID with the given packages and apt repos. The tag is the first 16 hex chars of a sha256 over baseID, the sorted package list, and (when non-empty) the sorted canonical repo descriptors: 

no repos:   sha256(baseID \x00 sorted(packages).join(\x01))
with repos: sha256(baseID \x00 sorted(packages).join(\x01) \x00 sorted(canonical-repos).join(\x02))

The repos segment is appended only when non-empty, so a packages-only profile keeps the byte-identical pre-repos hash and its cached derived image survives the upgrade. Pure; does not touch the Docker daemon. Package and repo order is canonicalised before hashing so catalog authors can't trigger rebuilds by reordering.

Returns "" when both packages and repos are empty — the prepare path short-circuits and no derived image is built.

func EnsureVolume 

func EnsureVolume(ctx context.Context, cli *client.Client, name string) error

EnsureVolume creates name if it does not already exist, tagging it with the ownership label so prune only ever removes volumes tpd created.

func NewDaemonHTTPClient added in v0.0.8 

func NewDaemonHTTPClient(host string) (*http.Client, string, error)

NewDaemonHTTPClient returns an HTTP client and the base URL of the Docker API for the daemon host string. Unix sockets (including a bare "unix://", which means defaultDaemonHost) get a Unix transport; "tcp://" is rewritten to "http://"; "http://"/"https://" pass through unchanged. "ssh://" and "npipe://" are rejected with a clear error: ssh needs the CLI's connection proxy and npipe is Windows-only. Every request is bounded by daemonHTTPTimeout.

func OwnershipLabels 

func OwnershipLabels() map[string]string

func QueryRootless 

func QueryRootless(ctx context.Context, cli *client.Client) (bool, error)

QueryRootless makes a raw GET to /info and parses the "rootless" field from the JSON response. Podman's Docker-compatible API includes this field; Docker's does not (it's absent, so json.Unmarshal leaves it as false). Exported so the doctor package can reuse it (Plan 3) without duplication.

func ResolveImageID 

func ResolveImageID(ctx context.Context, cli *client.Client, ref string) (string, error)

ResolveImageID returns the content-addressed image-config SHA of the locally-present image referenced by ref. Used as the hash input for DerivedTag and for invalidating derived images when the local base image changes. Callers handle a missing-local-image error by skipping the profile's contribution to the "used" derived-tag set (no local base ⇒ no possible derived image).

func SELinuxEnforcing 

func SELinuxEnforcing() bool

SELinuxEnforcing reports whether SELinux is enforcing on this host. Exported for tpd doctor, which mirrors the launch-time detection.

func ServiceHostEnvName added in v0.0.8 

func ServiceHostEnvName(serviceName string) string

ServiceHostEnvName is the consumer-side variable exposing a service's network alias to the main container.

func ServiceNetworkAlias added in v0.0.8 

func ServiceNetworkAlias(serviceName string) string

ServiceNetworkAlias is the DNS alias a service answers on the shared network. Names are DNS-safe by profile grammar, so aliases cannot collide.

Types

type CacheSpec 

type CacheSpec struct {
	// Name is the shared volume for the whole cache entry. On engines that
	// honor volume subpaths each target mounts Name with VolumeOptions.Subpath
	// set to Subpath; otherwise a dedicated volume Name-<Subpath> backs each
	// target.
	Name   string
	Target string
	// Subpath is the stable per-target key (sha256 of the target path,
	// truncated). It keeps the subdirectory/fallback-volume stable and
	// order-independent as profiles add or remove paths.
	Subpath string
}

type CreateResult added in v0.0.7 

type CreateResult struct {
	ContainerID string
}

type DeviceSpec 

type DeviceSpec struct {
	Container string
	Host      string
	Perms     string
	Cgroup    bool
}

type DockerRuntime 

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

func NewDockerRuntime 

func NewDockerRuntime() (*DockerRuntime, error)

func (*DockerRuntime) ConnectContainerToNetwork added in v0.0.8 

func (d *DockerRuntime) ConnectContainerToNetwork(ctx context.Context, containerID, networkName string, aliases []string) error

ConnectContainerToNetwork attaches a container to the managed network under DNS aliases, so services are reachable by name instead of a resolved IP.

func (*DockerRuntime) CreateContainer added in v0.0.7 

func (d *DockerRuntime) CreateContainer(ctx context.Context, spec Spec) (CreateResult, error)

func (*DockerRuntime) DetectMode 

func (d *DockerRuntime) DetectMode(ctx context.Context) (workspace.Mode, error)

DetectMode queries the engine's /info endpoint and checks for the Podman "rootless" field. The Docker SDK's types.Info does not map this field, so we make a raw HTTP request and parse the JSON ourselves. Spec §5.4.

func (*DockerRuntime) Prepare 

func (d *DockerRuntime) Prepare(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (string, error)

func (*DockerRuntime) RemoveContainer added in v0.0.8 

func (d *DockerRuntime) RemoveContainer(ctx context.Context, containerID string) error

RemoveContainer explicitly removes a container that failed before the run phase, where RunContainer's deferred cleanup does not apply.

func (*DockerRuntime) RunContainer added in v0.0.7 

func (d *DockerRuntime) RunContainer(ctx context.Context, spec Spec, created CreateResult) (int, error)

RunContainer attaches, starts, waits on, and removes a container created by CreateContainer. The deferred removal is the primary cleanup: it covers the whole attach/start/wait lifecycle and normal exit.

func (*DockerRuntime) StartServices added in v0.0.7 

func (d *DockerRuntime) StartServices(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (ServiceBindings, error)

StartServices finds-or-starts every service in spec.Services, holding the per-service lockfiles (acquired in sorted name order to prevent deadlock) until the caller invokes the returned Release. Locks are only released on error or via Release; Run's container-create must stay under the lock so a concurrent stop step can't see "zero consumers" mid-launch.

func (*DockerRuntime) StopServices added in v0.0.7 

func (d *DockerRuntime) StopServices(ctx context.Context, spec Spec) error

StopServices stops and removes each service container once no container consumes it. Safe to run concurrently with another launch's StartServices: the per-service lock serializes the stop decision, and All: true consumer lookup counts a created-but-not-started main container as a live consumer.

type FakeRuntime 

type FakeRuntime struct {
	PreparedSpec            *Spec
	PreparePull             bool
	PrepareErr              error
	PrepareImage            string
	CreatedSpec             *Spec
	CreateResult            CreateResult
	CreateErr               error
	RanSpec                 *Spec
	RunErr                  error
	ExitCode                int
	StartServicesSpec       *Spec
	StartServicesPull       bool
	StartServicesErr        error
	ServiceBindings         ServiceBindings
	StopServicesSpec        *Spec
	StopServicesErr         error
	ConnectedContainerID    string
	ConnectedNetworkName    string
	ConnectedNetworkAliases []string
	ConnectErr              error
	RemovedContainerID      string
	RemoveErr               error
}

FakeRuntime is a test helper that records runtime calls. Exported so pkg/tpd tests can import it without redefining.

func (*FakeRuntime) ConnectContainerToNetwork added in v0.0.8 

func (f *FakeRuntime) ConnectContainerToNetwork(ctx context.Context, containerID, networkName string, aliases []string) error

func (*FakeRuntime) CreateContainer added in v0.0.7 

func (f *FakeRuntime) CreateContainer(ctx context.Context, spec Spec) (CreateResult, error)

func (*FakeRuntime) Prepare 

func (f *FakeRuntime) Prepare(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (string, error)

func (*FakeRuntime) RemoveContainer added in v0.0.8 

func (f *FakeRuntime) RemoveContainer(ctx context.Context, containerID string) error

func (*FakeRuntime) RunContainer added in v0.0.7 

func (f *FakeRuntime) RunContainer(ctx context.Context, spec Spec, created CreateResult) (int, error)

func (*FakeRuntime) StartServices added in v0.0.7 

func (f *FakeRuntime) StartServices(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (ServiceBindings, error)

func (*FakeRuntime) StopServices added in v0.0.7 

func (f *FakeRuntime) StopServices(ctx context.Context, spec Spec) error

type FileSpec 

type FileSpec struct {
	Target  string
	Content string
	Mode    uint32
}

type ForeignServiceContainerError added in v0.0.8 

type ForeignServiceContainerError struct {
	ServiceName   string
	ContainerName string
}

ForeignServiceContainerError reports that a container not created by tpd occupies a service's deterministic name. tpd never stops, removes, or creates over such a container: the owner must rename or remove it.

func (*ForeignServiceContainerError) Error added in v0.0.8 

func (e *ForeignServiceContainerError) Error() string

type MountSpec 

type MountSpec struct {
	Target   string
	Source   string
	ReadOnly bool
	Optional bool
	Create   bool
	Service  string
	Socket   string
}

type NoopProgressWriter 

type NoopProgressWriter struct{}

func (NoopProgressWriter) WriteProgress 

func (NoopProgressWriter) WriteProgress(string)

type PortSpec 

type PortSpec struct {
	HostIP    string
	HostPort  string
	Container string
	Protocol  string
}

type ProgressWriter 

type ProgressWriter interface {
	WriteProgress(line string)
}

type Repo 

type Repo struct {
	ExtRepo    string
	URL        string
	KeyURL     string
	Suites     string
	Components string
}

Repo mirrors profile.Repo: a single extra apt source, either an extrepo catalog name (ExtRepo) or a fully inline custom repo (URL/KeyURL/...). Fields are duplicated (not the profile type) so the runtime package stays independent of the profile package.

type ResourceSpec 

type ResourceSpec struct {
	MemoryBytes int64
	NanoCPUs    int64
}

type Runtime 

type Runtime interface {
	Prepare(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (string, error)
	CreateContainer(ctx context.Context, spec Spec) (CreateResult, error)
	RunContainer(ctx context.Context, spec Spec, created CreateResult) (int, error)
	StartServices(ctx context.Context, spec Spec, w ProgressWriter, pull bool) (ServiceBindings, error)
	StopServices(ctx context.Context, spec Spec) error
	ConnectContainerToNetwork(ctx context.Context, containerID, networkName string, aliases []string) error
	RemoveContainer(ctx context.Context, containerID string) error
}

type ServiceBindings added in v0.0.7 

type ServiceBindings struct {
	Sockets map[string]string
	Network string
	Release func()
}

ServiceBindings carries the container-side socket paths for each running service (Sockets maps service name to container path), the shared network the services were attached to, and Release tears the services down when the launch finishes.

type ServiceSpec added in v0.0.7 

type ServiceSpec struct {
	Name       string
	Hash       string
	Image      string
	Packages   []string
	Repos      map[string]Repo
	Files      []FileSpec
	Command    []string
	Caches     []CacheSpec
	Mounts     []MountSpec
	Env        map[string]string
	Labels     map[string]string
	Exposes    map[string]string
	Privileged bool
}

ServiceSpec is a service container launched alongside the main container: it shares the profile's packages/repos/files/caches and publishes its service sockets back into the main container.

type Spec 

type Spec struct {
	ProfileName string
	Image       string
	Packages    []string
	Repos       map[string]Repo
	Files       []FileSpec
	Command     []string
	Mounts      []MountSpec
	PortSpecs   []PortSpec
	DeviceSpecs []DeviceSpec
	Env         map[string]string
	Tools       map[string]mise.Tool
	Caches      []CacheSpec
	Network     string
	Labels      map[string]string
	Services    []ServiceSpec
	SocketPaths []string
	Workspace   WorkspaceSpec
	TTY         string
	RuntimeHome string
	Resources   ResourceSpec
}

type WorkspaceSpec 

type WorkspaceSpec struct {
	HostPath string
	Target   string
	Mode     workspace.Mode
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.