Documentation
¶
Overview ¶
Package sim is the cloud-neutral framework the simulators build on. Each simulator is an HTTP server serving a slice of one cloud's API; the framework supplies the server, routing, persistent state, authentication, workload placement and the hooks a cloud's protocol and error shape plug into.
Index ¶
- Constants
- Variables
- func ASCIIFold(s string) string
- func ASCIIFoldUpper(s string) string
- func ArchiveVolume(ctx context.Context, volume string) (io.ReadCloser, error)
- func AuthPassthroughMiddleware(provider string) func(http.Handler) http.Handler
- func BasicChallenge(realm, service string) string
- func BasicCredential(encoded string) (username, password string, ok bool)
- func BearerChallenge(realm, service, scope, errCode string) string
- func BrowserFederationCoordinates(bool) map[string]string
- func CaptureVolume(ctx context.Context, src, dst, tag string) error
- func CaseInsensitiveIndex(s, sub string) int
- func CaseInsensitiveLastIndex(s, sub string) int
- func CleanupContainers()
- func CloseDB(db *sql.DB) error
- func CommitContainer(ctx context.Context, containerID, reference string) (string, error)
- func ConnectContainerToNetwork(containerName, networkName string, aliases []string) error
- func ConnectContainerToNetworkAt(containerName, networkName string, aliases []string, ipv4 netip.Addr) error
- func ConnectContainerToNetworkBehindGateway(containerName, networkName string, ipv4 netip.Addr) error
- func ConsoleBundle(dir string) (fs.FS, error)
- func ContainerEnvironment(ctx context.Context, containerID string) (map[string]string, error)
- func ContainerIPv4On(ctx context.Context, containerID, network string) netip.Addr
- func ContainerNetworkAddresses(ctx context.Context, containerID string) (map[string]netip.Addr, error)
- func DeclareOpenEndedWait(ctx context.Context)
- func DeclareWait(ctx context.Context, d time.Duration)
- func DeclaredWait(ctx context.Context) (wait time.Duration, openEnded bool)
- func DefaultContainerNetworkGatewayIPv4() (string, error)
- func DetachCommand(command *exec.Cmd)
- func DisconnectContainerFromNetwork(ctx context.Context, containerID, networkName string) error
- func DockerClient() *client.Client
- func DockerConfigEnv(configDir string) []string
- func EngineGoArch(engineArch string) (string, error)
- func EnsureCloudNetwork(ctx context.Context, spec CloudNetwork) (string, error)
- func EnsureDockerNetwork(name string) (string, error)
- func EnsureEngineBuild(ctx context.Context, cli *client.Client, b EngineBuild) (string, string, error)
- func EnsurePlatformNetwork(ctx context.Context, name string, labels map[string]string) (string, netip.Prefix, error)
- func EnsureWritableDir(dir string) error
- func EnvOr(key, fallback string) string
- func ExitWithParent()
- func HasPersistentWorkloadIdentity() bool
- func HoldThawed(ctx context.Context, containerID string) (release func(), err error)
- func HostDockerConfigDir() string
- func ImageOnPort(image string, port int) bool
- func InFlightMiddleware(next http.Handler) http.Handler
- func InFlightSnapshot() []inFlightRequest
- func InProcess(r *http.Request) bool
- func InitDocker(provider string, preserveWorkloads bool, stateDir string) (*client.Client, error)
- func InspectHeldImage(ctx context.Context, cli *client.Client, name string) (client.ImageInspectResult, error)
- func LeasePlatformAddress(ctx context.Context, network, owner string, requested netip.Addr) (netip.Addr, func(), error)
- func LegacyRows[T any](db *sql.DB, table string) (*SQLiteStore[T], []Keyed[T], error)
- func LifetimeContext(ctx context.Context) context.Context
- func LoggingMiddleware(logger zerolog.Logger, provider string) func(http.Handler) http.Handler
- func Main(p Program)
- func Migrate(db *sql.DB, name string, fn func() error) error
- func MissingNetfilterTableHint(err error) string
- func NewSidecarToken() string
- func NewUUID() string
- func OCIError(w http.ResponseWriter, code, message string, status int)
- func OpenDB(dataDir string) (*sql.DB, error)
- func OwnershipLabels(extra map[string]string) map[string]string
- func ParseAuthorization(header string) (scheme, credential string)
- func PathParam(r *http.Request, name string) string
- func PathPrefixes(id string) []string
- func ProcessAlive(pid int) bool
- func PublishedHostPort(ctx context.Context, containerID string, containerPort int) (int, error)
- func PullImage(ctx context.Context, imageName, platform string) error
- func PullImageOn(ctx context.Context, cli *client.Client, imageName, platform string) error
- func PullImageWithCredential(ctx context.Context, imageName, platform, registryAuth string) error
- func RandomHex(n int) string
- func ReadEngineImageFile(ctx context.Context, cli *client.Client, image, path string) ([]byte, error)
- func ReadJSON(r *http.Request, v any) error
- func RegisterSidecarToken(token, network string)
- func RegistryCredential(username, password string) string
- func RegistryError(w http.ResponseWriter, status int, code, message string, detail any)
- func RegistryIdentityToken(token string) string
- func RemoveContainer(containerID string) error
- func RemoveDockerNetwork(name string) error
- func RemoveDockerNetworkContext(ctx context.Context, name string) error
- func RemoveExistingContainer(containerID string) error
- func RemoveVolume(name string) error
- func RemoveVolumeSettled(name, tag string)
- func RemoveVolumesNamed(prefix string) error
- func RequestID(ctx context.Context) string
- func RequestIDMiddleware(provider string) func(http.Handler) http.Handler
- func RequireContainerRuntime(operation string) error
- func ReservePlatformAddress(ctx context.Context, network string, addr netip.Addr, owner string) (func(), error)
- func ResetTrackedStores()
- func ResolveLocalImage(image string) string
- func RunContainerReaper() bool
- func RuntimeInfo() string
- func ScopedDataDir(overrideEnv, subdir, tempName string) string
- func SidecarNetwork(ctx context.Context) string
- func SidecarTrust(next http.Handler) http.Handler
- func SnapshotVolume(ctx context.Context, src, dst string) (filesystem string, err error)
- func StartDiagnosticsListener()
- func StartExistingContainer(containerID string) error
- func StopAndRemoveContainer(containerID string, grace time.Duration)
- func StopContainer(containerID string, grace time.Duration)
- func UnregisterSidecarToken(token string)
- func VolumeExists(name string) bool
- func VolumeSnapshotIsInstant(filesystem string) bool
- func WaitContainerRemoved(containerID string, timeout time.Duration) error
- func WithCaller(ctx context.Context, caller Caller) context.Context
- func WorkloadScope() string
- func WriteDockerConfig(spec DockerConfigSpec) (string, error)
- func WriteJSON(w http.ResponseWriter, statusCode int, v any)
- type CachedSQLiteStore
- func (s *CachedSQLiteStore[T]) Delete(id string) bool
- func (s *CachedSQLiteStore[T]) Filter(fn func(T) bool) []T
- func (s *CachedSQLiteStore[T]) Generation() uint64
- func (s *CachedSQLiteStore[T]) Get(id string) (T, bool)
- func (s *CachedSQLiteStore[T]) Len() int
- func (s *CachedSQLiteStore[T]) List() []T
- func (s *CachedSQLiteStore[T]) ListPrefix(prefix string) []Keyed[T]
- func (s *CachedSQLiteStore[T]) Prune(expired func(T) bool) int
- func (s *CachedSQLiteStore[T]) Put(id string, item T)
- func (s *CachedSQLiteStore[T]) Update(id string, fn func(*T)) bool
- func (s *CachedSQLiteStore[T]) Upsert(id string, fn func(*T))
- type CallResponse
- type Caller
- type CloudNetwork
- type Config
- type ConsoleOptions
- type ContainerConfig
- type ContainerHandle
- func (h *ContainerHandle) Cancel()
- func (h *ContainerHandle) Exited() <-chan struct{}
- func (h *ContainerHandle) MemoryPeakBytes() uint64
- func (h *ContainerHandle) PublishedPort(ctx context.Context, containerPort int) (int, error)
- func (h *ContainerHandle) StartedAt() time.Time
- func (h *ContainerHandle) Wait() ProcessResult
- type DockerConfigSpec
- type DockerCredential
- type EngineBuild
- type ExistingContainer
- type FrameReader
- type FuncSink
- type GenerationIndex
- type HostEntry
- type Keyed
- type KeyedLocks
- type LogLine
- type LogSink
- type MemoryStore
- func (s *MemoryStore[T]) Delete(id string) bool
- func (s *MemoryStore[T]) Filter(fn func(T) bool) []T
- func (s *MemoryStore[T]) Generation() uint64
- func (s *MemoryStore[T]) Get(id string) (T, bool)
- func (s *MemoryStore[T]) Len() int
- func (s *MemoryStore[T]) List() []T
- func (s *MemoryStore[T]) ListPrefix(prefix string) []Keyed[T]
- func (s *MemoryStore[T]) Prune(expired func(T) bool) int
- func (s *MemoryStore[T]) Put(id string, item T)
- func (s *MemoryStore[T]) Update(id string, fn func(*T)) bool
- func (s *MemoryStore[T]) Upsert(id string, fn func(*T))
- type NetworkAttachment
- type NoopSink
- type OCIBlob
- type OCIManifest
- type OCIPull
- type OCIPulledBlob
- type OCIPulledManifest
- type OCIRegistry
- func (reg *OCIRegistry) DeleteManifest(scope, repo, ref string) bool
- func (reg *OCIRegistry) DeleteTagOnly(scope, repo, tag string) bool
- func (reg *OCIRegistry) ExportImage(scope, repo, reference string, maxManifests int) (OCIPull, error)
- func (reg *OCIRegistry) GetBlob(scope, repo, digest string) ([]byte, bool)
- func (reg *OCIRegistry) GetManifest(scope, repo, ref string) (OCIManifest, bool)
- func (reg *OCIRegistry) ImportImage(scope, repo string, pull OCIPull, tags []string)
- func (reg *OCIRegistry) PutBlob(scope, repo, digest, contentType string, data []byte)
- func (reg *OCIRegistry) PutManifest(scope, repo, ref, contentType string, data []byte)
- func (reg *OCIRegistry) Register(srv *Server)
- type OCIUpload
- type OTelLogWriter
- type Observability
- type ParseGuard
- type PrefixStore
- type ProcessResult
- type Program
- type RegistryScope
- type Route
- type RuntimeMode
- type SQLiteStore
- func (s *SQLiteStore[T]) Delete(id string) bool
- func (s *SQLiteStore[T]) Filter(fn func(T) bool) []T
- func (s *SQLiteStore[T]) Generation() uint64
- func (s *SQLiteStore[T]) Get(id string) (T, bool)
- func (s *SQLiteStore[T]) Len() int
- func (s *SQLiteStore[T]) List() []T
- func (s *SQLiteStore[T]) ListPrefix(prefix string) []Keyed[T]
- func (s *SQLiteStore[T]) Prune(expired func(T) bool) int
- func (s *SQLiteStore[T]) Put(id string, item T)
- func (s *SQLiteStore[T]) Update(id string, fn func(*T)) bool
- func (s *SQLiteStore[T]) Upsert(id string, fn func(*T))
- type SandboxProfile
- type Scanner
- type SeedFile
- type Server
- func (s *Server) Call(r *http.Request) *CallResponse
- func (s *Server) CallbackListenAddr() string
- func (s *Server) DB() *sql.DB
- func (s *Server) Handle(pattern string, handler http.Handler)
- func (s *Server) HandleFunc(pattern string, handler http.HandlerFunc)
- func (s *Server) Listen() error
- func (s *Server) ListenAndServe() error
- func (s *Server) Logger() zerolog.Logger
- func (s *Server) Mux() *http.ServeMux
- func (s *Server) OnStop(stop func(context.Context) error)
- func (s *Server) Payloads(name string) (*blobstore.Payloads, error)
- func (s *Server) RegisterUI(fsys fs.FS, console ConsoleOptions)
- func (s *Server) RequestContext(parent context.Context) context.Context
- func (s *Server) RoutePatterns() []string
- func (s *Server) Serve() error
- func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Server) ServeUIRoot(w http.ResponseWriter, r *http.Request) bool
- func (s *Server) SetSpecValidator(v SpecValidator)
- func (s *Server) StartBackground(name string, worker func(context.Context))
- func (s *Server) StopBackground()
- func (s *Server) UIAuth() *uiauth.Auth
- func (s *Server) WrapHandler(middleware func(http.Handler) http.Handler)
- type SpecValidator
- type SpecViolation
- type StateStore
- type Store
- type TrackedStore
- type Wildcard
Constants ¶
const ( DefaultMaxParseDepth = 512 DefaultMaxParseNodes = 100000 )
DefaultMaxParseDepth / DefaultMaxParseNodes are sane caps for the sims' expression parsers — far above any real query, far below stack/OOM limits.
const DockerIdentityTokenUsername = "<token>"
DockerIdentityTokenUsername is the username under which the Docker client treats a stored secret as an identity token.
const EngineBuildTrustFile = "engine-build-ca.pem"
EngineBuildTrustFile is the build-context file holding the roots the simulator's host trusts beyond the system's own, from SSL_CERT_FILE, and empty when the host names none. A build that fetches over TLS appends it to its stage's CA store, so a build behind a TLS-inspecting proxy trusts what the simulator trusts:
COPY engine-build-ca.pem /tmp/ RUN cat /tmp/engine-build-ca.pem >> /etc/ssl/certs/ca-certificates.crt
const NoGateway = "none"
NoGateway is the Gateway of a workload with no default route: one whose subnet's routing names no way out.
const ParentPIDVariable = "SOCKERLESS_PARENT_PID"
ParentPIDVariable names the process this simulator must not outlive.
A test harness stops the simulator it started from its own cleanup, which a `go test` killed outright — a timeout kill, a stopped run, an editor closing the process — never reaches; the simulator and the container reaper waiting on it then keep running, holding ports and memory. A signal handler cannot close that gap, since the ending that matters is the one signal a process cannot trap, so the child watches its parent, as the reaper watches the simulator.
const SlowRequestThreshold = 10 * time.Second
SlowRequestThreshold is the age at which the simulator reports an in-flight request as slow. It bounds and cancels nothing. A request whose handler declared a wait (DeclareWait) counts from the end of that wait.
Variables ¶
var ErrAddressRangeInUse = errors.New("address range held by another engine network")
EnsureCloudNetwork wraps ErrAddressRangeInUse when another live engine network already holds a range overlapping the requested one. The engine's IPAM admits one network per range, so two live cloud networks sharing a CIDR do not coexist on one engine.
var ErrNotRunning = errors.New("the workload is not running")
ErrNotRunning is wrapped by a read of a workload's published port when the workload has stopped, or is gone, and so publishes none.
var ErrOCITooManyManifests = errors.New("the image has more manifests than allowed")
ErrOCITooManyManifests is the pull of an image with more manifests than the caller allows.
var SidecarSource embed.FS
SidecarSource is what the network sidecar compiles from on the engine: its command, the packages of this module it imports, and the module's go.mod and go.sum, which pin everything else it needs. The embed lives here because a package embeds only files at or below its own directory.
Functions ¶
func ASCIIFold ¶
ASCIIFold lowercases ONLY ASCII A–Z and is byte-length preserving. Unlike strings.ToLower (Unicode-aware; invalid UTF-8 → 3-byte U+FFFD) it never changes the byte length, so an index computed against ASCIIFold(s) is valid in s. Keywords/operators in the sims are ASCII, so case-insensitive matching is unchanged.
func ASCIIFoldUpper ¶
ASCIIFoldUpper uppercases ONLY ASCII a–z and is byte-length preserving.
func ArchiveVolume ¶
ArchiveVolume streams a volume's contents as a tar archive, read through a container that mounts the volume and never starts. Closing the stream removes the container.
func AuthPassthroughMiddleware ¶
Extract the caller identity without validating credentials, and accept a request that carries no auth headers at all.
func BasicChallenge ¶
BasicChallenge renders the `WWW-Authenticate` value of a registry that takes HTTP Basic credentials directly.
func BasicCredential ¶
BasicCredential decodes the base64 `user:password` of an HTTP Basic credential.
func BearerChallenge ¶
BearerChallenge renders the `WWW-Authenticate` value of the Docker Registry v2 token flow. Empty service, scope and errCode are omitted, since registries differ on which they name.
func BrowserFederationCoordinates ¶
BrowserFederationCoordinates reports the coordinates of a console that federates from the browser: the cloud API endpoint it reads, the token service it exchanges the operator's assertion at, and the audience that exchange is addressed to. Empty means the console's own origin, where the simulator serves the real cloud APIs and its own token service.
func CaptureVolume ¶
CaptureVolume snapshots the src volume into dst and logs, under "[sim-<tag>]", whether the filesystem gave the copy-on-write path. With no container engine, or no src volume — an engine that never started — there is nothing to capture, and dst is not created.
func CaseInsensitiveIndex ¶
CaseInsensitiveIndex returns the byte index of the first ASCII-case-insensitive occurrence of sub in s, or -1. Because ASCIIFold preserves byte length, the returned index is valid for slicing the ORIGINAL s.
func CaseInsensitiveLastIndex ¶
CaseInsensitiveLastIndex returns the byte index of the LAST ASCII-case-insensitive occurrence of sub in s, or -1. Like CaseInsensitiveIndex, the index it returns is valid for slicing the ORIGINAL s.
func CleanupContainers ¶
func CleanupContainers()
CleanupContainers stops and removes all simulator-managed containers, then the run's networks and volumes. Shutdown calls it.
func CloseDB ¶
CloseDB checkpoints all committed WAL records into the database before closing it, so an orderly service shutdown leaves one self-contained database file for the next process rather than relying on that process to find and replay a WAL segment.
func CommitContainer ¶
CommitContainer captures a kept container's filesystem as an image under reference ("name:tag") and returns the image ID: a machine image taken from a stopped instance.
func ConnectContainerToNetwork ¶
ConnectContainerToNetwork connects a running container to a Docker network with the given DNS aliases. Idempotent: if the container is already on the network, the call updates aliases and returns nil.
func ConnectContainerToNetworkAt ¶
func ConnectContainerToNetworkAt(containerName, networkName string, aliases []string, ipv4 netip.Addr) error
ConnectContainerToNetworkAt connects a running container to an engine network at a fixed IPv4 address inside the network's range, with the given DNS aliases.
func ConnectContainerToNetworkBehindGateway ¶
func ConnectContainerToNetworkBehindGateway(containerName, networkName string, ipv4 netip.Addr) error
ConnectContainerToNetworkBehindGateway connects a container to a network at an address without that network ever providing the container's default gateway: the engine picks the gateway endpoint by priority and then by network name, and a container that bridges guests onto the networks it joins must keep its default route on the network it started on.
func ConsoleBundle ¶
ConsoleBundle opens the built console bundle in dir, whose index.html sits at its root.
func ContainerEnvironment ¶
func ContainerIPv4On ¶
ContainerIPv4On returns a container's address on the named engine network, or the zero value when it is not on it.
func ContainerNetworkAddresses ¶
func ContainerNetworkAddresses(ctx context.Context, containerID string) (map[string]netip.Addr, error)
ContainerNetworkAddresses is a container's IPv4 address on each engine network it is attached to, by network name.
func DeclareOpenEndedWait ¶
DeclareOpenEndedWait records that the request ctx belongs to blocks for as long as its caller keeps the connection -- a stream, or a wait the caller left without a timeout -- so the slow-request diagnostic never reports it.
func DeclareWait ¶
DeclareWait records that the request ctx belongs to may block for up to d by design -- a long poll, an operation wait, a synchronous run of the caller's own workload bounded by its configured timeout. The slow-request diagnostic then reports it only once it outlives d by SlowRequestThreshold. Several declarations keep the longest; a context outside InFlightMiddleware ignores it.
func DeclaredWait ¶
DeclaredWait reports the wait the handler serving ctx's request declared: its bound, or openEnded when it has none. A request that declared nothing, or a context outside InFlightMiddleware, reads zero.
func DefaultContainerNetworkGatewayIPv4 ¶
DefaultContainerNetworkGatewayIPv4 returns the host-side gateway of the container runtime's default bridge. A simulator process running directly on Linux listens in the host namespace, so workload containers reach its callback listeners through this address. Standard host aliases can point outside that Linux host (notably inside a Podman machine), whereas the runtime-reported bridge gateway is the actual packet coordinate.
func DetachCommand ¶
DetachCommand puts a helper in its own session so a test harness terminating the simulator's process group does not also kill its cleanup reaper.
func DisconnectContainerFromNetwork ¶
DisconnectContainerFromNetwork takes a container off an engine network it joined; a network the engine no longer has is nothing to leave.
func DockerClient ¶
DockerClient returns the shared Docker client InitDocker set.
func DockerConfigEnv ¶
DockerConfigEnv is the environment that points a docker invocation at the configuration WriteDockerConfig wrote.
func EngineGoArch ¶
EngineGoArch names an engine's architecture as Go and OCI platforms do.
func EnsureCloudNetwork ¶
func EnsureCloudNetwork(ctx context.Context, spec CloudNetwork) (string, error)
EnsureCloudNetwork creates the engine network realizing a cloud network resource, or returns the one its name already holds. A range an engine network of a dead simulator run still holds is reclaimed first; a range a live or foreign network holds fails with ErrAddressRangeInUse. Returns the engine network's ID.
func EnsureDockerNetwork ¶
EnsureDockerNetwork creates the user-defined engine network name unless it exists, and returns its ID. A user-defined network gives its containers the engine's embedded DNS.
func EnsureEngineBuild ¶
func EnsureEngineBuild(ctx context.Context, cli *client.Client, b EngineBuild) (string, string, error)
EnsureEngineBuild builds b on the engine cli reaches unless the engine holds it, and returns the image and its platform.
func EnsurePlatformNetwork ¶
func EnsurePlatformNetwork(ctx context.Context, name string, labels map[string]string) (string, netip.Prefix, error)
EnsurePlatformNetwork creates the engine network the workloads on no cloud network join, or returns the one its name already holds, and reports its IPv4 range. The network takes a /24 of the shared address space chosen by its name, moving to the next /24 while a live network holds the chosen one, so two simulators on one engine each get their own. The engine allocates container addresses from the upper half of the /24; the lower half is the simulator's to lease through LeasePlatformAddress, for the sidecars, the node agent and the guests the engine does not place. A platform network without that split is recreated once nothing is attached to it.
func EnsureWritableDir ¶
EnsureWritableDir creates dir and its parents and makes dir mode 0777, so a workload bind-mounting it writes to it under any uid. MkdirAll alone lands at 0755 under the usual umask; the chmod is not masked.
func ExitWithParent ¶
func ExitWithParent()
ExitWithParent ends this process once the process named by SOCKERLESS_PARENT_PID has exited. It returns immediately, and does nothing when the variable is unset or unusable: a simulator run by hand, by a service manager or by a container runtime has no parent it should die with, and inferring one from os.Getppid() would end a `nohup`ed run the moment its shell closed.
func HasPersistentWorkloadIdentity ¶
func HasPersistentWorkloadIdentity() bool
HasPersistentWorkloadIdentity reports whether workload ownership is scoped to a durable simulator state directory.
func HoldThawed ¶
HoldThawed waits until no volume capture holds the container frozen, then keeps new captures from freezing it until release runs. The Docker Engine refuses to exec into a paused container, so a command run into a database engine's container waits out a snapshot's brief I/O suspension under this hold.
func HostDockerConfigDir ¶
func HostDockerConfigDir() string
HostDockerConfigDir is the directory the host's docker CLI reads its configuration from.
func ImageOnPort ¶
ImageOnPort reports whether an image reference's registry host carries port, the one coordinate a relocated registry keeps.
func InFlightMiddleware ¶
InFlightMiddleware records every request while it runs, and reports the ones that outlive SlowRequestThreshold beyond the wait their handler declared. A request that finishes quickly costs a map insert and delete.
func InFlightSnapshot ¶
func InFlightSnapshot() []inFlightRequest
InFlightSnapshot lists the requests currently being served, oldest first.
func InitDocker ¶
InitDocker initializes the shared Docker client and verifies connectivity. Startup calls it for every runtime mode that executes workloads.
It returns an error rather than exiting, so startup decides to refuse to start and can say what it was configuring: a simulator that cannot reach an engine must not answer its health check while every workload it runs fails at first use.
func InspectHeldImage ¶
func InspectHeldImage(ctx context.Context, cli *client.Client, name string) (client.ImageInspectResult, error)
InspectHeldImage inspects the image the engine holds for name. `docker load` restores no repository digest, so the engine holds a digest-pinned image a base-image archive restored only under the tag that spells its digest, repo:sha256-<hex>, which is where the archive saves it.
func LeasePlatformAddress ¶
func LeasePlatformAddress(ctx context.Context, network, owner string, requested netip.Addr) (netip.Addr, func(), error)
LeasePlatformAddress leases an address of the platform network to owner, the one requested when it is valid, and returns it with the release that gives it back. The engine never allocates the address to a container, so a guest the engine does not place can take it.
func LegacyRows ¶
LegacyRows reads every row of a table in the shape an earlier build wrote it, for a migration to convert. It does not join the tracked store set: the migration either rewrites the table through its current store or empties it.
func LifetimeContext ¶
LifetimeContext returns the context of the server serving the request ctx belongs to, which only that server's shutdown cancels. Run work the request starts but its caller does not own under it: AWS Lambda keeps running an invocation whose caller hung up, yet a stopping simulator must not wait for one. It panics when ctx does not descend from a request the server serves or from RequestContext, because no other context answers that question.
func LoggingMiddleware ¶
func Main ¶
func Main(p Program)
Main runs a simulator binary: the container reaper when invoked as one, and otherwise configuration, observability, the build, the listeners beside the HTTP port and the HTTP server, until a signal shuts it down. A step that fails ends the process before it serves.
func Migrate ¶
Migrate runs fn the first time a persistent database opens under a build that declares the migration name, and records that it ran, so a store whose row shape a newer build changed converts once rather than reading wrong or rescanning on every start. Without a database there is nothing to migrate: in-memory state starts empty.
func MissingNetfilterTableHint ¶
MissingNetfilterTableHint names the kernel dependency behind a container runtime's refusal to wire a container onto a network, and returns "" for every other failure. Docker 28 and later programs a raw-table PREROUTING DROP rule when it attaches a container to a bridge network, so a kernel built without the corresponding netfilter table cannot start the workload at all; the runtime reports the table it could not initialise but not the module that supplies it, which leaves a minimal guest kernel (a Firecracker microVM, a container-optimised image) looking like a simulator defect.
func NewUUID ¶
func NewUUID() string
NewUUID returns a random RFC 9562 version 4 UUID in its canonical form.
func OCIError ¶
func OCIError(w http.ResponseWriter, code, message string, status int)
OCIError writes a Docker Registry HTTP API v2 error body.
func OpenDB ¶
OpenDB opens a SQLite database at the given path with WAL mode enabled. Creates the directory and file if they don't exist.
func OwnershipLabels ¶
OwnershipLabels are the labels that mark a workload as this simulator's, its persistent state among them, with extra merged in.
func ParseAuthorization ¶
ParseAuthorization splits an Authorization header into its scheme and credential. Compare the scheme case-insensitively (RFC 9110 §11.1).
func PathPrefixes ¶
PathPrefixes returns every prefix of a "/"-separated identifier that ends at a separator.
It is the keysOf for a store whose rows are addressed by a parent's identifier plus a child segment. A row indexed under all of its prefixes answers any `HasPrefix(id, parent+"/")` question exactly, at every depth, so one index serves a direct child collection and a cascading delete alike, without the index having to know which depth a caller will ask about.
func ProcessAlive ¶
ProcessAlive reports whether pid still identifies a running process.
func PublishedHostPort ¶
PublishedHostPort returns the host port the engine bound for a running container's containerPort/tcp. The engine allocates the port when it starts the container and releases it when the container stops, so a resumed container holds a new one: read it after every start. A container that joined another's network namespace listens on the ports the engine bound for that one.
func PullImage ¶
PullImage makes the simulator runtime's bounded, stream-aware pull path available to cloud-product translators that must inspect an image before they can construct its container configuration.
func PullImageOn ¶
PullImageOn pulls like PullImage through the engine cli rather than the simulator runtime's own.
func PullImageWithCredential ¶
PullImageWithCredential pulls like PullImage, presenting registryAuth (the engine API's X-Registry-Auth value) to the image's registry.
func ReadEngineImageFile ¶
func ReadEngineImageFile(ctx context.Context, cli *client.Client, image, path string) ([]byte, error)
ReadEngineImageFile returns the file at path in image, read from a container created from the image and never started.
func ReadJSON ¶
ReadJSON reads and decodes a JSON request body into the given value. The read is capped at maxQueryJSONBody so an unbounded body can't exhaust memory.
func RegisterSidecarToken ¶
func RegisterSidecarToken(token, network string)
RegisterSidecarToken trusts token as the sidecar of network.
func RegistryCredential ¶
RegistryCredential renders a username and password as the X-Registry-Auth value the engine API takes on an image pull: the engine's AuthConfig, JSON in URL-safe base64.
func RegistryError ¶
func RegistryError(w http.ResponseWriter, status int, code, message string, detail any)
RegistryError writes the Docker Registry HTTP API v2 error envelope with the `Docker-Distribution-Api-Version` header every registry response carries. A nil detail is omitted.
func RegistryIdentityToken ¶
RegistryIdentityToken is the credential the engine presents to a registry as an identity token: the engine exchanges it through the registry's OAuth 2.0 refresh-token grant for an access token, the way a Docker client holds the token `az acr login` stored.
func RemoveContainer ¶
RemoveContainer removes a container the simulator kept, running or not, with the anonymous volumes its image declared.
func RemoveDockerNetwork ¶
RemoveDockerNetwork removes a simulator-managed Docker network if it exists, and is idempotent for a missing one. The engine refuses to remove a network with endpoints still attached, so each refusal waits for a container to disconnect from it before trying again.
func RemoveDockerNetworkContext ¶
RemoveDockerNetworkContext is RemoveDockerNetwork waiting for the last container to disconnect for as long as ctx allows.
func RemoveExistingContainer ¶
RemoveExistingContainer stops and removes a workload whose owning control-plane process can no longer drive it.
func RemoveVolume ¶
RemoveVolume removes one explicitly named simulator-managed Docker volume. Callers own the lifecycle decision; this helper never enumerates or prunes unrelated volumes.
func RemoveVolumeSettled ¶
func RemoveVolumeSettled(name, tag string)
RemoveVolumeSettled removes a volume, waiting up to 30 seconds for the engine to remove the containers that still hold it: a container's removal completes on a goroutine its handle's Wait does not cover. A volume that stays is logged under "[sim-<tag>]".
func RemoveVolumesNamed ¶
RemoveVolumesNamed removes every simulator-managed volume whose name starts with prefix: a workload's own volumes once it is gone.
func RequestIDMiddleware ¶
func RequireContainerRuntime ¶
RequireContainerRuntime reports why an operation that runs a container cannot run in this process. Startup refuses to serve when a workload-executing mode cannot reach an engine, so a missing client here means the simulator was started API-only, not that an engine went away.
func ReservePlatformAddress ¶
func ReservePlatformAddress(ctx context.Context, network string, addr netip.Addr, owner string) (func(), error)
ReservePlatformAddress records that owner holds addr on the platform network when the address is one of the network's — the address of a workload an earlier process placed there, which the engine's view of the network does not show for a guest — and returns the release. An address outside the network is another network's, and the release does nothing.
func ResetTrackedStores ¶
func ResetTrackedStores()
ResetTrackedStores drops the recorded set. buildSimulator calls it before it creates a build's stores, so a second build in the same process — which the in-process test servers do — scans its own stores rather than the previous build's abandoned ones.
func ResolveLocalImage ¶
ResolveLocalImage maps pull-through-cache coordinates back to their upstream Docker Hub images for local execution. A cloud can resolve "alpine:latest" to a private registry cache of its own:
- Artifact Registry: "us-central1-docker.pkg.dev/project/docker-hub/library/alpine:latest"
- Amazon ECR: "123456789.dkr.ecr.eu-west-1.amazonaws.com/alpine:latest"
- Azure Container Registry: "myacr.azurecr.io/library/alpine:latest"
The local engine pulls public registry coordinates directly, unchanged.
func RunContainerReaper ¶
func RunContainerReaper() bool
RunContainerReaper handles the detached cleanup mode before a simulator initializes its API server. It returns false for an ordinary invocation.
func RuntimeInfo ¶
func RuntimeInfo() string
RuntimeInfo returns the container runtime name and version for display.
func ScopedDataDir ¶
ScopedDataDir resolves the host directory a service slice keeps its bulk data in — file-share trees, bucket payloads, volume images, build caches:
- the directory overrideEnv names, when overrideEnv is non-empty and set;
- <SIM_DATA_DIR>/<subdir>, so the data survives a restart beside the SQLite state the same directory holds;
- <os.TempDir()>/<tempName>-<pid>, for a process-lifetime run, so two simulators on one host never share it; the server's shutdown removes it.
func SidecarNetwork ¶
SidecarNetwork is the engine network whose sidecar forwarded the request, or "" when it came from anywhere else.
func SidecarTrust ¶
SidecarTrust is the middleware that reads the pair: a server applies it to everything it routes.
func SnapshotVolume ¶
SnapshotVolume captures the full contents of the src volume into the dst volume, creating dst. It returns the filesystem the volume store reported, for logging — "btrfs" and "zfs" are the copy-on-write substrates.
func StartDiagnosticsListener ¶
func StartDiagnosticsListener()
StartDiagnosticsListener serves pprof and the in-flight registry on SIM_DIAGNOSTICS_ADDR (default 127.0.0.1:6060). Set SIM_DIAGNOSTICS_ADDR=off to disable. It never shares the API listener: see the file comment. The registry is the process's, so a process that builds several servers -- the test suites do -- serves it once.
func StartExistingContainer ¶
StartExistingContainer resumes an exited persistent workload container without replacing it, preserving its filesystem, mounts, identity, and port bindings.
func StopAndRemoveContainer ¶
StopAndRemoveContainer stops and removes the container, giving its process the grace the cloud grants between SIGTERM and SIGKILL. It is idempotent cleanup that callers defer, so it logs a removal that did not finish rather than returning it.
func StopContainer ¶
StopContainer stops a running container by ID, sending SIGTERM and then SIGKILL once the grace the cloud grants a stopping workload has elapsed.
func UnregisterSidecarToken ¶
func UnregisterSidecarToken(token string)
UnregisterSidecarToken stops trusting token.
func VolumeExists ¶
VolumeExists reports whether a named volume exists on the engine. Callers on the modeled tier (no engine) get false, which is the truth there.
func VolumeSnapshotIsInstant ¶
VolumeSnapshotIsInstant reports whether the filesystem SnapshotVolume found clones blocks copy-on-write, for the log line that tells an operator whether their deployment has the instant path.
func WaitContainerRemoved ¶
WaitContainerRemoved waits until the runtime no longer owns containerID. Lifecycle callers use this after requesting a stop when the cloud resource must not report its terminal state while its network endpoint or mounts are still present.
func WithCaller ¶
WithCaller returns ctx carrying caller. Only an in-process call carries it: a request from outside the simulator has no way to set a context value.
func WorkloadScope ¶
func WorkloadScope() string
WorkloadScope names the simulator that owns the workloads it starts: its state directory when it persists, which a restarted simulator shares, and its run otherwise. Names derived from it never collide with those of a concurrent simulator.
func WriteDockerConfig ¶
func WriteDockerConfig(spec DockerConfigSpec) (string, error)
WriteDockerConfig writes the Docker client configuration a build service's docker steps run with: the host's own configuration — its CLI plugins, contexts and every setting — with a credential helper in front that answers the registry hosts the spec names with its credential, and hands any other host to the helper the host configured, or to nothing, which the client then reaches anonymously. The returned directory is DOCKER_CONFIG for the steps and its bin/ joins their PATH (DockerConfigEnv); the caller removes it after the build.
Types ¶
type CachedSQLiteStore ¶
type CachedSQLiteStore[T any] struct { // contains filtered or unexported fields }
CachedSQLiteStore keeps every row of a SQLite-backed store in memory and writes through to SQLite. SQLiteStore answers each Get with a SQL query and a JSON decode, the whole cost of a store read in bulk: an Amazon DynamoDB query on a secondary index reads every item of its table, and from SQLite that held the table lock long enough to stall PutItem and UpdateItem behind it.
SQLite stays the durable copy: every write reaches it before memory does, and a new process loads the rows back. Reads return a copy, as MemoryStore's do, so a caller that changes what it read cannot change what is stored.
func NewCachedSQLiteStore ¶
NewCachedSQLiteStore opens the SQLite table and loads every row into memory.
func (*CachedSQLiteStore[T]) Delete ¶
func (s *CachedSQLiteStore[T]) Delete(id string) bool
func (*CachedSQLiteStore[T]) Filter ¶
func (s *CachedSQLiteStore[T]) Filter(fn func(T) bool) []T
func (*CachedSQLiteStore[T]) Generation ¶
func (s *CachedSQLiteStore[T]) Generation() uint64
Generation reports the write counter described on Store; every write goes through the SQLite store, which advances it.
func (*CachedSQLiteStore[T]) Get ¶
func (s *CachedSQLiteStore[T]) Get(id string) (T, bool)
func (*CachedSQLiteStore[T]) Len ¶
func (s *CachedSQLiteStore[T]) Len() int
func (*CachedSQLiteStore[T]) List ¶
func (s *CachedSQLiteStore[T]) List() []T
func (*CachedSQLiteStore[T]) ListPrefix ¶
func (s *CachedSQLiteStore[T]) ListPrefix(prefix string) []Keyed[T]
ListPrefix returns snapshots of the items whose id begins with prefix, in id order.
func (*CachedSQLiteStore[T]) Prune ¶
func (s *CachedSQLiteStore[T]) Prune(expired func(T) bool) int
Prune deletes every row expired reports true for and returns how many it deleted. It picks the candidates from memory, then deletes them from SQLite and memory a batch at a time, so readers wait only for one batch.
func (*CachedSQLiteStore[T]) Put ¶
func (s *CachedSQLiteStore[T]) Put(id string, item T)
func (*CachedSQLiteStore[T]) Update ¶
func (s *CachedSQLiteStore[T]) Update(id string, fn func(*T)) bool
func (*CachedSQLiteStore[T]) Upsert ¶
func (s *CachedSQLiteStore[T]) Upsert(id string, fn func(*T))
type CallResponse ¶
type CallResponse struct {
StatusCode int
Body bytes.Buffer
// contains filtered or unexported fields
}
CallResponse is what a handler answered an in-process call with.
func (*CallResponse) Header ¶
func (c *CallResponse) Header() http.Header
func (*CallResponse) WriteHeader ¶
func (c *CallResponse) WriteHeader(status int)
type Caller ¶
type Caller struct {
// Service is the calling service's principal, such as
// events.amazonaws.com.
Service string
// Source names the resource the service acts for, such as the rule's ARN;
// the receiving service's resource policy can condition on it.
Source string
// Account is the account or project the source belongs to.
Account string
}
Caller is the identity an in-process call is made as when no credential carries it: a cloud service principal acting for one of its resources, as Amazon EventBridge delivers to a target as events.amazonaws.com for a rule. A call made as a role or a service account carries that identity's own credential instead, as any client's request does.
type CloudNetwork ¶
type CloudNetwork struct {
// Name is the engine network's name, derived from the resource's ID.
Name string
// CIDR is the resource's IPv4 range.
CIDR netip.Prefix
// Gateway is the address the cloud's router answers on; the zero value
// takes the first host of CIDR, where Amazon VPC, Google Cloud VPC and
// Azure Virtual Network all put it.
Gateway netip.Addr
// MTU is the largest packet the cloud network carries, which its
// documentation states; zero leaves the engine's default.
MTU int
// Labels go on the engine network beside the simulator's own.
Labels map[string]string
// DynamicRange, when set, is the part of CIDR the engine allocates
// addresses from; the simulator leases the rest itself, for workloads
// the engine does not place.
DynamicRange netip.Prefix
}
CloudNetwork is a cloud network resource — an Amazon VPC, a Compute Engine subnetwork, an Azure virtual network — realized as one engine network over the resource's own address range, so every member's engine-assigned address is the address the cloud API reports for its interface.
type Config ¶
type Config struct {
// ListenAddr is the address to listen on (e.g., ":4566").
ListenAddr string
// TLSCert is the path to the TLS certificate file. Empty disables TLS.
TLSCert string
// TLSKey is the path to the TLS private key file.
TLSKey string
// CallbackListenAddr is the plain-HTTP address the simulator serves beside
// a TLS listener for the workloads it places: the instance metadata and
// identity endpoints their network sidecars forward to, which a container
// reaches without the operator's certificate authority. It serves the
// whole handler chain, plain. Set via SIM_CALLBACK_LISTEN_ADDR; empty
// takes a free port on every interface, and Main resolves it to the bound
// address before Program.Build runs. Without TLS the one listener serves
// everything and this is ListenAddr.
CallbackListenAddr string
// TLSConfigForClient, when set, picks a connection's TLS configuration
// from its ClientHello. base is a copy of the listener's configuration,
// carrying its certificate; the hook returns it adjusted, or nil to keep
// it as it is. A cloud whose front end asks the clients of some hostnames
// for a certificate decides that here, by the hello's ServerName.
TLSConfigForClient func(hello *tls.ClientHelloInfo, base *tls.Config) (*tls.Config, error)
// LogLevel is the zerolog log level (trace, debug, info, warn, error).
LogLevel string
// Provider identifies the cloud provider (aws, gcp, azure).
Provider string
// DataDir is the directory for persistent storage (SQLite database, PID files).
// Set via SIM_DATA_DIR. Empty uses a temp directory.
DataDir string
// RewriteRequest, when set, runs on every request before routing. It
// exists for virtual-hosted addressing, where the cloud carries part of the
// resource identity in the hostname and the router works on paths: the hook
// maps the one onto the other, and records what the client actually sent so
// the signature is still verified against that.
RewriteRequest func(*http.Request)
// Persist enables SQLite-backed state persistence.
// Set via SIM_PERSIST=true. Default false (in-memory only).
Persist bool
// LogWriter, when set, receives every zerolog event beside the console
// writer, bridging the logs to OpenTelemetry. main assigns it from
// InitObservability when the operator brought up the OpenTelemetry stack.
LogWriter *OTelLogWriter
UIOIDCIssuer string
UIOIDCClientID string
UIOIDCClientSecret string
UIPublicURL string
UISessionSecret string
UIOIDCInsecureCookies bool
ApplicationReleaseRevision string
ApplicationMonitoringToken string
// ConsoleDir is a built console bundle to serve, for a simulator built
// without the console embedded. Set via SIM_CONSOLE_DIR.
ConsoleDir string
// Placement is the per-service backend table, as SIM_PLACEMENT spells it:
// `service[:qualifier]=container|microvm`, comma-separated. Empty runs
// every service on containers.
Placement string
}
func ConfigFromEnv ¶
ConfigFromEnv loads configuration from environment variables.
SIM_<PROVIDER>_PORT — port to listen on, ahead of SIM_LISTEN_ADDR SIM_LISTEN_ADDR — listen address (default ":" + defaultPort) SIM_TLS_CERT — TLS certificate file path SIM_TLS_KEY — TLS private key file path SIM_CALLBACK_LISTEN_ADDR — plain-HTTP address for workload callbacks beside a TLS listener (see Config.CallbackListenAddr) SIM_LOG_LEVEL — log level (default "info") SIM_UI_OIDC_ISSUER — Shauth or another OpenID Connect issuer SIM_UI_OIDC_CLIENT_ID — simulator dashboard relying-party client ID SIM_UI_OIDC_CLIENT_SECRET — simulator dashboard relying-party secret SIM_UI_PUBLIC_URL — externally visible simulator origin SIM_UI_SESSION_SECRET — random secret used to sign local sessions APPLICATION_RELEASE_REVISION — immutable deployed release exposed to Shauth validation SIM_MONITORING_TOKEN — deployment bearer for the application observation SIM_PLACEMENT — per-service placement backends (see Config.Placement) SIM_CONSOLE_DIR — a built console bundle to serve (see Config.ConsoleDir)
type ConsoleOptions ¶
type ConsoleOptions struct {
// Coordinates returns the cloud's entries of GET /ui/config.json — the
// cloud API and federation coordinates the console reads real APIs at,
// provisioned the administrator's way and supplied as coordinates, never
// invented by the simulator. The server adds the entries every console
// shares: identityEndpoint, logoutEndpoint and federationSubject.
// authenticated reports whether the console's OpenID Connect layer is on.
Coordinates func(authenticated bool) map[string]string
// AuthRoutes are console auth-layer routes of the cloud's own, keyed by
// mux pattern and registered next to the session routes when
// authentication is enabled. They are registered unprotected and read the
// operator's session themselves through UIAuth, the right contract for an
// XHR endpoint the console polls rather than a browser-navigated redirect
// target.
AuthRoutes map[string]http.HandlerFunc
}
ConsoleOptions is what a cloud's console needs from the server beyond its static bundle.
type ContainerConfig ¶
type ContainerConfig struct {
Image string // container image (e.g., "alpine:latest")
Architecture string // OS/arch (e.g. "linux/arm64") from the workload's spec, never the host's
// RegistryAuth is the credential the engine presents to Image's registry
// when it pulls — the engine API's X-Registry-Auth value, which
// RegistryCredential renders. Empty pulls anonymously.
RegistryAuth string
Command []string // entrypoint override (empty = use image default)
Args []string // command/args (empty = use image default)
Env map[string]string // environment variables
Timeout time.Duration // max execution time (0 = no limit)
Labels map[string]string // container labels for tracking
Network string // Docker network to join (optional)
// NetworkAliases are the names Docker's embedded DNS resolves to this
// container on Network.
NetworkAliases []string
// IPv4Address is the fixed address the container takes on Network, inside
// the network's range: the address the cloud API reports for the
// workload's interface. Empty lets the engine pick one.
IPv4Address string
// MACAddress is the hardware address of the workload's interface on
// Network, as the cloud assigns it to the interface. Empty lets the
// engine pick one.
MACAddress string
// ExtraNetworks are further engine networks the workload has an
// interface on, each at a fixed address in the network's range, with no
// route out through it: a site integrated into more than one virtual
// network.
ExtraNetworks []NetworkAttachment
// JoinNetworks are further engine networks the container is on from its
// first instruction, each at a fixed address and never carrying its
// default route: a platform container the simulator runs on its own behalf
// that stands on several networks at once, as a load balancer node does.
JoinNetworks []NetworkAttachment
// Gateway is where the workload's default route goes: empty for the
// network's own gateway, an address on the network for a next hop the
// cloud's routing names (a NAT gateway), or NoGateway for no route out.
// A backend that cannot route a workload leaves it on the network's
// gateway.
Gateway string
// Routes are routes the workload's namespace carries besides its default
// route: the cloud's fixed link-local addresses through its network's
// sidecar. A backend that cannot route a workload leaves them out.
Routes []Route
// Hostname is the name the container sees as its own; empty leaves the
// engine's default.
Hostname string
// Devices are host device nodes the engine hands the container, as
// "/dev/kvm" or "/dev/net/tun"; only a platform container the simulator
// runs on its own behalf (a node agent) names any.
Devices []string
// Sysctls are namespaced kernel parameters the engine sets in the
// container's namespaces, as "net.ipv4.conf.all.rp_filter".
Sysctls map[string]string
// KeepOnExit leaves the container in place once it exits, with its
// filesystem, for RestartContainer, CommitContainer or RemoveContainer: a
// virtual machine instance's root disk outlives a stop.
KeepOnExit bool
// Seed files are written into the container's filesystem after it is
// created and before it starts: what a cloud hands an instance through
// its platform rather than its image or its environment — user data, the
// instance's own init.
Seed []SeedFile
// Ingress is what the workload may receive on its network: stages a
// packet passes in turn, each a rule list whose first match decides,
// where an accept hands it to the next stage and a stage nothing matches
// drops it; no stages admit everything. A cloud compiles its security
// groups, firewall rules or network security groups into it. The microVM
// backend enforces it at the guest's tap; the container backend cannot
// filter between two containers on one network and runs the workload
// unfiltered.
Ingress [][]netrules.PacketRule
NetworkMode string // Docker network mode (e.g. "container:<id>" for shared netns)
// PidMode joins another container's pid namespace ("container:<id>"):
// a platform helper reading a workload's processes. Empty is the
// container's own namespace.
PidMode string
Name string // container name (optional, auto-generated if empty)
Tty bool // allocate a pseudo-TTY
OpenStdin bool // keep stdin open
Binds []string // bind mounts (e.g., "vol:/path")
ExtraHosts []string // --add-host entries (e.g., "host.docker.internal:host-gateway")
// DNS are the resolvers written into the container's /etc/resolv.conf. A
// workload in its own network namespace cannot reach the embedded resolver
// Docker would otherwise configure, so the namespace's own resolver is named
// here; empty leaves Docker's default in place.
DNS []string
WorkingDir string // working directory inside the container (optional)
// PublishPorts lists container TCP ports the engine publishes on
// 127.0.0.1, each on a host port the engine allocates when it starts the
// container; read it back with ContainerHandle.PublishedPort. Host-addressed
// data planes use it to reach a workload's listener cross-platform:
// container IPs are only routable from the host on Linux, while a loopback
// port binding works on Docker Desktop (macOS/Windows) too. The engine
// allocates the port because a port the caller picked is free only until
// something else binds it.
PublishPorts []int
// Sandbox restricts the workload as its cloud platform does; each
// cloud-product handler picks the matching profile (SandboxLambda,
// SandboxFargate, and so on). The zero value enforces nothing.
Sandbox SandboxProfile
// MemoryBytes is the hard memory limit (cgroup memory.max) in bytes; zero
// is unbounded. Cloud handlers translate the product's advertised sizing
// (an Amazon ECS task's or container's memory) here, so the cgroup matches
// what the metadata advertises.
MemoryBytes int64
// NanoCPU is the CPU limit (cgroup cpu.max) in units of 1e-9 CPUs — e.g.
// 1_000_000_000 == 1 vCPU. Zero = unbounded. Cloud handlers translate the
// product's advertised CPU sizing here.
NanoCPU int64
// CancelGracePeriod is how long the workload gets between the SIGTERM a
// cancellation sends and the SIGKILL that follows it — the cloud's own
// documented stop grace (Cloud Run's ten seconds, an Amazon ECS task's
// stopTimeout). Zero kills the workload outright, which is what a cloud
// does to a command it has cancelled rather than a workload it is stopping.
CancelGracePeriod time.Duration
// TrackMemoryPeak makes the handle observe the container's memory usage
// through the engine's stats endpoint for as long as it runs, so a cloud
// product that reports what a workload consumed — the AWS Lambda
// invocation REPORT's Max Memory Used — has a measurement to report.
// Read it back with ContainerHandle.MemoryPeakBytes.
TrackMemoryPeak bool
}
type ContainerHandle ¶
type ContainerHandle struct {
ContainerID string
// contains filtered or unexported fields
}
ContainerHandle manages a running container.
func AdoptContainer ¶
func AdoptContainer(containerID string, cfg ContainerConfig, sink LogSink) (*ContainerHandle, error)
AdoptContainer attaches lifecycle observation to a container created by an earlier persistent simulator process. It never restarts the workload; callers decide whether an exited cloud workload should remain terminal or resume. A container the earlier process left frozen by a volume capture it did not finish is thawed, since no capture of this process holds it.
func StartContainerSyncContext ¶
func StartContainerSyncContext(ctx context.Context, cfg ContainerConfig, sink LogSink) (*ContainerHandle, error)
StartContainerSyncContext pulls the image when needed, creates and starts a container, and returns its handle once it has started. Stdout and stderr stream to sink; handle.Wait blocks until exit.
ctx bounds the start alone: once it is done the pull and the create stop and the call fails, while a container that already started runs until it exits or handle.Cancel stops it.
func (*ContainerHandle) Cancel ¶
func (h *ContainerHandle) Cancel()
Cancel stops and removes the container.
func (*ContainerHandle) Exited ¶
func (h *ContainerHandle) Exited() <-chan struct{}
Exited closes once the container has exited; Wait then returns at once.
func (*ContainerHandle) MemoryPeakBytes ¶
func (h *ContainerHandle) MemoryPeakBytes() uint64
MemoryPeakBytes reports the highest memory usage the container engine accounted to this container up to now. A container still running is read once more before the figure is returned, so whatever it holds at the moment of the call counts. It is zero when the engine reported none — a container started without ContainerConfig.TrackMemoryPeak, or one the engine stopped accounting for before any reading — and a caller that reports the figure must then report nothing rather than a substitute.
func (*ContainerHandle) PublishedPort ¶
PublishedPort returns the 127.0.0.1 host port the engine bound for the container's containerPort/tcp, listed in ContainerConfig.PublishPorts.
func (*ContainerHandle) StartedAt ¶
func (h *ContainerHandle) StartedAt() time.Time
StartedAt is the moment the engine was asked to start the container: its process starts after it. An adopted container reports the start the engine recorded, and none when the engine no longer held it.
func (*ContainerHandle) Wait ¶
func (h *ContainerHandle) Wait() ProcessResult
Wait blocks until the container exits, and returns how it exited to every caller.
type DockerConfigSpec ¶
type DockerConfigSpec struct {
// HostPatterns are shell patterns, matched against a registry host with
// and without its port, the credential helper answers with Credential.
HostPatterns []string
// Hosts are the registry hosts the configuration names outright, as
// `credHelpers` entries, so a client that enumerates configured
// registries before it starts — the legacy `docker build`, which sends
// the daemon the credentials of every registry the configuration
// names — carries the credential for them. Each is matched by
// HostPatterns too.
Hosts []string
Credential DockerCredential
}
DockerConfigSpec describes the credential a build service's Docker configuration answers with and the registries it answers for.
type DockerCredential ¶
DockerCredential is what a credential helper answers for a registry host: a username and a secret. With DockerIdentityTokenUsername as the username the secret is an identity token the Docker client exchanges through the registry's OAuth 2.0 refresh-token grant, the way `az acr login` stores one.
type EngineBuild ¶
type EngineBuild struct {
// Name is the image repository; the tag is a digest of the build context,
// so a change to the sources builds a new image and an unchanged one
// reuses the engine's copy.
Name string
// Context returns the build context for an architecture ("amd64",
// "arm64"), its Dockerfile included.
Context func(arch string) (map[string][]byte, error)
// Bases are the images the Dockerfile's FROM lines name. EnsureEngineBuild
// pulls them first, with the retries a registry's throttle needs, so the
// build finds them held.
Bases []string
}
EngineBuild is an image the simulator builds on the container engine from sources it carries, for the engine's own architecture.
type ExistingContainer ¶
type ExistingContainer struct {
ID string
Running bool
PublishedPorts map[int]int
Labels map[string]string
}
ExistingContainer describes a workload container that outlived a persistent simulator control-plane process. Service slices use the same cloud-resource labels they supplied at creation to reclaim ownership after restart.
func FindExistingContainers ¶
func FindExistingContainers(labels map[string]string) ([]ExistingContainer, error)
FindExistingContainers returns every container carrying all requested labels, including exited containers whose terminal result has not yet been reconciled into the durable cloud resource.
type FrameReader ¶
type FrameReader struct {
// contains filtered or unexported fields
}
FrameReader is a bounds-checked cursor over an attacker-controlled byte buffer. Every read returns an error rather than panicking on a short buffer, and Take rejects a negative or over-long length so a wire-declared size can never slice past the buffer or drive a giant allocation. Use it for hand-rolled binary wire decoders instead of raw binary.BigEndian + b[i:j].
func NewFrameReader ¶
func NewFrameReader(data []byte) *FrameReader
func (*FrameReader) Remaining ¶
func (r *FrameReader) Remaining() int
Remaining reports the number of unread bytes.
type GenerationIndex ¶
type GenerationIndex[T any] struct { // contains filtered or unexported fields }
GenerationIndex answers a lookup from a store without reading all of it. A store's rows are JSON, so List decodes every row it returns: the right cost for a List API and the wrong one for finding one row on a hot path — above all the lookups a handler wrapper makes to decide whether to claim a request, which run for every request in the process.
The index keys on the store's Generation instead of being invalidated by hand, which would be a second source of truth: two reads that observe the same generation observed the same contents, so a resource deleted, renamed or replaced leaves the index on the next lookup. Generations are unique across every store in the process, so replacing a store — which tests do between cases — cannot present a generation an index already holds.
func (*GenerationIndex[T]) Lookup ¶
func (i *GenerationIndex[T]) Lookup(store Store[T], key string, keysOf func(T) []string) (T, bool)
Lookup returns the first row indexed under key. keysOf maps a row to the keys it answers on; Lookup calls it only when it rebuilds the index.
func (*GenerationIndex[T]) LookupAll ¶
func (i *GenerationIndex[T]) LookupAll(store Store[T], key string, keysOf func(T) []string) []T
LookupAll returns every row indexed under key, in the order the store listed them. Callers that can legitimately have more than one row on a key — two virtual networks sharing a CIDR, say — need all of them.
type KeyedLocks ¶
type KeyedLocks struct {
// contains filtered or unexported fields
}
KeyedLocks serializes work on one key at a time — the writes to one stored object, say. An object store evaluates a write's conditions and applies the write as one step: of two writers that each require the version they read, exactly one succeeds. A caller holds the key's lock from reading the object to storing what replaces it. A key's entry lives only while someone holds or awaits it, so the table stays as small as the set of keys in use.
func NewKeyedLocks ¶
func NewKeyedLocks() *KeyedLocks
func (*KeyedLocks) Lock ¶
func (l *KeyedLocks) Lock(key string) func()
Lock takes key's lock and returns its release.
type LogSink ¶
type LogSink interface {
WriteLog(line LogLine)
}
LogSink receives log lines as the workload writes them. Each cloud implements its own sink (Amazon CloudWatch Logs, Cloud Logging, Azure Monitor Logs).
type MemoryStore ¶
type MemoryStore[T any] struct { // contains filtered or unexported fields }
MemoryStore is an in-memory implementation of Store backed by a map.
func NewStateStore ¶
func NewStateStore[T any]() *MemoryStore[T]
NewStateStore returns an empty in-memory store.
func (*MemoryStore[T]) Delete ¶
func (s *MemoryStore[T]) Delete(id string) bool
func (*MemoryStore[T]) Filter ¶
func (s *MemoryStore[T]) Filter(fn func(T) bool) []T
Filter returns snapshots of the stored items matching fn.
func (*MemoryStore[T]) Generation ¶
func (s *MemoryStore[T]) Generation() uint64
Generation reports the write counter described on Store.
func (*MemoryStore[T]) Get ¶
func (s *MemoryStore[T]) Get(id string) (T, bool)
Get returns a snapshot of the stored item. Reference fields (maps, slices, pointers) are deep-copied so callers cannot mutate store-owned state.
func (*MemoryStore[T]) Len ¶
func (s *MemoryStore[T]) Len() int
func (*MemoryStore[T]) List ¶
func (s *MemoryStore[T]) List() []T
List returns snapshots of all stored items.
func (*MemoryStore[T]) ListPrefix ¶
func (s *MemoryStore[T]) ListPrefix(prefix string) []Keyed[T]
ListPrefix returns snapshots of the items whose id begins with prefix, in id order.
func (*MemoryStore[T]) Prune ¶
func (s *MemoryStore[T]) Prune(expired func(T) bool) int
Prune deletes every item expired reports true for and returns how many it deleted.
func (*MemoryStore[T]) Put ¶
func (s *MemoryStore[T]) Put(id string, item T)
func (*MemoryStore[T]) Update ¶
func (s *MemoryStore[T]) Update(id string, fn func(*T)) bool
func (*MemoryStore[T]) Upsert ¶
func (s *MemoryStore[T]) Upsert(id string, fn func(*T))
Upsert atomically create-or-modifies the item at id under the single write lock (absent → the zero value), avoiding the Update-then-Put race.
type NetworkAttachment ¶
NetworkAttachment is a further network a workload joins at an address.
type OCIBlob ¶
OCIBlob is a stored content-addressed blob (image config or layer), keyed by `scope/repo@digest`.
type OCIManifest ¶
type OCIManifest struct {
Scope string
ContentType string
Digest string
Data []byte
Repo string
Ref string
// Pushed is when the registry received this manifest, which the
// properties APIs the clouds put in front of it report.
Pushed time.Time
}
OCIManifest is a stored image manifest, keyed by `scope/repo:reference` (tag or digest).
type OCIPull ¶
type OCIPull struct {
Root OCIPulledManifest
Manifests []OCIPulledManifest
Blobs []OCIPulledBlob
}
OCIPull is an image as a registry serves it: the manifest the reference names, any manifests an index lists, and every blob they reference.
func PullOCIImage ¶
func PullOCIImage(ctx context.Context, client *http.Client, baseURL, repo, reference, username, password string, maxManifests int) (OCIPull, error)
PullOCIImage fetches repo:reference from the registry at baseURL over the Registry v2 API, answering a bearer challenge with the credentials when given, and keeps every byte as served.
type OCIPulledBlob ¶
OCIPulledBlob is one blob a pull fetched.
type OCIPulledManifest ¶
OCIPulledManifest is one manifest a pull fetched, as the source served it.
type OCIRegistry ¶
type OCIRegistry struct {
Manifests Store[OCIManifest]
Blobs Store[OCIBlob]
Uploads Store[OCIUpload]
// OnManifestPut, if set, runs after the registry stores a manifest, so the
// cloud can register a control-plane image row against the registry the
// request addressed. r is the client's push, or nil for a manifest the
// cloud stored itself through PutManifest.
OnManifestPut func(r *http.Request, scope, repo, ref, contentType string, data []byte)
// OnManifestDelete, if set, runs under the manifest lock after a client's
// DELETE removed a manifest and its aliases, so the cloud can drop the
// control-plane rows that describe that digest. It must not re-enter the
// manifest store.
OnManifestDelete func(r *http.Request, scope, repo, digest, contentType string)
// HydrateManifest, if set, runs on a manifest GET/HEAD miss so the cloud's
// pull-through cache can populate the manifest and its blobs through
// PutBlob, in the scope of the registry the request addressed. It returns
// true if it populated the requested manifest.
HydrateManifest func(reg *OCIRegistry, scope, repo, ref string) bool
// SkipPath, if set, returns true for `/v2/`-prefixed paths the surrounding
// mux serves elsewhere (Artifact Registry's `/v2/projects/` control-plane
// routes); the data plane answers them 404 so the cloud handler takes them.
SkipPath func(path string) bool
// Authorize, if set, authenticates every `/v2/` request before the data
// plane acts on it. repo is the repository the request addresses — empty
// for the `/v2/` base ping, which addresses the registry itself. The hook
// returns true to let the request through; on false it has already written
// the registry's own refusal (the Docker Registry HTTP API v2 challenge and
// error body), so the caller must return without touching the stores.
//
// The hook belongs to the cloud that mounts the registry because the
// credentials, the token service and the challenge realm are that cloud's:
// the protocol under `/v2/` is identical everywhere, the authority that
// issues tokens for it is not.
Authorize func(w http.ResponseWriter, r *http.Request, repo string) bool
// AdmitRepository, if set, decides whether the repository a request names
// may be acted on, and runs after Authorize and before the handler so a
// refused request never reads or writes a store. push reports whether the
// request is one of the verbs that puts content into a repository — the
// blob upload and the manifest PUT a `docker push` is made of — which is
// the distinction a registry needs to decide whether a name it does not
// hold yet may come into existence now. The hook returns true to let the
// request through; on false it has already written the registry's refusal.
//
// It belongs to the cloud that mounts the registry because whether a
// repository is an explicit resource is that cloud's contract: Amazon ECR
// requires one to be created before it can be used, and refuses a request
// naming any other.
AdmitRepository func(w http.ResponseWriter, r *http.Request, repo string, push bool) bool
// BaseResponse, if set, writes the authorized answer to the API-version
// probe at `/v2/`. The three registries this data plane serves disagree
// there: Amazon ECR answers status 200 with `content-length: 0` and no
// `content-type` at all, Artifact Registry the same empty body as
// `text/html; charset=UTF-8`, Azure Container Registry the two-byte body
// `{}` as `application/json; charset=utf-8`. Docker Distribution's `{}` is
// what the reference implementation sends and none of these three do. A
// registry mounted without the hook answers the way Amazon ECR does.
BaseResponse func(w http.ResponseWriter)
// RefuseChunkedUpload, if set, makes an upload session accept exactly one
// write and calls the hook to refuse the second. Artifact Registry
// documents that it does not support Docker chunked uploads; the line is
// between one write and several, not between PATCH and PUT, because every
// container engine's `docker push` sends the whole blob in one PATCH and
// finalizes with PUT, and pushes to the live service succeed.
RefuseChunkedUpload func(w http.ResponseWriter)
// Scope, if set, returns the identity of the registry a request addresses,
// which every stored manifest, blob and upload is keyed within. The
// mounting cloud owns it because only that cloud knows how a request names
// a registry — Azure Container Registry resolves the Host header against
// the login server its control plane advertises, and the identity it
// returns is the registry's ARM resource ID, the same key the rest of the
// Azure stores use.
//
// A registry mounted without one keys its content in a single unnamed
// scope, which is correct only for a cloud that serves exactly one
// registry per simulator.
Scope func(r *http.Request) string
// contains filtered or unexported fields
}
OCIRegistry serves the OCI Distribution data plane from a trio of stores.
func (*OCIRegistry) DeleteManifest ¶
func (reg *OCIRegistry) DeleteManifest(scope, repo, ref string) bool
func (*OCIRegistry) DeleteTagOnly ¶
func (reg *OCIRegistry) DeleteTagOnly(scope, repo, tag string) bool
DeleteTagOnly removes a tag and leaves the manifest it pointed at in place. That is the difference between deleting a tag and deleting a manifest: the content stays addressable by digest, untagged rather than gone.
func (*OCIRegistry) ExportImage ¶
func (reg *OCIRegistry) ExportImage(scope, repo, reference string, maxManifests int) (OCIPull, error)
ExportImage reads repo:reference out of the registry as a pull would fetch it, from the stores directly.
func (*OCIRegistry) GetBlob ¶
func (reg *OCIRegistry) GetBlob(scope, repo, digest string) ([]byte, bool)
GetBlob reads a stored blob. The properties APIs the clouds put in front of a registry describe an image from the config blob its manifest points at, which is where the registry actually holds the platform it was built for.
func (*OCIRegistry) GetManifest ¶
func (reg *OCIRegistry) GetManifest(scope, repo, ref string) (OCIManifest, bool)
DeleteManifest removes a manifest and every alias pointing at the same content, which is what the registry's own DELETE does: a manifest removed by digest takes its tags with it, and one removed by tag takes the digest entry. GetManifest is the manifest repo:ref names.
func (*OCIRegistry) ImportImage ¶
func (reg *OCIRegistry) ImportImage(scope, repo string, pull OCIPull, tags []string)
ImportImage stores a pulled image in repo under each tag, or by digest alone when no tag is given, as a push of the same bytes would.
func (*OCIRegistry) PutBlob ¶
func (reg *OCIRegistry) PutBlob(scope, repo, digest, contentType string, data []byte)
PutBlob stores a content-addressed blob in one registry's scope (used by hydration hooks).
func (*OCIRegistry) PutManifest ¶
func (reg *OCIRegistry) PutManifest(scope, repo, ref, contentType string, data []byte)
PutManifest stores a manifest as a push of it would, under its reference and under its digest, and runs the control-plane hook so the registry's own records see it. A hydration hook uses this to serve content it fetched from somewhere else — an image cached through a pull-through cache rule is in the repository exactly as a pushed one is.
func (*OCIRegistry) Register ¶
func (reg *OCIRegistry) Register(srv *Server)
Register mounts the data plane on the /v2/ subtree once per method and dispatches inside. One method-specific subtree per verb sidesteps three ServeMux pitfalls: a `{name...}` wildcard must be the final segment; per-method wildcard patterns leave some verb unrouted; and a bare all-method `/v2/` conflicts with a method-specific root pattern like awsJson's `POST /`, which a method-specific subtree outranks.
type OCIUpload ¶
OCIUpload tracks an in-progress (possibly chunked) blob upload, keyed by `scope/uuid`.
type OTelLogWriter ¶
type OTelLogWriter struct {
// contains filtered or unexported fields
}
OTelLogWriter bridges zerolog to OpenTelemetry logs, as an io.Writer that slots into zerolog.MultiLevelWriter beside the ConsoleWriter.
type Observability ¶
type Observability struct {
LogWriter *OTelLogWriter
Shutdown func(context.Context) error
}
Observability holds the trace and log SDK shutdown and a zerolog writer that mirrors entries to the OpenTelemetry logs SDK.
func InitObservability ¶
func InitObservability(serviceName string) (*Observability, error)
InitObservability sets up the OpenTelemetry providers when OTEL_EXPORTER_OTLP_ENDPOINT is set, and otherwise returns an Observability whose Shutdown does nothing.
type ParseGuard ¶
type ParseGuard struct {
// contains filtered or unexported fields
}
ParseGuard bounds recursion depth and total node count for a recursive-descent parser so deeply-nested or pathological input can't blow the stack or hang. Enter() at the top of each recursive production, Leave() (usually deferred) on the way out; bail out of the parse when Enter() returns false.
func NewParseGuard ¶
func NewParseGuard(maxDepth, maxNodes int) *ParseGuard
NewParseGuard returns a guard with the given caps (0 = the Default caps).
func (*ParseGuard) Enter ¶
func (g *ParseGuard) Enter() bool
Enter records one level of recursion / one node and reports whether the parse is still within budget. A false return means the input is too deep/large and the parser must stop (treat as a parse error).
func (*ParseGuard) Leave ¶
func (g *ParseGuard) Leave()
Leave undoes one Enter's depth (not the node count — total work stays capped).
type PrefixStore ¶
type PrefixStore[T any] interface { Get(id string) (T, bool) Put(id string, item T) Delete(id string) bool ListPrefix(prefix string) []Keyed[T] Len() int Update(id string, fn func(*T)) bool Upsert(id string, fn func(*T)) Generation() uint64 }
PrefixStore is a Store that cannot be read whole: what it holds is read by id or by id prefix. A store of object contents is one, because a read of all of it costs every byte every bucket holds, and a listing of one bucket has to cost that bucket.
type ProcessResult ¶
ProcessResult is the terminal state of a workload: the exit code its main process returned, when it ran, and a non-nil Error when it never started or was killed rather than exiting cleanly.
type Program ¶
type Program struct {
// Provider names the cloud ("aws", "gcp", "azure"); it selects the
// SIM_<PROVIDER>_PORT variable and the observability service name.
Provider string
// DefaultPort is the port served when neither SIM_<PROVIDER>_PORT nor
// SIM_LISTEN_ADDR names one.
DefaultPort string
// Configure, when set, checks or records the resolved configuration before
// anything is built.
Configure func(*Config) error
// Build constructs the server with every service slice registered, with
// the configuration's CallbackListenAddr resolved to the address the
// server's listeners bound.
Build func(Config) (*Server, error)
// Start, when set, starts what serves beside the HTTP port. The stop it
// returns runs once the HTTP server has shut down and its workers have
// returned, before the database closes.
Start func(*Server, Config) (stop func(context.Context) error, err error)
}
Program is one simulator binary's startup: what Main runs between reading the configuration and serving.
type RegistryScope ¶
type RegistryScope struct {
Type string `json:"type"`
Name string `json:"name"`
Actions []string `json:"actions"`
}
RegistryScope is one Docker Registry v2 token scope, `<type>:<name>:<action>[,<action>…]`, and one entry of a registry token's `access` claim.
func ParseRegistryScope ¶
func ParseRegistryScope(value string) (RegistryScope, bool)
ParseRegistryScope reads one scope. It reports false when the type or name is missing; the action list may be empty.
func ParseRegistryScopes ¶
func ParseRegistryScopes(values []string) []RegistryScope
ParseRegistryScopes reads the scopes of a token request, which a client may repeat or separate with spaces. A scope that names no action is dropped.
func (RegistryScope) String ¶
func (s RegistryScope) String() string
type RuntimeMode ¶
type RuntimeMode string
RuntimeMode is how a simulator process was started, and decides whether it holds a container engine client. Startup resolves it once from the SIM_RUNTIME environment variable and carries it on the server: re-reading the variable later would let what the process reports about itself drift from what it actually has.
const ( // RuntimeModeContainer is the default: workloads run as containers, so the // process must hold a container engine client and refuses to start without // one. RuntimeModeContainer RuntimeMode = "docker" // RuntimeModeAPIOnly serves the API surface without a container engine, for // runs that exercise control planes and never execute a workload. It is the // one mode that legitimately holds no engine client, which is why it has to // be asked for by name rather than fallen into. RuntimeModeAPIOnly RuntimeMode = "process" )
func ResolveRuntimeMode ¶
func ResolveRuntimeMode() (RuntimeMode, error)
ResolveRuntimeMode reads the runtime mode from the environment. An empty variable is the container default; anything else must name a mode the simulator implements. It refuses an unrecognised value rather than reading it as "not API-only": the variable alone decides whether the process can run workloads, and a misread shows up much later as workloads failing one by one against a process that looks healthy.
func (RuntimeMode) ExecutesWorkloads ¶
func (m RuntimeMode) ExecutesWorkloads() bool
ExecutesWorkloads reports whether the mode runs containers, and therefore whether startup must obtain a container engine client before serving.
type SQLiteStore ¶
type SQLiteStore[T any] struct { // contains filtered or unexported fields }
SQLiteStore persists a Store in one SQLite table of (key TEXT, value BLOB).
func NewSQLiteStore ¶
NewSQLiteStore opens a store over table, creating the table when absent.
func (*SQLiteStore[T]) Delete ¶
func (s *SQLiteStore[T]) Delete(id string) bool
func (*SQLiteStore[T]) Filter ¶
func (s *SQLiteStore[T]) Filter(fn func(T) bool) []T
func (*SQLiteStore[T]) Generation ¶
func (s *SQLiteStore[T]) Generation() uint64
Generation reports the write counter described on Store.
func (*SQLiteStore[T]) Get ¶
func (s *SQLiteStore[T]) Get(id string) (T, bool)
func (*SQLiteStore[T]) Len ¶
func (s *SQLiteStore[T]) Len() int
func (*SQLiteStore[T]) List ¶
func (s *SQLiteStore[T]) List() []T
func (*SQLiteStore[T]) ListPrefix ¶
func (s *SQLiteStore[T]) ListPrefix(prefix string) []Keyed[T]
ListPrefix returns the items whose id begins with prefix, in id order. It is a range on the primary key, so SQLite reads and this decodes only those rows.
func (*SQLiteStore[T]) Prune ¶
func (s *SQLiteStore[T]) Prune(expired func(T) bool) int
Prune deletes every row expired reports true for and returns how many it deleted. It reads the table in key order a batch at a time and re-checks each candidate under the write lock, so a row rewritten since the scan survives.
Prune runs on a background goroutine, where a panic takes the whole simulator down, and every task's network namespace with it, so it treats a busy database as a reason to stop rather than a fault. Contention is not corruption: the rows are still there, and the next sweep deletes them.
func (*SQLiteStore[T]) Put ¶
func (s *SQLiteStore[T]) Put(id string, item T)
func (*SQLiteStore[T]) Update ¶
func (s *SQLiteStore[T]) Update(id string, fn func(*T)) bool
func (*SQLiteStore[T]) Upsert ¶
func (s *SQLiteStore[T]) Upsert(id string, fn func(*T))
Upsert atomically create-or-modifies the row at id under the single write lock (absent → the zero value), avoiding the Update-then-Put race.
type SandboxProfile ¶
type SandboxProfile struct {
// Privileged stays false: the clouds never run workload code privileged,
// only some platform-managed system containers.
Privileged bool
// ReadonlyRootfs mounts the root filesystem read-only, as AWS Lambda, Cloud
// Run, Cloud Functions (2nd gen), Azure Container Apps and Azure Functions
// do for workload containers; only declared writable mounts (/tmp) stay
// writable.
ReadonlyRootfs bool
// User, when set, forces this UID:GID (or name) into
// container.Config.User: AWS Lambda runs as uid 1051 (sbx_user1051); Cloud
// Run runs as non-root unless the image names a user.
User string
// CapDrop lists capabilities to drop; ALL drops the kernel's CAP_BASE set
// and CapAdd lets specific ones back in.
CapDrop []string
// CapAdd lists capabilities to keep. AWS Lambda workloads hold almost none;
// Cloud Run grants SETUID/SETGID by default, and Azure Container Apps
// similar.
CapAdd []string
// NoNewPrivileges sets `--security-opt=no-new-privileges`, which keeps
// setuid binaries from escalating; every cloud enforces it.
NoNewPrivileges bool
// TmpfsSize, when set, mounts /tmp as tmpfs with this size option
// ("size=512m"), as AWS Lambda does.
TmpfsSize string
// VolatileRun mounts /run as tmpfs, so each boot of a machine starts with
// an empty /run as a booted Linux system does.
VolatileRun bool
// DenyDockerSocket refuses to mount the host's docker.sock under any path;
// no cloud exposes such a surface.
DenyDockerSocket bool
// DenyHostNetwork refuses NetworkMode=host; no cloud gives workloads host
// networking.
DenyHostNetwork bool
}
SandboxProfile holds the security restrictions the cloud platform applies to workload containers, which the simulator enforces on the engine so a workload cannot rely on a privilege the cloud would refuse. A profile may be stricter than the cloud where the engine makes that cheap (capability drops): never laxer than the cloud is the bar.
func (SandboxProfile) Apply ¶
func (p SandboxProfile) Apply(hostCfg *container.HostConfig, containerCfg *container.Config) error
Apply enforces the profile on hostCfg and containerCfg. It fails when hostCfg.NetworkMode or hostCfg.Binds violates a deny rule rather than fixing the caller's mistake.
type Scanner ¶
type Scanner struct {
// contains filtered or unexported fields
}
Scanner is a bounds-safe cursor over a string. Every accessor is range-checked so a parser can never panic on an index or slice, regardless of input.
func NewScanner ¶
type SeedFile ¶
type SeedFile struct {
// Path is absolute inside the container; its directory is created.
Path string
Mode int64
Data []byte
}
SeedFile is one file written into a container before it starts.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func NewServer ¶
NewServer fails when persistence is requested (cfg.Persist) but the data directory cannot be opened: degrading to in-memory state would hide the misconfiguration and lose data across restarts.
func (*Server) Call ¶
func (s *Server) Call(r *http.Request) *CallResponse
Call serves r in-process through the server's whole handler chain and returns what the handler answered. r's context is the caller's: its deadline bounds the call, and a Caller on it is the identity the call is made as when r carries no credential of its own.
func (*Server) CallbackListenAddr ¶
CallbackListenAddr is the plain-HTTP listen address the workloads call back on, with the port Listen bound: ListenAddr without TLS, else the callback listener's.
func (*Server) Handle ¶
Handle registers a pattern on the server's mux and records it for RoutePatterns.
func (*Server) HandleFunc ¶
func (s *Server) HandleFunc(pattern string, handler http.HandlerFunc)
HandleFunc registers a handler function on the server's mux and records its pattern for RoutePatterns.
func (*Server) Listen ¶
Listen binds the API listener at ListenAddr and, when it serves TLS, the plain-HTTP callback listener at CallbackListenAddr, without serving yet.
func (*Server) ListenAndServe ¶
ListenAndServe binds the listeners and serves until shutdown.
func (*Server) OnStop ¶
OnStop registers what shutdown runs after the HTTP server has drained and the background workers have returned, while the database is still open: the listeners, placement backends and workloads a program started beside the HTTP port read and write state as they stop.
func (*Server) Payloads ¶
Payloads returns the payload store called name. A persistent server keeps it beside its database, so a restart serves the same bytes; otherwise it lives in a temporary directory the server removes when it stops.
func (*Server) RegisterUI ¶
func (s *Server) RegisterUI(fsys fs.FS, console ConsoleOptions)
RegisterUI registers an embedded SPA at /ui/ and redirects GET / to /ui/. When a simulated service already owns the API root ("GET /{$}"), the API surface wins — registering the redirect anyway would panic the mux at startup — and that service delegates the requests it declines to ServeUIRoot, so the bare origin still reaches the console.
func (*Server) RequestContext ¶
RequestContext returns parent carrying what the server gives every request it serves. Build the request for a handler called in-process from it, so the handler finds what it finds when the server routes the request.
func (*Server) RoutePatterns ¶
RoutePatterns returns every pattern registered through Handle / HandleFunc, in registration order.
func (*Server) Serve ¶
Serve serves on the listeners Listen bound and blocks until shutdown. It listens for SIGTERM and SIGINT for graceful shutdown.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP serves through the same final handler chain as ListenAndServe.
func (*Server) ServeUIRoot ¶
ServeUIRoot redirects a request at the bare origin to the console, and reports whether it did. A service that owns the API root calls this when the request is not addressed to its own API — an operator who types the bare origin into a browser then reaches the console instead of a bare 404, while the service keeps the root for its real clients. It reports false, writing nothing, when no console is registered.
func (*Server) SetSpecValidator ¶
func (s *Server) SetSpecValidator(v SpecValidator)
SetSpecValidator registers the per-cloud validator and, when SOCKERLESS_SPEC_VALIDATE is set, arms the capture middleware. Call it before ListenAndServe or ServeHTTP.
func (*Server) StartBackground ¶
StartBackground runs service work under the server lifecycle. The worker must return when ctx is cancelled. ListenAndServe cancels and drains every worker before checkpointing and closing SQLite, so no service queries durable state after shutdown closed the database.
A panic in a worker ends the worker, not the process: net/http recovers a handler's panic, but one on a bare goroutine would end the simulator and tear down the network namespace of every running task. The stack goes where the deployment collects it, so the failure is as loud as a crash.
name says what the worker is, and is what a shutdown still waiting on it reports.
func (*Server) StopBackground ¶
func (s *Server) StopBackground()
StopBackground cancels every background worker the server started and waits for them to return. Shutting the listener down does this on its way out; a caller that builds a server without serving on it — a test exercising one registered subsystem, say — has to do it explicitly, or those workers keep running against package-level state after the caller is finished with it.
type SpecValidator ¶
type SpecValidator func(req *http.Request, reqBody []byte, status int, respHeader http.Header, respBody []byte) []SpecViolation
SpecValidator inspects one exchange and reports spec divergences. status/respBody are the simulator's response; reqBody is the request payload (already drained and restored on the request the handler saw).
type SpecViolation ¶
type SpecViolation struct {
// Op identifies the operation (X-Amz-Target, "METHOD /path", ...).
Op string `json:"op"`
// Kind classifies the divergence (unknown-field, type-mismatch, ...).
Kind string `json:"kind"`
// Field is the JSON path of the offending member.
Field string `json:"field"`
// Detail is a human-readable explanation.
Detail string `json:"detail"`
}
SpecViolation is one observed divergence between a simulator response and the vendored cloud API spec (specs/cloud-api/).
func (SpecViolation) Key ¶
func (v SpecViolation) Key() string
Key is the stable identity used by the ratchet allowlist.
type StateStore ¶
type StateStore[T any] = MemoryStore[T]
StateStore is an alias for backward compatibility. New code should use Store[T] interface or MemoryStore[T] directly.
type Store ¶
type Store[T any] interface { Get(id string) (T, bool) Put(id string, item T) Delete(id string) bool List() []T Filter(fn func(T) bool) []T // ListPrefix returns snapshots of the items whose id begins with prefix, // with their ids, in id order. It reads those items and no others. ListPrefix(prefix string) []Keyed[T] Len() int Update(id string, fn func(*T)) bool // Upsert atomically applies fn to the item at id under a single lock, // creating it from the zero value when absent (create-or-modify). Use it // for read-modify-write that must not race a concurrent writer the way a // separate Update-then-Put pair would. Upsert(id string, fn func(*T)) // Prune deletes every item expired reports true for and returns how many // it deleted, without loading the whole store at once. Prune(expired func(T) bool) int // Generation is a counter this store advances on every write that // changed it. Two reads that observe the same generation observed the // same contents, so a caller that derives an index from List can keep // that index until the generation moves instead of rebuilding it per // request. It says nothing about *what* changed. // // Every store in the process draws from one counter, so a generation // identifies a state of a particular store: tests replace a package-level // store between cases, and a per-store counter would let an index built // from the old store match the new one's generation. It is meaningless // across processes. Generation() uint64 }
Store is a typed key-value store: MemoryStore keeps it in memory and SQLiteStore persists it.
func Announcing ¶
Announcing returns store with every write announced to changes under the id it wrote, so a waiter on a resource sleeps until something about it changed and then reads it through the service's API, as the service's own clients do, instead of reading the store on a timer. A Prune names no ids and wakes every waiter.
func MakeCachedStore ¶
MakeCachedStore is MakeStore for a store whose reads must not each cost a SQLite query (see CachedSQLiteStore). With a database it keeps every row in memory and writes through; without one it is the MemoryStore MakeStore returns. Like MakeStore, a table SQLite rejects is a startup error.
func MakeStore ¶
MakeStore returns a SQLiteStore when db is set and a MemoryStore otherwise. A table SQLite refuses to create exits the process through log.Fatalf rather than dropping that one table back to memory while its neighbours stay durable; every caller runs at registration, so this is a startup error that names the table.
type TrackedStore ¶
type TrackedStore struct {
// Table is the store's table name, which is unique per simulator build.
Table string
// Remap rewrites every stored key with rekey and every string reachable
// from every stored value with edit, writing back only the rows one of
// them changed.
Remap func(rekey func(string) string, edit func(string) string)
}
TrackedStore is one store MakeStore created, exposed for a cross-cutting pass.
func TrackedStores ¶
func TrackedStores() []TrackedStore
TrackedStores returns a snapshot of the stores created since the last reset.
type Wildcard ¶
type Wildcard struct {
// AnyOne makes '?' match any one character; otherwise '?' is literal.
AnyOne bool
// Escapes are the characters a backslash before them makes literal; a
// backslash before any other character is itself literal.
Escapes string
// FoldCase matches letters regardless of case.
FoldCase bool
}
Wildcard is a pattern syntax of literal characters and '*', which matches any run of characters, none included — the wildcard IAM policies, load balancer rules, Azure role actions and event filters share. Its fields add the parts of a syntax that are a cloud's own.
Source Files
¶
- announcing.go
- call.go
- cloudnet.go
- config.go
- console_bundle.go
- container.go
- container_memory.go
- container_reaper.go
- datadir.go
- db.go
- db_checkpoint.go
- diagnostics.go
- diagnostics_stores.go
- docker_config.go
- enginebuild.go
- enginebuild_lock_unix.go
- errors.go
- ids.go
- index.go
- keyed_locks.go
- middleware.go
- migrate.go
- oci.go
- oci_pull.go
- ociauth.go
- ordered_ids.go
- otel.go
- parent.go
- parent_linux.go
- parsecore.go
- payloads.go
- process.go
- process_unix.go
- program.go
- registry_credential.go
- router.go
- runtime_mode.go
- safeparse.go
- sandbox.go
- server.go
- sidecar_source.go
- sidecar_trust.go
- specvalidate.go
- state.go
- state_cached.go
- state_prune.go
- state_sqlite.go
- store_scan.go
- volume_snapshot.go
- wildcard.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package archive unpacks the ZIP and tar archives clients upload — function deployment packages, build contexts, site deployments — without letting an entry write outside the destination or expand past a size bound.
|
Package archive unpacks the ZIP and tar archives clients upload — function deployment packages, build contexts, site deployments — without letting an entry write outside the destination or expand past a size bound. |
|
Package bg counts the work a simulator runs after the request that asked for it has returned, so a test can drain that work before it replaces the package-level stores the work reads.
|
Package bg counts the work a simulator runs after the request that asked for it has returned, so a test can drain that work before it replaces the package-level stores the work reads. |
|
Package cacheengine runs the data plane of a managed in-memory cache: real Redis-protocol engines (Redis OSS, or Valkey through the same command names) and Memcached engines, one workload per node on a placement backend, behind endpoint listeners the simulator owns.
|
Package cacheengine runs the data plane of a managed in-memory cache: real Redis-protocol engines (Redis OSS, or Valkey through the same command names) and Memcached engines, one workload per node on a placement backend, behind endpoint listeners the simulator owns. |
|
Package cron parses the cron expressions the clouds accept and computes their occurrences in a time zone, and fires persisted schedules from a server's background loop (see Ticker).
|
Package cron parses the cron expressions the clouds accept and computes their occurrences in a time zone, and fires persisted schedules from a server's background loop (see Ticker). |
|
Package dbengine runs the data plane of a managed relational database: a real PostgreSQL, MySQL or MariaDB engine in a container whose data directory is a named volume, behind an endpoint listener the simulator owns.
|
Package dbengine runs the data plane of a managed relational database: a real PostgreSQL, MySQL or MariaDB engine in a container whose data directory is a named volume, behind an endpoint listener the simulator owns. |
|
mysqlwire
Package mysqlwire speaks the connection phase of the MySQL client/server protocol a managed-database endpoint owns.
|
Package mysqlwire speaks the connection phase of the MySQL client/server protocol a managed-database endpoint owns. |
|
pgwire
Package pgwire speaks the front half of the PostgreSQL frontend/backend protocol a managed-database endpoint owns: the startup packet, the SSLRequest upgrade, a cleartext-password exchange, and ErrorResponse refusals.
|
Package pgwire speaks the front half of the PostgreSQL frontend/backend protocol a managed-database endpoint owns: the startup packet, the SSLRequest upgrade, a cleartext-password exchange, and ErrorResponse refusals. |
|
Package delivery runs the at-least-once push deliveries the clouds make on a caller's behalf — an asynchronous function invocation, a webhook POST, a rule target — with the retry policy, event age limit and dead-letter hand-off each cloud documents.
|
Package delivery runs the at-least-once push deliveries the clouds make on a caller's behalf — an asynchronous function invocation, a webhook POST, a rule target — with the retry policy, event age limit and dead-letter hand-off each cloud documents. |
|
Package dnsserver is the DNS listener each simulator answers its zones on.
|
Package dnsserver is the DNS listener each simulator answers its zones on. |
|
Package eventbus fans an event out to the subscriptions that match it: an Amazon EventBridge rule's targets, an Amazon SNS topic's subscriptions, an Azure Event Grid topic's event subscriptions, a Pub/Sub topic's subscriptions, the Eventarc triggers an audit entry reaches.
|
Package eventbus fans an event out to the subscriptions that match it: an Amazon EventBridge rule's targets, an Amazon SNS topic's subscriptions, an Azure Event Grid topic's event subscriptions, a Pub/Sub topic's subscriptions, the Eventarc triggers an audit entry reaches. |
|
Package fileshare serves host directories to guests over NFSv4.0 (RFC 7530): what a bind mount gives a container, a guest mounts over its network from the simulator that holds the directory.
|
Package fileshare serves host directories to guests over NFSv4.0 (RFC 7530): what a bind mount gives a container, a guest mounts over its network from the simulator that holds the directory. |
|
Package funcrt runs a function's invocations on execution environments: the mechanism behind AWS Lambda's execution environments and the Azure Functions host an App Service site runs.
|
Package funcrt runs a function's invocations on execution environments: the mechanism behind AWS Lambda's execution environments and the Azure Functions host an App Service site runs. |
|
Package jobrun runs an execution of tasks to completion: the mechanism behind a Cloud Run job execution's tasks and an Azure Container Apps job execution's replicas.
|
Package jobrun runs an execution of tasks to completion: the mechanism behind a Cloud Run job execution's tasks and an Azure Container Apps job execution's replicas. |
|
Package kvstore holds the primitives the simulators' key-value and document stores share: provisioned-throughput token buckets, per-key read-write locks, the background expiry sweep, a change log, and entity-tag preconditions.
|
Package kvstore holds the primitives the simulators' key-value and document stores share: provisioned-throughput token buckets, per-key read-write locks, the background expiry sweep, a change log, and entity-tag preconditions. |
|
Package listenfds takes the listening sockets a process inherits through systemd's socket-activation protocol (sd_listen_fds(3)): LISTEN_PID names the process, LISTEN_FDS counts the sockets, and they start at file descriptor 3.
|
Package listenfds takes the listening sockets a process inherits through systemd's socket-activation protocol (sd_listen_fds(3)): LISTEN_PID names the process, LISTEN_FDS counts the sockets, and they start at file descriptor 3. |
|
Package listq holds the cloud-neutral plumbing behind list operations: offset and key-cursor pagination, a filter expression tree evaluated over a resource's JSON form, field lookup, and ordering.
|
Package listq holds the cloud-neutral plumbing behind list operations: offset and key-cursor pagination, a filter expression tree evaluated over a resource's JSON form, field lookup, and ordering. |
|
Package logstore is the log entry store the simulators' logging services share: Amazon CloudWatch Logs streams, Cloud Logging logs and Azure Monitor tables.
|
Package logstore is the log entry store the simulators' logging services share: Amazon CloudWatch Logs streams, Cloud Logging logs and Azure Monitor tables. |
|
Package machine runs the lifecycle of a cloud's virtual machines on a placement backend: boot a machine and wait until its init is ready, watch it for an exit of its own, stop it keeping its root disk, start that disk again, discard it, take a running or kept machine over after the simulator restarts, capture its disk as an image and read its console.
|
Package machine runs the lifecycle of a cloud's virtual machines on a placement backend: boot a machine and wait until its init is ready, watch it for an exit of its own, stop it keeping its root disk, start that disk again, discard it, take a running or kept machine over after the simulator restarts, capture its disk as an image and read its console. |
|
Package msgq is the leased message queue the simulators' queueing services share: Amazon SQS queues, Cloud Pub/Sub subscriptions, Azure Service Bus queues and subscriptions, and Azure Queue Storage queues.
|
Package msgq is the leased message queue the simulators' queueing services share: Amazon SQS queues, Cloud Pub/Sub subscriptions, Azure Service Bus queues and subscriptions, and Azure Queue Storage queues. |
|
Package nodeagent is the client side of the node agent: the container that boots Firecracker microVMs for the services configured onto it, holding the KVM device and the network capability the simulator process never holds.
|
Package nodeagent is the client side of the node agent: the container that boots Firecracker microVMs for the services configured onto it, holding the KVM device and the network capability the simulator process never holds. |
|
cmd/guestinit
command
Command guestinit is the first process of a Firecracker guest the node agent boots.
|
Command guestinit is the first process of a Firecracker guest the node agent boots. |
|
cmd/nodeagent
command
Command nodeagent boots Firecracker microVMs for the simulator that started it.
|
Command nodeagent boots Firecracker microVMs for the simulator that started it. |
|
cmd/nodeagent-image
command
Command nodeagent-image builds the node agent's image on the engine, or finds it held, and prints its name.
|
Command nodeagent-image builds the node agent's image on the engine, or finds it held, and prints its name. |
|
Package oidcfed verifies tokens an external OpenID Connect issuer signed, the step every cloud's workload identity federation takes before it checks the token against its own trust configuration.
|
Package oidcfed verifies tokens an external OpenID Connect issuer signed, the step every cloud's workload identity federation takes before it checks the token against its own trust configuration. |
|
Package placement is the one interface through which a cloud service runs a workload — a container on the engine, or a Firecracker microVM on a node agent — chosen per service in the simulator's own configuration and never by anything a workload or a cloud API client sees.
|
Package placement is the one interface through which a cloud service runs a workload — a container on the engine, or a Firecracker microVM on a node agent — chosen per service in the simulator's own configuration and never by anything a workload or a cloud API client sees. |
|
Package procimage reads a process's memory image out of its /proc entry: its mapping table, the modules that table names, and an ELF core a debugger opens.
|
Package procimage reads a process's memory image out of its /proc entry: its mapping table, the modules that table names, and an ELF core a debugger opens. |
|
Package replicas keeps a count of replicas of one specification running: the instances of a Cloud Run revision or worker pool, the replicas of a Container Apps revision, the tasks of an Amazon ECS service deployment.
|
Package replicas keeps a count of replicas of one specification running: the instances of a Cloud Run revision or worker pool, the replicas of a Container Apps revision, the tasks of an Amazon ECS service deployment. |
|
Package revisions holds what the clouds' revisioned container services share: a revision template's identity by content, and the choice of the revision a request goes to by traffic weight.
|
Package revisions holds what the clouds' revisioned container services share: a revision template's identity by content, and the choice of the revision a request goes to by traffic weight. |
|
Package sidecar runs the container that stands in for a cloud network's fixed addresses from inside the network: the resolver the cloud's DHCP hands out and the metadata endpoints, both forwarded to the simulator.
|
Package sidecar runs the container that stands in for a cloud network's fixed addresses from inside the network: the resolver the cloud's DHCP hands out and the metadata endpoints, both forwarded to the simulator. |
|
cmd/sidecar
command
Command sidecar stands in for a cloud network's fixed addresses from inside the network: it answers DNS at the cloud's resolver address and the metadata endpoints at the address the cloud serves them on, and forwards both to the simulator that started it.
|
Command sidecar stands in for a cloud network's fixed addresses from inside the network: it answers DNS at the cloud's resolver address and the metadata endpoints at the address the cloud serves them on, and forwards both to the simulator that started it. |
|
cmd/sidecar-image
command
Command sidecar-image builds the network sidecar's image on the engine, or finds it held, and prints its name.
|
Command sidecar-image builds the network sidecar's image on the engine, or finds it held, and prints its name. |
|
egress
Package egress is what an egress sidecar and the simulator that started it share: the report the sidecar sends about the connections it carried, and the names its configuration travels under.
|
Package egress is what an egress sidecar and the simulator that started it share: the report the sidecar sends about the connections it carried, and the names its configuration travels under. |
|
gwlb
Package gwlb is what a Gateway Load Balancer node sidecar and the simulator that starts it share: the environment that places the node, and the state it long-polls the simulator for.
|
Package gwlb is what a Gateway Load Balancer node sidecar and the simulator that starts it share: the environment that places the node, and the state it long-polls the simulator for. |
|
Package signals wakes goroutines that wait for something keyed to change: an operation to finish, a queue to gain a message, a record to be written.
|
Package signals wakes goroutines that wait for something keyed to change: an operation to finish, a queue to gain a message, a record to be written. |
|
Package simjwt signs and verifies the JSON Web Tokens a simulator issues as its own identity provider, persists the signing key, and publishes it as a JSON Web Key Set with an OpenID Connect discovery document.
|
Package simjwt signs and verifies the JSON Web Tokens a simulator issues as its own identity provider, persists the signing key, and publishes it as a JSON Web Key Set with an OpenID Connect discovery document. |
|
Package simkms holds the key-material primitives the three simulators share: AES-256-GCM sealing, service-owned keys created on first use, and RFC 5649 key wrapping.
|
Package simkms holds the key-material primitives the three simulators share: AES-256-GCM sealing, service-owned keys created on first use, and RFC 5649 key wrapping. |
|
Package sparse works with files whose unwritten extents are holes: it asks the filesystem which extents hold data, deallocates extents, copies files without allocating their holes, and does the arithmetic of extent sets.
|
Package sparse works with files whose unwritten extents are holes: it asks the filesystem which extents hold data, deallocates extents, copies files without allocating their holes, and does the arithmetic of extent sets. |
|
Package streamlog is the partitioned, append-only record log the simulators' streaming services share: Amazon Kinesis Data Streams shards and Azure Event Hubs partitions.
|
Package streamlog is the partitioned, append-only record log the simulators' streaming services share: Amazon Kinesis Data Streams shards and Azure Event Hubs partitions. |
|
Package vminstance runs a cloud's virtual machine instance — an Amazon EC2 instance, a Compute Engine instance, an Azure virtual machine — on a placement backend.
|
Package vminstance runs a cloud's virtual machine instance — an Amazon EC2 instance, a Compute Engine instance, an Azure virtual machine — on a placement backend. |
|
Package workload holds what every simulator does to launch and reach a workload container: reading the platform off the image, posting to its bootstrap, starting a main container with sidecars in its network namespace, and building images with the host's docker CLI.
|
Package workload holds what every simulator does to launch and reach a workload container: reading the platform off the image, posting to its bootstrap, starting a main container with sidecars in its network namespace, and building images with the host's docker CLI. |
|
Package workloadhost resolves the coordinates a workload container uses to reach the simulator that started it and the machine both run on.
|
Package workloadhost resolves the coordinates a workload container uses to reach the simulator that started it and the machine both run on. |