deployment

package
v0.37.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package deployment enters the runtime described by a deployed release. Applications opt in only when neither --config nor --env-file was supplied.

Index

Constants

View Source
const BindingsEnvironment = "FOUNDRY_DEPLOY_RUNTIME_FILE"

BindingsEnvironment selects the root-owned descriptor for this role invocation.

View Source
const RehearsalRunEnvironment = "FOUNDRY_REHEARSAL_RUN_ID"
View Source
const RuntimeDescriptor = "config/deploy-runtime.json"

RuntimeDescriptor is the release-relative deployment descriptor path.

Variables

This section is empty.

Functions

func LoadRehearsal added in v0.37.0

func LoadRehearsal() (storage.Rehearsal, bool, error)

LoadRehearsal reads only the optional rehearsal grant from the selected runtime descriptor. The boolean reports block presence. Without a nonempty process rehearsal identity it performs no file access. Active rehearsal validates schema-1 or schema-2 descriptors; only a protected schema-2 block can grant reduced fidelity. A missing descriptor or block grants nothing.

Types

type BindingName added in v0.31.0

type BindingName string

BindingName identifies a binding declared by the consuming role.

type Bindings added in v0.31.0

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

Bindings is an immutable startup snapshot. Pass concrete values to business handlers. Its zero value has no bindings; a missing name returns fault.Missing.

func LoadBindings added in v0.31.0

func LoadBindings() (Bindings, bool, error)

LoadBindings reads the descriptor selected by the deployment unit. Absence is reported separately from malformed configuration; an explicit bad path never falls back.

func ReadBindings added in v0.31.0

func ReadBindings(path string) (Bindings, error)

ReadBindings loads a bounded, nonsecret descriptor. Host-side executable and artifact verification remains the deployment owner's responsibility.

func (Bindings) Bundle added in v0.31.0

func (b Bindings) Bundle(name BindingName) (BundleDirectory, error)

Bundle returns the named service-local bundle directory. A missing name returns an error classified as fault.Missing.

func (Bindings) Copies added in v0.37.0

func (b Bindings) Copies(name BindingName) ([]Copy, error)

Copies returns the placed providers in ordinal order as an owned slice. A declared binding may be empty. An unknown or ungranted name returns fault.Missing. Mutating the returned slice or its values cannot change this startup snapshot.

func (Bindings) DeploymentSHA256 added in v0.31.0

func (b Bindings) DeploymentSHA256() SHA256

DeploymentSHA256 returns the digest of the selected deployment.

func (Bindings) Endpoint added in v0.31.0

func (b Bindings) Endpoint(name BindingName) (Endpoint, error)

Endpoint returns the named private endpoint. A missing name returns an error classified as fault.Missing.

func (Bindings) Executable added in v0.31.0

func (b Bindings) Executable(name BindingName) (Executable, error)

Executable returns the named executable. A missing name returns an error classified as fault.Missing.

func (Bindings) PublicListener added in v0.33.0

func (b Bindings) PublicListener(name BindingName) (PublicListener, error)

PublicListener returns the named public listener with an owned address snapshot. A missing name returns an error classified as fault.Missing.

func (Bindings) Rehearsal added in v0.37.0

func (b Bindings) Rehearsal() storage.Rehearsal

Rehearsal returns the sealed storage grant captured when this descriptor was read. Absent blocks and mismatched process identities grant nothing.

func (Bindings) SharedDirectory added in v0.35.0

func (b Bindings) SharedDirectory(name BindingName) (SharedDirectory, error)

SharedDirectory returns a topology directory explicitly granted to this role. A missing or ungranted name returns an error classified as fault.Missing.

func (Bindings) Unit added in v0.31.0

func (b Bindings) Unit() Unit

Unit returns the identity of the role invocation that owns these bindings.

type BundleDirectory added in v0.31.0

type BundleDirectory struct {
	// Path is the absolute path of the protected directory view.
	Path string
	// SHA256 identifies the artifact that supplies this bundle.
	SHA256 SHA256
}

BundleDirectory is the protected service-local view, not the artifact's host path.

type Copy added in v0.37.0

type Copy struct {
	// Ordinal is the provider's stable copy number, starting at one.
	Ordinal int
	// Endpoint addresses this copy's declared private listener.
	Endpoint Endpoint
	// SecretFile is empty when no secret file path is included in this descriptor.
	SecretFile string
}

Copy is one placed provider and its optional secret file path. It contains file paths, never secret values.

type DirectoryAccess added in v0.35.0

type DirectoryAccess string

DirectoryAccess is the filesystem access granted to this role by its sandbox.

const (
	// DirectoryReadOnly permits reading prepared files, but no filesystem writes.
	DirectoryReadOnly DirectoryAccess = "read-only"
	// DirectoryReadWrite permits creating, modifying and deleting cached files.
	DirectoryReadWrite DirectoryAccess = "read-write"
)

type Endpoint added in v0.31.0

type Endpoint struct {
	// Role identifies the producer of this endpoint.
	Role RoleName
	// Listener identifies the producer's listener.
	Listener ListenerName
	// Scheme selects HTTP, TCP or Unix addressing.
	Scheme EndpointScheme
	// Address is the allocated loopback address.
	Address netip.Addr
	// Port is the allocated private port, not the public edge port.
	Port uint16
	// Path is the full Unix socket path; it is empty for TCP and HTTP endpoints.
	Path string
	// Directory is the shared instance socket directory for Unix endpoints.
	Directory string
	// Name is the Unix socket file name within Directory.
	Name string
}

