Module container_net 

Shared container-to-host networking resolution for service runtimes that spawn sibling containers (Lambda, ECS, RDS, ElastiCache).

Captures the issue #1539 fix shape in one place so the four runtimes that shell out to docker/podman can’t drift apart again:

• podman ships host.containers.internal as a built-in container DNS entry on every platform and must NOT receive --add-host host.docker.internal:host-gateway — rootless podman’s gvproxy leaves the magic alias empty and the create fails with “host containers internal IP address is empty”.
• bare docker on Linux has no host-gateway magic; the bridge gateway IP has to be resolved from the daemon and injected explicitly.
• Docker Desktop on Mac/Windows resolves the host-gateway magic value to the host’s IP.
• when fakecloud itself runs in a container (FAKECLOUD_IN_CONTAINER=1, baked into the published image), the sibling containers it spawns publish their ports on the host’s daemon — reachable from inside fakecloud’s container as host.docker.internal:<port>, not 127.0.0.1:<port>.

Structs

HostNetworking

Resolved container-to-host networking for a given CLI. Built once at runtime construction and reused for every container spawn.

Constants

CLI_PROBE_TIMEOUT

How long to wait for <cli> info before giving up and treating the runtime as unavailable. A healthy daemon answers in well under a second; an unreachable or wedged daemon (stale DOCKER_HOST, Docker Desktop mid start, a broken socket) can leave the CLI blocked on connect forever, which would hang fakecloud startup and the test harness. Bounding the probe turns “daemon wedged” into “no runtime detected” instead of a hang.

CONTAINER_RUNTIME_HINT

Actionable remediation appended to every error raised when a container runtime (Docker/Podman) is required for an operation but none is available. Kept in one place so RDS, Lambda, ECS, and the server startup banner all surface the same fix steps and can’t drift apart.

HOST_ALIAS_RESOLVE_TIMEOUT

How long to wait for the blocking getaddrinfo in [host_alias_resolves] before giving up and returning false. getaddrinfo has no timeout of its own, and a slow or unreachable DNS server would otherwise block a runtime thread at startup (this runs inside runtime constructors under #[tokio::main]). Bounding it — same tradeoff as CLI_PROBE_TIMEOUT — turns “DNS wedged” into “alias doesn’t resolve”, the safe default that keeps the --add-host bridge mapping.

Functions

bounded_output

Run a container-CLI command and return its stdout, or None when it fails or outruns CLI_PROBE_TIMEOUT.

bounded_status

Run a container-CLI command for its effect only, bounded the same way. Returns whether it succeeded.

cli_available

True when the CLI responds to <cli> info with success within CLI_PROBE_TIMEOUT — the same liveness probe every runtime used before this module existed, but bounded so an unreachable daemon can’t hang the caller indefinitely (the CLI blocks on connect with no timeout of its own), and memoized per process so a dozen runtimes probing at startup don’t each pay that bound.

detect_bridge_gateway

Detect the Docker bridge gateway IP on Linux. Returns None if detection fails (caller falls back to the conventional 172.17.0.1).

detect_container_cli

Auto-detect an available container CLI. Honors FAKECLOUD_CONTAINER_CLI as an explicit override (returns None if the override doesn’t work), otherwise prefers docker then podman. Returns None when neither is usable.

is_podman_binary

True when cli is podman or a podman-compatible binary. Matches on the filename component so absolute paths (/opt/homebrew/bin/podman) and wrappers (podman-remote) both register as podman. Docker Desktop’s compatibility CLI is named docker, so this check is safe.

owned_by_dead_process

Whether a container or network labelled fakecloud-instance=<label> was left behind by a fakecloud process that is gone. The label is fakecloud-<pid>; an object is orphaned only when that PID is neither the current process nor alive. Several fakecloud processes can share one daemon (parallel test servers, side-by-side installs), so an object owned by another live process is never an orphan. A label that doesn’t parse is not treated as an orphan either – nothing proves its owner is gone.

pid_alive

True if the given PID is a live process on this host.

registry_auth_hosts

Hostnames fakecloud’s bundled ECR/OCI registry can be addressed from a sibling container or the host, each at server_port.

resolve_host_alias

Compute the (host_alias, add_host_arg) pair for a CLI. Pure except for the bridge-gateway daemon probe on Linux docker, so the macOS / podman branches are unit-testable without a daemon.

resolve_sibling_host

Decide what address fakecloud uses to reach the sibling containers it just spawned. Pure helper so the env-var parsing can be tested without touching the process’s real environment.