Documentation
¶
Overview ¶
Package hostpin pins the hosts a proxy may reach to the addresses this machine resolves for them, as --add-host entries for the proxy's /etc/hosts. A proxy dials from inside its container, where names go to the engine's DNS: on Docker the embedded server (127.0.0.11), which knows no search domain, no mDNS and no split DNS of the host; on rootless podman, a container on an internal network and the default one is told only the internal network's name server, which answers no outside name at all. A pin changes where an allowed name points, never what the proxy may reach: its allowlist is still enforced by name.
Index ¶
Constants ¶
const HostGateway = "host-gateway"
HostGateway is the address an --add-host entry gives a name that means this computer. Docker and podman put the address a container reaches the engine's host at in its place; on Docker Desktop that address also reaches services the host has bound to its loopback.
const LookupTimeout = 2 * time.Second
LookupTimeout bounds each lookup: a name the host cannot resolve quickly is left to the container's DNS.
const LoopbackAlias = "agentry-host.internal"
LoopbackAlias is the name a plan gives a model endpoint on this computer's loopback when its harness runs in a container, where "localhost" would name the container and is never proxied. It is under .internal, which no public name uses, and only a local run pins it.
Variables ¶
This section is empty.
Functions ¶
func AllowHost ¶
AllowHost is the host of an allowlist entry (host, host:port or [v6]:port), lower-cased as a proxy compares it.
func Pins ¶
func Pins(ctx context.Context, allow []string, lookup func(context.Context, string) ([]net.IP, error)) []string
Pins answers the proxy's --add-host entries ("name:ip") for the allowlist's hosts, resolved with lookup. Only IPv4 answers are pinned, since a proxy's network may have no IPv6 route; IP literals, the engines' own names, names that do not resolve here, and loopback or unspecified answers (which inside a container would name the container itself) are left to the container's DNS.
func Upstreams ¶
func Upstreams() []string
Upstreams are this machine's name servers as a container can reach them, for a proxy that may reach any public host, whose names cannot be pinned ahead: the IPv4 servers of the first file of resolvConfs that names any besides loopback ones, at most three, as a resolv.conf reads them. Nil when none does.
Types ¶
type ModelHosts ¶
type ModelHosts struct {
// Pins are the proxy's --add-host entries: "name:ip" for an endpoint
// elsewhere, "name:host-gateway" for one on this computer.
Pins []string
// Gateway are the hosts of Pins that name this computer.
Gateway []string
// Unresolved are the hosts this machine's resolver says do not exist,
// so that the proxy can say so in plain words when one is dialled.
Unresolved []string
}
ModelHosts is what ResolveModelHosts found for a model allowlist.
func ResolveModelHosts ¶
func ResolveModelHosts(ctx context.Context, allow []string, lookup func(context.Context, string) ([]net.IP, error), hostname string, local bool) ModelHosts
ResolveModelHosts resolves a model allowlist's hosts with lookup, as Pins does, and, for a run on this computer (local), pins every host that means this computer to HostGateway: localhost and *.localhost, a name with a loopback answer (a Mac answers its own .local name with 127.0.0.1 beside its LAN address, and many Linux hosts map their own name to 127.0.1.1), and the machine's own name (hostname, its first label, or that label with .local) when the lookup fails. Inside the proxy's container a loopback address names the container itself, so such an endpoint would otherwise be unreachable. A run whose caller says it is not local (a hosted run's) never reaches its host this way. A name the lookup reports as not existing (not one that timed out) is Unresolved. IP literals and the engines' own names (host.docker.internal, host.containers.internal) are left to the container.