Addresses

Addresses in Gruvi are a location to connect to or listen on. Addresses can be local (e.g. when using a pipe), or remote (when using TCP or UDP).

The following convention is used throughput Gruvi:

• Pipe addresses are represented as str or bytes instances. On Unix these represent paths in the file system but on Windows there is no such correspondence. On Linux there is a special class of abstract socket addresses that start with a null byte ('\x00').
• IP addresses are represented as (node, service) tuples. The format is identical for IPv4 and IPv6, and both protocols are supported transparently. The host component of the tuple is either DNS name or a string format numerical IPv4/IPv6 address, while the port component is either an integer port number or a service name.

In addition, some APIs also support connecting to a file descriptor or to a pyuv.Stream instance.

Name Resolution

IP (node, service) tuples are resolved to numerical host addresses and port numbers using the getaddrinfo() function. The resulting, resolved address is called a socket address, and should be distinguished from a non-resolved addressed which we simply call “address”.

switchpoint getaddrinfo(node, service=0, family=0, socktype=0, protocol=0, flags=0, timeout=30)

Resolve an Internet node name and service into a socket address.

The family, socktype and protocol are optional arguments that specify the address family, socket type and protocol, respectively. The flags argument allows you to pass flags to further modify the resolution process. See the socket.getaddrinfo() function for a detailed description of these arguments.

The return value is a list of (family, socktype, proto, canonname, sockaddr) tuples. The fifth element (sockaddr) is the socket address. It will be a 2-tuple (addr, port) for an IPv4 address, and a 4-tuple (addr, port, flowinfo, scopeid) for an IPv6 address.

The address resolution is performed in the libuv thread pool.

Note that the distinction between addresses and socket addresses is only present for IP addresses. Pipes don’t use address resolution and their addresses and socket addresses are the same.

A socket address can be resolved back to an address using getnameinfo():

switchpoint getnameinfo(sockaddr, flags=0, timeout=30)

Resolve a socket address sockaddr back to a (node, service) tuple.

The flags argument can be used to modify the resolution process. See the socket.getnameinfo() function for more information.

The address resolution is performed in the libuv thread pool.

Gruvi API function always accept addresses, and address resolution is performed automatically. The only place where you will work with raw socket addresses is when you query the address of an existing socket, using e.g. the get_extra_info() method of a transport.

Note that the first two elements of an IP socket address are always the numerical-as-string address and the port number (for both IPv4 and IPv6). Because getaddrinfo() also accepts numerical-as-string addresses and port numbers, they also form a valid address and could be passed back to getaddrinfo() again.

Some operating systems support a special convention to specify the scope ID for an IPv6 addressing using the 'host%ifname' notation where 'ifname' is the name of a network interface. Support for this is OS specific and neither libuv nor Gruvi try to present a portable interface for this.

String Addresses

Gruvi contains two utility functions to transform addresses to and from a string representation. This is useful when logging or when accepting addresses from the command line.

saddr(address)

Return a string representation for an address.

The address paramater can be a pipe name, an IP address tuple, or a socket address.

The return value is always a str instance.

paddr(address)

Parse a string representation of an address.

This function is the inverse of saddr().