hostpin

package
v0.7.51 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 8 Imported by: 0

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

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

View Source
const LookupTimeout = 2 * time.Second

LookupTimeout bounds each lookup: a name the host cannot resolve quickly is left to the container's DNS.

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

func AllowHost(entry string) string

AllowHost is the host of an allowlist entry (host, host:port or [v6]:port), lower-cased as a proxy compares it.

func Lookup

func Lookup(ctx context.Context, host string) ([]net.IP, error)

Lookup resolves a host with this machine's resolver, bounded by LookupTimeout.

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.

Jump to

Keyboard shortcuts

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