Documentation
¶
Overview ¶
Package netdriver is how containers reach a network: a NetworkDriver gives each container an Endpoint, and the engine's WASI host maps the WasmEdge socket functions of wasi_snapshot_preview1 (sock_open, sock_bind, sock_listen, sock_accept, sock_connect, sock_recv_from, sock_send_to, sock_getaddrinfo, ...) onto it.
The contract is the relay's (github.com/go-wasmcontainers/relay, docs/NETWORKDRIVER.md): addresses are the driver's, a connect blocks until the peer accepts or refuses, errors unwrap to the syscall.Errno a socket call returns. Local is an in-engine network with DNS by container name; package relaynet puts containers on a class network through the relay.
Index ¶
- Constants
- Variables
- func Answer(ctx context.Context, ...) []byte
- func ValidName(s string) bool
- type AliasDriver
- type Endpoint
- type Local
- type Multi
- func (m *Multi) Add(ctx context.Context, network string, ep Endpoint) error
- func (m *Multi) Addr() netip.Addr
- func (m *Multi) Detach() error
- func (m *Multi) Dial(ctx context.Context, network string, addr netip.AddrPort) (net.Conn, error)
- func (m *Multi) Endpoints() []NamedEndpoint
- func (m *Multi) Listen(ctx context.Context, network string, port uint16) (net.Listener, error)
- func (m *Multi) ListenPacket(ctx context.Context, network string, port uint16) (net.PacketConn, error)
- func (m *Multi) Remove(network string) (Endpoint, bool)
- func (m *Multi) Resolve(ctx context.Context, name string) ([]netip.Addr, error)
- type NamedEndpoint
- type NetworkDriver
Constants ¶
const ( // MaxDatagram bounds one datagram (the relay's limit). MaxDatagram = 8 << 10 // DatagramQueue is how many datagrams a socket holds before dropping. DatagramQueue = 256 // Backlog is how many connections wait for Accept before a connect is // refused. Backlog = 128 // MaxEndpoints bounds a network's containers. MaxEndpoints = 4096 // MaxSockets bounds the listeners and datagram sockets of one network. MaxSockets = 1 << 15 // MaxAliases bounds one endpoint's aliases. MaxAliases = 32 )
const DNSTTL = 5
DNSTTL is the time to live of every answer, in seconds: addresses are stable while a container is attached, but containers come and go.
const MaxDNSMessage = 512
MaxDNSMessage bounds a query and an answer: plain DNS over UDP, no EDNS.
const StreamWindow = 64 << 10
StreamWindow is how many bytes one direction of a local stream holds before its writer blocks (the relay's window is the same).
Variables ¶
var DefaultPrefix = netip.MustParsePrefix("10.88.0.0/16")
DefaultPrefix is Local's network unless NewLocal is given another.
var Resolvers = []netip.Addr{ netip.AddrFrom4([4]byte{127, 0, 0, 11}), netip.AddrFrom4([4]byte{127, 0, 0, 1}), netip.IPv6Loopback(), }
Resolvers are the addresses where a container's stub resolver finds the network's DNS: 127.0.0.11 (Docker's embedded DNS) and 127.0.0.1 / ::1, which Go's and musl's resolvers use when /etc/resolv.conf is missing — as it is in most wasm images.
Functions ¶
func Answer ¶
func Answer(ctx context.Context, resolve func(context.Context, string) ([]netip.Addr, error), query []byte) []byte
Answer answers one DNS query (RFC 1035) from resolve: A and AAAA records of a name that resolves, NOERROR with no record for its other types, NXDOMAIN for a name that does not, SERVFAIL when resolve fails otherwise, FORMERR for a malformed query, NOTIMP for an opcode other than QUERY. It returns nil for what is not a query (a response, or too short to carry an ID). Answers fit in MaxDNSMessage bytes, truncated (TC) otherwise.
Types ¶
type AliasDriver ¶ added in v0.14.0
type AliasDriver interface {
NetworkDriver
AttachAliases(ctx context.Context, container string, aliases []string) (Endpoint, error)
}
AliasDriver is a NetworkDriver whose containers can answer to more names than their own (Docker's network aliases). Local is one; a driver that is not refuses a container that asks for aliases.
type Endpoint ¶
type Endpoint interface {
Addr() netip.Addr
// Listen is a SOCK_STREAM bind+listen ("tcp"); port 0 picks an
// ephemeral port, which the listener's Addr says.
Listen(ctx context.Context, network string, port uint16) (net.Listener, error)
// Dial is a SOCK_STREAM connect ("tcp") or a connected SOCK_DGRAM
// socket ("udp").
Dial(ctx context.Context, network string, addr netip.AddrPort) (net.Conn, error)
// ListenPacket is a SOCK_DGRAM bind ("udp").
ListenPacket(ctx context.Context, network string, port uint16) (net.PacketConn, error)
// Resolve is sock_getaddrinfo: a container's name, or an IP literal.
Resolve(ctx context.Context, name string) ([]netip.Addr, error)
Detach() error
}
Endpoint is one container's place on a network.
func WithDNS ¶
WithDNS returns ep with a DNS server on its resolver addresses: a UDP socket connected to one of Resolvers, port 53, is answered in the engine from ep.Resolve — A and AAAA records for the network's names, NXDOMAIN for anything else. Nothing is forwarded outside the network. So a stock Go or C program resolves container names with no sock_getaddrinfo. (A container's own UDP server on those addresses, port 53, is shadowed.)
type Local ¶
type Local struct {
// contains filtered or unexported fields
}
Local is a network inside the engine: each attached container gets an address in Prefix, containers reach each other's listeners by address or by name (Resolve), and 127.0.0.1 is the container itself. Streams are in-memory and flow-controlled (StreamWindow per direction); datagrams are at most MaxDatagram bytes, and a full receive queue drops, as a socket buffer would.
func NewLocal ¶
NewLocal returns an empty network on prefix (an IPv4 prefix of at least 2 host bits).
func (*Local) AttachAliases ¶ added in v0.14.0
func (n *Local) AttachAliases(ctx context.Context, container string, aliases []string) (Endpoint, error)
AttachAliases implements AliasDriver: the container also answers to aliases on this network (Docker's network aliases; a compose service's name). An alias several containers share resolves to all of them, in an order that rotates from one query to the next. A container's own name wins over another's alias. Attaching again replaces the aliases.
type Multi ¶ added in v0.14.0
type Multi struct {
// contains filtered or unexported fields
}
Multi is one container on several networks (`docker network connect`): an Endpoint over one endpoint per network, in the order they were added.
- Addr is the first network's address.
- A listener or a datagram socket is open on every network, as one bound to 0.0.0.0 is, networks added while it is open included (a network where its port is taken is skipped).
- A dial goes out through the network whose prefix holds the address (an endpoint with a Prefix method), else through the first network that reaches it.
- Resolve asks every network, the first one's answers first.
func (*Multi) Detach ¶ added in v0.14.0
Detach implements Endpoint: every network's endpoint is detached.
func (*Multi) Endpoints ¶ added in v0.14.0
func (m *Multi) Endpoints() []NamedEndpoint
Endpoints returns the networks and their endpoints, in order.
func (*Multi) ListenPacket ¶ added in v0.14.0
func (m *Multi) ListenPacket(ctx context.Context, network string, port uint16) (net.PacketConn, error)
ListenPacket implements Endpoint.
type NamedEndpoint ¶ added in v0.14.0
NamedEndpoint is a Multi's endpoint on one network.
type NetworkDriver ¶
type NetworkDriver interface {
// Attach gives container (a DNS label: [a-z0-9-]{1,63}) an endpoint.
// Attaching the same name again returns the same address.
Attach(ctx context.Context, container string) (Endpoint, error)
Close() error
}
NetworkDriver gives containers endpoints on a network.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package relaynet puts containers on a class network through the relay (github.com/go-wasmcontainers/relay): one driver.Session per engine, one endpoint per container, as the relay's docs/NETWORKDRIVER.md describes.
|
Package relaynet puts containers on a class network through the relay (github.com/go-wasmcontainers/relay): one driver.Session per engine, one endpoint per container, as the relay's docs/NETWORKDRIVER.md describes. |