sim

package module
v0.0.0-...-1614f50 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 74 Imported by: 0

README

sim

The cloud-neutral framework the three simulators are built on:

  • the HTTP server and the startup every binary runs;
  • configuration, and durable state on SQLite;
  • the container-engine layer and the placement backends;
  • cloud networks and their sidecars;
  • the mechanisms services share: queues, fan-out, delivery, jobs, function environments, replica sets, relational engines, object contents and lists;
  • the OCI Distribution data plane, and the bounds-safe parsing primitives.

Each simulator imports it as github.com/e6qu/sockerless-cloud/sim and pins it by pseudo-version (Maintaining → Support-module pins). A cloud's error shape, protocol router, sandbox profile and console coordinates live in that cloud's module and reach the framework through the hooks listed under What stays with the cloud. Architecture shows how the pieces fit together.

Files

File Provides
server.go, console_bundle.go Server: mux registration that records every route pattern for the spec-conformance gates, WrapHandler for host-addressed data planes, RegisterUI with ConsoleOptions and ConsoleBundle for the bundle SIM_CONSOLE_DIR names, background workers drained before SQLite closes, graceful shutdown, TLS
program.go Main and Program: the startup every simulator binary runs — the detached reaper invocation, the parent-process watch, configuration, observability, the cloud's build, the listeners it serves beside the HTTP port, and the HTTP server until a signal, ending the process at the first step that fails
config.go Config read from SIM_* environment variables, including the RewriteRequest hook a cloud uses to map virtual-hosted or case-folded addressing onto the paths the router works in
middleware.go request id, structured request logging (5xx bodies captured), identity extraction from the caller's credential, Flush and Hijack passthrough for streaming and WebSocket handlers
diagnostics.go, diagnostics_stores.go, runtime_mode.go in-flight request registry with slow-request reporting; per-table sizes at /debug/stores; SIM_RUNTIME resolution
state.go, state_sqlite.go, state_cached.go, state_prune.go, migrate.go, db.go, db_checkpoint.go, index.go, ordered_ids.go, store_scan.go Store[T] in memory, on SQLite, or cached in memory over SQLite (the persistence envelope keeps json:"-" fields); PrefixStore[T] and ListPrefix key-range reads over sorted ids; Upsert; Prune for retention sweeps; Migrate runs a named one-time startup conversion per database and LegacyRows reads a table in the row shape an earlier build wrote; write generations and GenerationIndex for keyed lookups; WAL checkpoints; the tracked-store set cross-cutting passes address
keyed_locks.go per-key locks that make a conditional write's check and store one step
signals/, announcing.go change signals: signals.Keyed[K] hands a waiter a channel the next Announce(k) closes (Changed), Any a channel the next announcement of any key closes, AnnounceAll wakes everyone, and Await(ctx, k, ready) re-reads until ready holds — a waiter takes the channel before it reads the state the channel guards; sim.Announcing(store, changes) wraps a Store so every write announces the id it wrote and a Prune wakes every waiter
kvstore/ key-value and document store primitives: Buckets of TokenBuckets for provisioned throughput (Take refuses what the balance cannot cover; Admit and Charge let a request whose cost is known only afterwards run into debt), RWLocks (per-key read-write locks, multi-key calls taken in sorted order, entries reclaimed when released), StartSweeper for time-to-live deletion on Server.StartBackground, and ChangeLog[T] — every create, replace and delete per stream, read after a sequence number, pruned by retention
container.go, container_reaper.go, container_memory.go, sandbox.go, volume_snapshot.go, enginebuild.go the container engine layer: start, adopt, stop and remove workloads, and read back the loopback ports the engine published for them (ContainerHandle.PublishedPort, PublishedHostPort); the detached reaper and startup sweep; memory-peak observation; SandboxProfile enforcement; crash-consistent volume snapshots (SnapshotVolume, CaptureVolume, HoldThawed); SandboxProfile.VolatileRun, a tmpfs /run so each boot of a machine starts with an empty one; EnsureEngineBuild, which builds an embedded source tree into an image on the engine once per engine and source version
cloudnet.go, sidecar_source.go, sidecar_trust.go, call.go cloud networks as engine networks over their own ranges (EnsureCloudNetwork), the platform network and its leased lower half (EnsurePlatformNetwork, LeasePlatformAddress); the sidecar's embedded source and the trust middleware that attributes a sidecar's request to its workload; Server.Call and Caller, an in-process request through the whole chain as a named service principal
datadir.go ScopedDataDir resolves a slice's bulk-data root (override variable, <SIM_DATA_DIR>/<subdir>, temp); EnsureWritableDir makes a bind-mounted directory writable past the umask
workload/ launching and reaching workloads: Place and PlaceMember through a placement backend, StartGroup for a group started in dependsOn order behind startup checks, LocalImagePlatform, PostBootstrap, DockerBuildInvocation and the cancellable DockerCommand for image builds
archive/ ExtractZip, ExtractTar (gzip detected) and ReadZip: every write goes through an os.Root, entry names must stay local, symbolic links are recreated but never written through out of the root, and a size bound caps expansion
oci.go, registry_credential.go, docker_config.go the Docker Registry HTTP API v2 data plane, keyed per registry scope, with the hooks a cloud's registry differs on; the registry credential a workload host pulls with; the Docker configuration and credential helper a build service's steps run with
payloads.go, blobstore/ Server.Payloads opens a blobstore.Payloads store: object contents in files of their own, written once (WriteFrom computes size, MD5 and CRC32C in the same pass), streamed Concat, staged WriteAt for resumable uploads, Materialize for mount mirrors, Adopt/Sweep at startup, and OpenCurrent that follows an overwrite a reader raced; plus RFC 9110 conditional-request evaluation (EvaluateHTTP, ETagListMatches), per-service byte-range grammars with ServeRange, and delimited listing roll-up with combined item/prefix paging (RollUp, PageAfter)
sparse/ sparse files: DataExtents (SEEK_DATA/SEEK_HOLE), PunchHole, Clear, extent-preserving Copy/CopyFile/CopyTree, and extent-set arithmetic (Merge, Subtract, Clip, Diff)
ociauth.go registry authentication primitives: the error envelope with Docker-Distribution-Api-Version, Bearer and Basic challenges, Authorization and Basic-credential parsing, token-scope parsing, and the image-on-this-port check
simjwt/ JWT signing and verification for a simulator acting as its own identity provider: a persisted RSA or P-384 key (LoadOrCreate reads the PKCS#1 / SEC 1 PEM the clouds already persist), Sign, Verify, the JWKS and the OpenID Connect discovery document
oidcfed/ verification of tokens an external OpenID Connect issuer signed: one cached verifier per issuer on a bounded HTTP client and a background context, UnverifiedIssuer, NormalizeIssuer, AudienceIntersects
router.go, errors.go ReadJSON, PathParam, WriteJSON
wildcard.go Wildcard, the one * pattern matcher, with ? (AnyOne), backslash escapes (Escapes) and case folding (FoldCase) as options, behind Elastic Load Balancing rule conditions, IAM policy and condition patterns, Amazon EC2 filter values, Azure RBAC actions, Eventarc path segments and the AWS event pattern wildcard filter
parsecore.go, safeparse.go bounds-safe scanner and frame reader, byte-length-preserving ASCII folding
listq/ list-operation plumbing: offset page windows over a cloud's own token spelling (Tokens, Window, OffsetPage, TokenPage, ErrBadToken), KeyPage, whose token names the last key a page returned so a create or delete between calls skips and repeats nothing, and ColumnPage, its multi-column form, which resumes strictly after the last item's sort values (page-token sort values travel as bytes, so no UTF-8 is lost), with IntKey the integer key spelling that sorts numerically, the filter tree (Node: True, And, Or, Not, Cmp) each cloud's grammar parses into, JSON field lookup and scalar rendering (Lookup, Field, ScalarString), numeric-else-lexical ordering (CompareNumeric, CompareOrdered), and ParseOrderBy / ApplyList / ToDoc for filter-then-sort over any resource type; each cloud maps ErrBadToken and parse errors to its own error shape
msgq/ the leased message queue behind Amazon SQS, Cloud Pub/Sub subscriptions, Cloud Tasks queues, Azure Service Bus entities and Azure Queue Storage: Queue[P] is plain data kept in the owner's Store row and changed inside its Update — Enqueue with delay, time to live, deduplication key and ordering group; Receive leasing in order, blocking an unavailable group, dead-lettering past Policy.MaxDeliveries and expiring past retention; Extend, Settle, Abandon (with Policy.Backoff), Release, DeadLetter, Exhausted, Peek, Remove, Purge, Count; Dedup.Admit, the one duplicate-detection path, which Enqueue takes for a message's key and a topic that deduplicates before fan-out calls itself; Queue.NextChange names the next moment the queue changes by itself (a delay, a lease or a retry backoff ending, an expiry), and Waiter wakes a queue's receivers on the cloud's signal or at that moment — Poll is a long-poll receive, Wait one sleep of a stream, WaitAny the sleep of a loop over many queues, and Arm a self-re-arming timer per queue whose OnDue hook pushes newly available messages to receivers. Each cloud spells its own receipts
streamlog/ the partitioned append-only record log behind Amazon Kinesis Data Streams shards and Azure Event Hubs partitions: one row per record plus a partition head, so Append, Read, Trim (retention), SeekTime, Last and Drop never rewrite a partition, and Import fills an empty partition from another layout keeping sequence numbers and times; HashRanges (MD5 hash-key ranges) and Modulo implement Partitioner
otel.go, parent.go, parent_linux.go, parent_darwin.go, process.go, process_unix.go, process_windows.go, specvalidate.go OpenTelemetry export, exit-with-parent, log sinks and workload results, runtime wire-shape validation
ids.go NewUUID (random version 4) and RandomHex from crypto/rand
workloadhost/ the coordinates a workload container dials back on: CallbackHost/CallbackAddr (container address, Linux bridge gateway, or the desktop runtime's host alias), ListenPort, ExtraHosts and AliasHosts for Docker and Podman, OuterHostEntries, MergeEnv, and MetadataIndex[T] keying a metadata server's instance records by source address
delivery/ at-least-once push delivery: Dispatcher[T] persists each pending delivery with its next attempt time, retries it under a Policy (MaxAttempts, MaxAge, Backoff, MinWait from the failed answer, and BothLimits for a cloud that retries until both limits run out), resumes after a restart (Resume), and hands a delivery that ends without success to the cloud's dead-letter path (Handler.Finish with the Reason); SubmitAttempted makes the first attempt on the caller's goroutine; Deferred(err, wait) retries after wait without spending MaxAttempts, for a throttled delivery, and ends at MaxAge; Post sends a push request (POST unless Request.Method names another) and classifies the answer through a cloud's Classifier; Exponential and Steps backoff shapes. A push that drains a leased queue, such as a Cloud Pub/Sub push subscription or a Cloud Tasks queue, keeps its attempts, backoff and dead-lettering in the msgq queue it shares with pull and uses Post alone
eventbus/ event fan-out: Bus[E, S, P] publishes an event to a source's Subscriptions, filters it through the cloud's Admits dialect, cuts the admitted events into deliveries by Batch Limits (count and bytes), turns each into a payload with Transform (the input transformation), and either hands it to a Sink that owns its own retries — a Pub/Sub subscription's queue — or delivers it through a delivery dispatcher under the subscription's retry policy with Settled and DeadLetter hooks; Archive sees every published event, Replay re-delivers without archiving, DeliverTo addresses subscriptions directly, Submit sends a payload no event caused. Amazon EventBridge, Amazon SNS, Azure Event Grid, Pub/Sub and Eventarc fan out through it
cron/ cron schedules: Parse in the Vixie five-field dialect (0–7 day-of-week, names, the either-day rule when both day fields are restricted) or the AWS six-field dialect (year, ?, L, W, #), bound to a time zone; Schedule.Next skips wall-clock times a daylight-saving jump removes; Ticker fires Entry schedules from Server.StartBackground, persisting each one's next occurrence (Record), collapsing occurrences missed while stopped into the latest, dropping those older than MaxLate, and forgetting schedules that no longer exist
bg/ counted background work a test drains with bg.Await before it rebuilds the stores: Go, JoinedGo, Handoff (work handed to Server.StartBackground), AfterFunc (with Timer.Pending) and WatchThen
dbengine/ the managed relational database data plane: Instance runs a real PostgreSQL, MySQL or MariaDB engine (Postgres16, MySQL80, MariaDB114) on a named volume behind an endpoint the simulator owns — start on first client, adopt after restart, readiness classified the way pg_isready does, Exec, Stop that returns once the volume is free; ListenLoopback keeps the advertised port or fails; SelfSignedCertificate; SQL and shell quoting
cacheengine/ the managed cache data plane: Plane runs real Valkey or Redis nodes on placement.Backend, as an instance with replicas following a primary or as a Redis Cluster whose nodes announce their own endpoints, with failover, resharding, reboot, restart and adoption, RDB snapshots and import, ACL users, and TLS required, preferred or off per endpoint; Memcached runs independent nodes behind per-node and discovery endpoints; a RESP client (Dial, Conn.Do, Pipeline, KeySlot). Each cloud supplies its images, network, credentials and token exchange through Config hooks
logstore/ log entries by scope (a log stream, a log, a table): one row per entry keyed by scope and arrival sequence plus a scope head, so Append, Entries, Expire (retention by the entry's own time, leaving gaps reads step over), Cap, Edit (rewrite or delete entries in place), Drop and DropPrefix never rewrite a scope; Open lists a scope before its first write and Import fills an empty scope from another layout
simkms/ key material: AES-256-GCM Seal/Open (nonce followed by the sealed bytes, which every cloud's ciphertext framing ends with) and SealWithNonce/OpenWithNonce for raw-encryption APIs that return the IV; NewKey; EnsureKey, which creates a service-owned key on first use inside the store's Upsert over any row shape; RFC 5649 WrapWithPadding/UnwrapWithPadding. Each cloud keeps its ciphertext framing, key versions and key API
listenfds/ the listening sockets a process inherits through systemd's socket-activation protocol (LISTEN_PID, LISTEN_FDS): Listen, ListenTCP and ListenUDP take the inherited socket bound to the port they are asked for, or bind it
dnsserver/ the DNS listener each simulator answers its zones on: one port on UDP and TCP, a Catalog hook that returns the zones and names a query can see — given the address it came from and the address it arrived at, which names a workload network — and everything that is DNS rather than cloud: longest-zone matching, RFC 4592 wildcards, CNAME chains across zones, delegations with glue, NXDOMAIN versus NODATA with the zone's SOA, EDNS0 and truncation on UDP, forwarding zones, and recursion through upstreams for names outside every zone
placement/ the one interface through which a service places a workload — Place, PlaceMember, Adopt, Restart, Remove, Find, Console and Capture, and a Handle with wait, stop, exec, address, published port, ingress and gateway control — with the container backend and the microVM backend, chosen per service by SIM_PLACEMENT
nodeagent/ the node agent's client, its program (cmd/nodeagent) and the guest's first process (guestinit): Firecracker guests from OCI-built root filesystems, members on disk slots, tap filtering, file shares and extra interfaces
machine/ the virtual machine lifecycle on a placement backend — boot to ready, watch, stop keeping the disk, start, discard, adopt, capture, console — with each cloud's states as hooks
vminstance/ VM instances from a cloud's image catalog with the seeded init that runs the image's cloud-init over the user data
replicas/, revisions/ a replica set kept at its count with restarts, back-off, adoption and a pick for front ends; Probe and Probes, the container probe runner with the kubelet's semantics (initial delay from container start, period from attempt start to attempt start, per-attempt timeout, failure and success thresholds; the startup probe first, then liveness restarting on failure and readiness gating ready); CrashLoopBackoff and CrashLoopSettled, the kubelet's crash-loop back-off; revision identity by template content and the choice of a revision by traffic weight
jobrun/ run to completion: an execution of N tasks, at most Parallelism at once, lowest index first; each task runs as attempts, retried up to MaxRetries while the cloud's Retry hook agrees, each bounded by AttemptTimeout and the task by TaskTimeout (never retried); a Policy (AllSucceed, Completions(n)) turns counts into a verdict, after which pending tasks never start and running ones stop; Cancel; Resume takes back recorded tasks after a restart and adopts running workloads through Hooks.Adopt, a lost one ending as a failed attempt. The cloud starts attempts (Hooks.Start) and records every change (Hooks.Changed, Hooks.Finished) in its own store
funcrt/ function execution environments: Pool leases an idle initialised environment or starts another through Hooks.Start (Options.PerEnvironment invocations at once), Release reuses it and Discard resets it; a Limit shared by pools caps invocations in flight (ThrottledError), a bounded limit owning its capacity and an unbounded one counting against its parent; Provision keeps environments initialised ahead of invocations, serving once all are ready (Provisioning); Retire drains a pool; Hooks.Expires retires an environment past its time; Pollers runs one event-source poller per key, with the cloud's Source (keys, key changes, wake channels, poll) as hooks
sidecar/ the network sidecar program: the resolver and metadata forwarder at the cloud's reserved address, the NAT egress proxy, the container-credentials forwarder, file shares and process reads
fileshare/ an NFSv4.0 server over host directories, the bind mounts of guests
lbplane/ the load-balancer and front-end data plane: listeners, TLS, forwarding with Upstream timeouts and header builders, health probes and admission hooks; HostRouter, the front end of every service that serves a workload on a hostname of its own (it normalises the Host with Hostname, claims only hostnames under its Domains, asks the cloud's Route hook for the handler, and answers a claimed name that names nothing with the cloud's NotFound page); Serve, the forward with a front end's own answers (499 for a client gone, a cut stream for a target lost mid-answer marked ErrAnswerStarted, and the cloud's Answers for a forward that got nothing), with AbortStarted, CloseWithoutAnswer and ClientProto; ProbeHTTP (headers, TLS server name, separate connect and response timeouts, a fresh proxy-free connection per check), ProbeTCP and ProbeGRPC (grpc.health.v1)
ipam/, netrules/ address ledgers and the parsers of security group, firewall and network security group rules
procimage/ a process's mapping table and an ELF core read from /proc
dbengine/pgwire/, dbengine/mysqlwire/ the front half of each wire protocol: startup and SSLRequest upgrade, cleartext-password exchange and FATAL 28P01 refusal; the MySQL connection phase with mysql_clear_password on the front and a native or caching_sha2_password login to the engine

What stays with the cloud

  • Error shapes — AWSError, S3ErrorXML, GCPError, AzureError are defined in the simulator that speaks that protocol.
  • Protocol routers — the AWS JSON (X-Amz-Target) and AWS Query (Action/Version) routers live in simulator-aws; Google Cloud and Azure register on the server mux directly.
  • Sandbox profiles — SandboxLambda, SandboxFargate, SandboxCloudRun, SandboxACA and their aliases are each cloud's documented workload restrictions; the framework enforces whatever profile it is handed.
  • Registry behaviour — OCIRegistry hooks: Authorize, AdmitRepository, Scope, BaseResponse, RefuseChunkedUpload, OnManifestPut, HydrateManifest.
  • Console coordinates — ConsoleOptions.Coordinates fills GET /ui/config.json; BrowserFederationCoordinates serves the consoles that federate from the browser, and Azure's server-side Entra broker registers through ConsoleOptions.AuthRoutes.
  • Database credentials — dbengine.Instance hooks: Environment, Ready, Authenticate, RefusePlaintext, BackendLogin; each cloud keeps its credential store and the row its sealing key lives in, and seals through simkms.
  • DNS visibility — which zones a query sees (Route 53 private zones by VPC, Azure Private DNS by virtual network link, Cloud DNS private zones by network) and each cloud's record shapes reach dnsserver through its Catalog.
  • Path rewriting — Amazon S3's zonal virtual-hosted addressing and Azure Resource Manager's case folding are Config.RewriteRequest hooks.

Configuration

ConfigFromEnv(provider, defaultPort) reads the SIM_* variables that docs/configuration.md lists.

Usage

func main() {
    sim.Main(sim.Program{
        Provider:    "aws",
        DefaultPort: "4566",
        Build: func(cfg sim.Config) (*sim.Server, error) {
            srv, err := sim.NewServer(cfg)
            if err != nil {
                return nil, err
            }
            srv.HandleFunc("GET /2015-03-31/functions", listFunctions)
            return srv, nil
        },
    })
}

Configure checks or records the resolved configuration before the build, and Start starts what serves beside the HTTP port (a gRPC or DNS listener), returning the stop that runs once the HTTP server has shut down.

Testing

Command Runs
make -C sim test The module's own tests, which start real containers for the reaper, the startup sweep, the memory observer and the cloud networks
make -C sim race-test The same tests under the race detector
make node-agent-test A Firecracker guest booted through the node agent, on a host with /dev/kvm

Every simulator's SDK, CLI and Terraform suite exercises the framework too.

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

View Source
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.

View Source
const DockerIdentityTokenUsername = "<token>"

DockerIdentityTokenUsername is the username under which the Docker client treats a stored secret as an identity token.

View Source
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
View Source
const NoGateway = "none"

NoGateway is the Gateway of a workload with no default route: one whose subnet's routing names no way out.

View Source
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.

View Source
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

View Source
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.

View Source
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.

View Source
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.

View Source
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

func ASCIIFold(s string) string

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

func ASCIIFoldUpper(s string) string

ASCIIFoldUpper uppercases ONLY ASCII a–z and is byte-length preserving.

func ArchiveVolume

func ArchiveVolume(ctx context.Context, volume string) (io.ReadCloser, error)

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

func AuthPassthroughMiddleware(provider string) func(http.Handler) http.Handler

Extract the caller identity without validating credentials, and accept a request that carries no auth headers at all.

func BasicChallenge

func BasicChallenge(realm, service string) string

BasicChallenge renders the `WWW-Authenticate` value of a registry that takes HTTP Basic credentials directly.

func BasicCredential

func BasicCredential(encoded string) (username, password string, ok bool)

BasicCredential decodes the base64 `user:password` of an HTTP Basic credential.

func BearerChallenge

func BearerChallenge(realm, service, scope, errCode string) string

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

func BrowserFederationCoordinates(bool) map[string]string

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

func CaptureVolume(ctx context.Context, src, dst, tag string) error

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

func CaseInsensitiveIndex(s, sub string) int

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

func CaseInsensitiveLastIndex(s, sub string) int

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

func CloseDB(db *sql.DB) error

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

func CommitContainer(ctx context.Context, containerID, reference string) (string, error)

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

func ConnectContainerToNetwork(containerName, networkName string, aliases []string) error

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

func ConsoleBundle(dir string) (fs.FS, error)

ConsoleBundle opens the built console bundle in dir, whose index.html sits at its root.

func ContainerEnvironment

func ContainerEnvironment(ctx context.Context, containerID string) (map[string]string, error)

func ContainerIPv4On

func ContainerIPv4On(ctx context.Context, containerID, network string) netip.Addr

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

func DeclareOpenEndedWait(ctx context.Context)

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

func DeclareWait(ctx context.Context, d time.Duration)

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

func DeclaredWait(ctx context.Context) (wait time.Duration, openEnded bool)

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

func DefaultContainerNetworkGatewayIPv4() (string, error)

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

func DetachCommand(command *exec.Cmd)

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

func DisconnectContainerFromNetwork(ctx context.Context, containerID, networkName string) error

DisconnectContainerFromNetwork takes a container off an engine network it joined; a network the engine no longer has is nothing to leave.

func DockerClient

func DockerClient() *client.Client

DockerClient returns the shared Docker client InitDocker set.

func DockerConfigEnv

func DockerConfigEnv(configDir string) []string

DockerConfigEnv is the environment that points a docker invocation at the configuration WriteDockerConfig wrote.

func EngineGoArch

func EngineGoArch(engineArch string) (string, error)

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

func EnsureDockerNetwork(name string) (string, error)

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

func EnsureWritableDir(dir string) error

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 EnvOr

func EnvOr(key, fallback string) string

EnvOr reads an environment variable, or fallback when it is unset or empty.

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

func HoldThawed(ctx context.Context, containerID string) (release func(), err error)

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

func ImageOnPort(image string, port int) bool

ImageOnPort reports whether an image reference's registry host carries port, the one coordinate a relocated registry keeps.

func InFlightMiddleware

func InFlightMiddleware(next http.Handler) http.Handler

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 InProcess

func InProcess(r *http.Request) bool

InProcess reports whether a request is one Call is serving.

func InitDocker

func InitDocker(provider string, preserveWorkloads bool, stateDir string) (*client.Client, error)

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

func LegacyRows[T any](db *sql.DB, table string) (*SQLiteStore[T], []Keyed[T], error)

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

func LifetimeContext(ctx context.Context) context.Context

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 LoggingMiddleware(logger zerolog.Logger, provider string) func(http.Handler) http.Handler

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

func Migrate(db *sql.DB, name string, fn func() error) error

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

func MissingNetfilterTableHint(err error) string

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 NewSidecarToken

func NewSidecarToken() string

NewSidecarToken mints a token for one sidecar.

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

func OpenDB(dataDir string) (*sql.DB, error)

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

func OwnershipLabels(extra map[string]string) map[string]string

OwnershipLabels are the labels that mark a workload as this simulator's, its persistent state among them, with extra merged in.

func ParseAuthorization

func ParseAuthorization(header string) (scheme, credential string)

ParseAuthorization splits an Authorization header into its scheme and credential. Compare the scheme case-insensitively (RFC 9110 §11.1).

func PathParam

func PathParam(r *http.Request, name string) string

func PathPrefixes

func PathPrefixes(id string) []string

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

func ProcessAlive(pid int) bool

ProcessAlive reports whether pid still identifies a running process.

func PublishedHostPort

func PublishedHostPort(ctx context.Context, containerID string, containerPort int) (int, error)

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

func PullImage(ctx context.Context, imageName, platform string) error

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

func PullImageOn(ctx context.Context, cli *client.Client, imageName, platform string) error

PullImageOn pulls like PullImage through the engine cli rather than the simulator runtime's own.

func PullImageWithCredential

func PullImageWithCredential(ctx context.Context, imageName, platform, registryAuth string) error

PullImageWithCredential pulls like PullImage, presenting registryAuth (the engine API's X-Registry-Auth value) to the image's registry.

func RandomHex

func RandomHex(n int) string

RandomHex returns n lowercase hexadecimal characters drawn from crypto/rand.

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

func ReadJSON(r *http.Request, v any) error

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

func RegistryCredential(username, password string) string

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

func RegistryIdentityToken(token string) string

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

func RemoveContainer(containerID string) error

RemoveContainer removes a container the simulator kept, running or not, with the anonymous volumes its image declared.

func RemoveDockerNetwork

func RemoveDockerNetwork(name string) error

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

func RemoveDockerNetworkContext(ctx context.Context, name string) error

RemoveDockerNetworkContext is RemoveDockerNetwork waiting for the last container to disconnect for as long as ctx allows.

func RemoveExistingContainer

func RemoveExistingContainer(containerID string) error

RemoveExistingContainer stops and removes a workload whose owning control-plane process can no longer drive it.

func RemoveVolume

func RemoveVolume(name string) error

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

func RemoveVolumesNamed(prefix string) error

RemoveVolumesNamed removes every simulator-managed volume whose name starts with prefix: a workload's own volumes once it is gone.

func RequestID

func RequestID(ctx context.Context) string

func RequestIDMiddleware

func RequestIDMiddleware(provider string) func(http.Handler) http.Handler

func RequireContainerRuntime

func RequireContainerRuntime(operation string) error

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

func ResolveLocalImage(image string) string

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

func ScopedDataDir(overrideEnv, subdir, tempName string) string

ScopedDataDir resolves the host directory a service slice keeps its bulk data in — file-share trees, bucket payloads, volume images, build caches:

  1. the directory overrideEnv names, when overrideEnv is non-empty and set;
  2. <SIM_DATA_DIR>/<subdir>, so the data survives a restart beside the SQLite state the same directory holds;
  3. <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

func SidecarNetwork(ctx context.Context) string

SidecarNetwork is the engine network whose sidecar forwarded the request, or "" when it came from anywhere else.

func SidecarTrust

func SidecarTrust(next http.Handler) http.Handler

SidecarTrust is the middleware that reads the pair: a server applies it to everything it routes.

func SnapshotVolume

func SnapshotVolume(ctx context.Context, src, dst string) (filesystem string, err error)

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

func StartExistingContainer(containerID string) error

StartExistingContainer resumes an exited persistent workload container without replacing it, preserving its filesystem, mounts, identity, and port bindings.

func StopAndRemoveContainer

func StopAndRemoveContainer(containerID string, grace time.Duration)

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

func StopContainer(containerID string, grace time.Duration)

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

func VolumeExists(name string) bool

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

func VolumeSnapshotIsInstant(filesystem string) bool

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

func WaitContainerRemoved(containerID string, timeout time.Duration) error

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

func WithCaller(ctx context.Context, caller Caller) context.Context

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.

func WriteJSON

func WriteJSON(w http.ResponseWriter, statusCode int, v any)

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

func NewCachedSQLiteStore[T any](db *sql.DB, table string) (*CachedSQLiteStore[T], error)

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) Write

func (c *CallResponse) Write(b []byte) (int, error)

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.

func CallerOf

func CallerOf(ctx context.Context) (Caller, bool)

CallerOf returns the service principal an in-process call is made as.

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

func ConfigFromEnv(provider, defaultPort string) Config

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

func (h *ContainerHandle) PublishedPort(ctx context.Context, containerPort int) (int, error)

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

type DockerCredential struct {
	Username string
	Secret   string
}

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.

func (*FrameReader) Take

func (r *FrameReader) Take(n int) ([]byte, error)

Take returns the next n bytes (a sub-slice of the backing buffer — do not mutate). A negative or over-long n yields io.ErrUnexpectedEOF.

type FuncSink

type FuncSink func(LogLine)

FuncSink wraps a function as a LogSink.

func (FuncSink) WriteLog

func (f FuncSink) WriteLog(line LogLine)

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 HostEntry

type HostEntry struct {
	IP   string
	Name string
}

type Keyed

type Keyed[T any] struct {
	ID   string
	Item T
}

Keyed is one item of a ListPrefix result, under the id it is stored at.

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 LogLine

type LogLine struct {
	Stream    string // "stdout" or "stderr"
	Text      string
	Timestamp time.Time
}

LogLine is a single line of captured output.

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

type NetworkAttachment struct {
	Network     string
	IPv4Address string
}

NetworkAttachment is a further network a workload joins at an address.

type NoopSink

type NoopSink struct{}

NoopSink discards all log output.

func (NoopSink) WriteLog

func (NoopSink) WriteLog(LogLine)

type OCIBlob

type OCIBlob struct {
	Scope       string
	Digest      string
	ContentType string
	Data        []byte
}

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

type OCIPulledBlob struct {
	Digest      string
	ContentType string
	Data        []byte
}

OCIPulledBlob is one blob a pull fetched.

type OCIPulledManifest

type OCIPulledManifest struct {
	Digest      string
	ContentType string
	Data        []byte
}

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

type OCIUpload struct {
	Scope string
	UUID  string
	Repo  string
	Data  []byte
}

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.

func (*OTelLogWriter) Write

func (w *OTelLogWriter) Write(p []byte) (int, error)

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

type ProcessResult struct {
	ExitCode  int
	StartedAt time.Time
	StoppedAt time.Time
	Error     error
}

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 Route

type Route struct {
	Destination netip.Prefix
	Via         netip.Addr
}

Route sends what a workload addresses to Destination through Via.

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

func NewSQLiteStore[T any](db *sql.DB, table string) (*SQLiteStore[T], error)

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

func NewScanner(s string) *Scanner

func (*Scanner) Eof

func (sc *Scanner) Eof() bool

Eof reports whether the cursor is at or past the end.

func (*Scanner) Len

func (sc *Scanner) Len() int

func (*Scanner) Next

func (sc *Scanner) Next() byte

Next returns the current byte and advances, or 0 at EOF (cursor unchanged).

func (*Scanner) Peek

func (sc *Scanner) Peek() byte

Peek returns the current byte without advancing, or 0 at EOF.

func (*Scanner) PeekAt

func (sc *Scanner) PeekAt(n int) byte

PeekAt returns the byte at offset n from the cursor, or 0 if out of range.

func (*Scanner) Pos

func (sc *Scanner) Pos() int

Pos and Len report the cursor position and the input length.

func (*Scanner) Slice

func (sc *Scanner) Slice(start, end int) string

Slice returns s[start:end] with both bounds clamped into range; an inverted range yields "".

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

func NewServer(cfg Config) (*Server, error)

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

func (s *Server) CallbackListenAddr() string

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) DB

func (s *Server) DB() *sql.DB

DB returns the SQLite database connection, or nil if persistence is disabled.

func (*Server) Handle

func (s *Server) Handle(pattern string, handler http.Handler)

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

func (s *Server) Listen() error

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

func (s *Server) ListenAndServe() error

ListenAndServe binds the listeners and serves until shutdown.

func (*Server) Logger

func (s *Server) Logger() zerolog.Logger

Logger returns the server's logger for use by service handlers.

func (*Server) Mux

func (s *Server) Mux() *http.ServeMux

Mux returns the underlying ServeMux for direct registration.

func (*Server) OnStop

func (s *Server) OnStop(stop func(context.Context) error)

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

func (s *Server) Payloads(name string) (*blobstore.Payloads, error)

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

func (s *Server) RequestContext(parent context.Context) context.Context

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

func (s *Server) RoutePatterns() []string

RoutePatterns returns every pattern registered through Handle / HandleFunc, in registration order.

func (*Server) Serve

func (s *Server) Serve() error

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

func (s *Server) ServeUIRoot(w http.ResponseWriter, r *http.Request) bool

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

func (s *Server) StartBackground(name string, worker func(context.Context))

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.

func (*Server) UIAuth

func (s *Server) UIAuth() *uiauth.Auth

UIAuth is the console's OpenID Connect session layer, for a console auth-layer route that reads the operator's session itself.

func (*Server) WrapHandler

func (s *Server) WrapHandler(middleware func(http.Handler) http.Handler)

WrapHandler wraps the server's final handler chain. Host-addressed cloud data planes use this to route before generic path handlers.

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

func Announcing[T any](store Store[T], changes *signals.Keyed[string]) Store[T]

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

func MakeCachedStore[T any](db *sql.DB, table string) Store[T]

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

func MakeStore[T any](db *sql.DB, table string) Store[T]

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.

func (Wildcard) Match

func (w Wildcard) Match(pattern, s string) bool

Match reports whether all of s matches pattern.

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.

Jump to

Keyboard shortcuts

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