Endpoint is an allocated private endpoint. It is immutable for this invocation.

func (Endpoint) Network added in v0.34.0

func (e Endpoint) Network() string

Network returns the network accepted by net.Dialer: "unix" or "tcp".

func (Endpoint) URL added in v0.31.0

func (e Endpoint) URL() url.URL

URL returns the endpoint URL, including the socket path for Unix endpoints.

type EndpointScheme added in v0.31.0

type EndpointScheme string

EndpointScheme identifies the protocol used to address a private endpoint.

const (
	// HTTP addresses a private HTTP listener.
	HTTP EndpointScheme = "http"
	// TCP addresses a private TCP listener.
	TCP EndpointScheme = "tcp"
	// Unix addresses a private Unix-domain stream socket.
	Unix EndpointScheme = "unix"
)

type Executable added in v0.31.0

type Executable struct {
	// Path is the absolute path of the host-verified executable.
	Path string
	// SHA256 identifies the executable source recorded by the host.
	SHA256 SHA256
}

Executable is a host-verified absolute file, never a PATH search or shell command.

type InstanceID added in v0.31.0

type InstanceID string

InstanceID is the UUID of the deployed environment instance.

type ListenerName added in v0.31.0

type ListenerName string

ListenerName identifies a listener within its producing role.

type ListenerTransport added in v0.33.0

type ListenerTransport string

ListenerTransport identifies a declared listener's network transport.

const TCPTransport ListenerTransport = "tcp"

TCPTransport carries a public listener over TCP.

type PublicListener added in v0.33.0

type PublicListener struct {
	// Role identifies the role that owns the listener.
	Role RoleName
	// Listener identifies the declared listener within its role.
	Listener ListenerName
	// Hostname is the public DNS hostname selected by the profile.
	Hostname string
	// Port is the first copy's public port, retained for singleton consumers.
	Port uint16
	// Ports contains every placed copy's public port, ordered by ordinal.
	Ports []PublicPort
	// TLS is the TLS mode declared by the topology.
	TLS TLSMode
	// Transport is the network transport declared by the topology.
	Transport ListenerTransport
	// PublicAddresses contains the profile's explicit public addresses, not a DNS lookup.
	PublicAddresses []netip.Addr
}

PublicListener is the declared public face of a placed listener. It is immutable for this invocation; it does not attest to current readiness.

type PublicPort added in v0.37.0

type PublicPort struct {
	// Ordinal is the provider's copy number, starting at one.
	Ordinal int
	// Port is the public port selected by the profile.
	Port uint16
}

PublicPort maps a provider copy to its explicit public edge port.

type RoleName added in v0.31.0

type RoleName string

RoleName identifies a builtin or executable role in the topology.

type Runtime

type Runtime struct {
	// Release is the absolute path of the selected release.
	Release string
	// Instance is the deployed instance name.
	Instance string
	// User is the instance account used to run the application.
	User string
	// ConfigFile is the selected release's application configuration file.
	ConfigFile string
	// EnvFile is the selected runtime environment file.
	EnvFile string
	// WorkDir is the application working directory.
	WorkDir string
	// PublicDir is the selected release's public asset directory.
	PublicDir string
}

Runtime contains the release profile and the instance's runtime paths. Use Detect to obtain it before calling Enter.

func Detect

func Detect() (Runtime, bool, error)

Detect reads the role descriptor selected by BindingsEnvironment, or the descriptor beside the resolved executable when that variable is absent. An absent legacy descriptor returns ok=false; an invalid or unreadable descriptor returns an error without falling back.

func (Runtime) Enter

func (r Runtime) Enter(args []string) error

Enter replaces a root Linux process with runuser and forwards args unchanged (pass os.Args[1:]). Other users enter WorkDir and default WEB__PUBLIC_DIR to PublicDir only when unset. After Enter, load ConfigFile and EnvFile explicitly. A successful root exec never returns. Root on other platforms is unsupported.

type SHA256 added in v0.31.0

type SHA256 string

SHA256 is a lowercase hexadecimal SHA-256 digest.

type SharedDirectory added in v0.35.0

type SharedDirectory struct {
	// Path is the absolute directory path within the role's filesystem view.
	Path string
	// Access is enforced by the systemd sandbox, not by the shared account's mode bits.
	Access DirectoryAccess
	// MaxBytes limits allocated file data. It does not reserve memory or bound sparse file lengths.
	MaxBytes int64
}

SharedDirectory is a disposable, size-bounded tmpfs shared by declared roles. Contents are never backed up or restored and must be safe to recreate.

type TLSMode added in v0.33.0

type TLSMode string

TLSMode identifies where a public listener terminates TLS.

const (
	// TLSEdge terminates TLS at the deployment's public edge.
	TLSEdge TLSMode = "edge"
	// TLSNone exposes the listener without TLS termination.
	TLSNone TLSMode = "none"
)

type Unit added in v0.31.0

type Unit struct {
	// Instance identifies the deployed environment instance.
	Instance InstanceID
	// Role identifies the placed service role.
	Role RoleName
	// Ordinal is the service copy number, from 1 through 128.
	Ordinal uint16
}

Unit identifies a single placed service copy.

Jump to

Keyboard shortcuts

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