On this page:
1.1 IP Addresses
ip4
ip6
1.2 Abstract Registered Names
reg-name
1.3 DNS Names
dns
dns-label?
dns-root-label
example.
example.com.
example.net.
example.org.
invalid.
local.
localhost.
test.
1.4 UNIX Socket Names
unix-socket-name
unix-socket-name->string
1.5 Authorities
authority
1.6 URIs
1.7 Contract Utilities
bytes/  c
7.1

1 Networking Data Structures

 (require net2/data) package: net2

The net2 library defines several data structures related to networking, as well as validating conversions to and from strings. Many of these data types are specified by Request for Comments (RFC) documents published by the Internet Engineering Task Force (IETF); references to appropriate specifications are included in the documentation of each data structure.

The Internet Assigned Numbers Authority (IANA) is another relevant organization that defines and operates centrally managed globally unique namespaces used for a wide variety of purposes. The IANA may delegate assignment of names in namespace subtrees to other organizations, which may delegate further to other entities. This chained delegation of namespace responsibility defines a federated namespace. DNS names serve as a classic example of such a namespace.

1.1 IP Addresses

struct

(struct ip4 (bytes)
    #:transparent)
  bytes : (bytes/c 4)
An IPv4 address.

struct

(struct ip6 (bytes)
    #:transparent)
  bytes : (bytes/c 16)
An IPv6 address.

1.2 Abstract Registered Names

struct

(struct reg-name ()
    #:transparent)
Supertype of all registered names: names that are centrally managed according to some publicly known name registry. Subtypes of reg-name typically specify what registry is used and how to register names, as well as how to resolve a registered name to a host if possible. This name-to-host resolution process is often referred to as a name lookup.

Note that IP addresses are not considered registered names by this definition because their name-to-host mapping is an inherent physical property of the Internet’s network topology and the IP protocol itself. Put more simply, an IP address isn’t a name for an Internet host: it’s the definition of a host.

Registered names are used in URIs and authorities to avoid name collisions for global identifiers. Frequently the registry for a name will allow extension and delegation with a federated namespace.

All registered names SHOULD obey the syntax rules for well-formed DNS names. Additionally, names that depend on the resolver’s context (such as dns-localhost) SHOULD be distinguishable from globally-scoped names without requiring clients perform a name lookup. Designers of new globally-scoped registered name systems are encouraged to reuse the Special Use Domain Names specified in RFC 6761 with equivalent semantics.

Currently, the only subtypes of reg-name are the dns and unix-socket-name types.

1.3 DNS Names

struct

(struct dns reg-name (labels)
    #:transparent)
  labels : (listof dns-label?)
A Domain Name System registered name consisting of labels as defined by RFC 952, RFC 1034, RFC 1035, and RFC 1123 Section 2. In addition to the length restrictions of dns-label?, the total length of a DNS name must not exceed 255 bytes including one byte for a length header between labels.

If the last element of labels is dns-root, the name is fully qualified. Otherwise, the domain name is partially qualified and is typically resolved relative to either the root domain or relative to a domain in a locally configured search list.

procedure

(dns-label? v)  boolean?

  v : any/c
Implies (bytes? v). Returns #t when v is a valid DNS label. Labels may consist of zero to 63 bytes with no restrictions on what bytes are allowed. However, according to the RFCs mentioned in dns, labels that are equal when compared case-insensitively as Latin-1 strings are considered identical. When rendered, labels are typically displayed as strings.

value

dns-root-label : dns-label? = #""

The root DNS nameserver, represented by an empty label. See dns for a discussion on the root nameserver and the difference between fully and partially qualified names.

value

example. : dns?

value

example.com. : dns?

value

example.net. : dns?

value

example.org. : dns?

value

invalid. : dns?

value

local. : dns?

value

localhost. : dns?

value

test. : dns?

Constants for Special Use Domain Names as defined in RFC 6761 and registered in the IANA Special Use Domain Names Registry.

1.4 UNIX Socket Names

struct

(struct unix-socket-name reg-name (path)
    #:transparent)
  path : (and/c unix-socket-path? complete-path?)
A registered name corresponding to a host that can be communicated with via the UNIX domain socket path. Note that all domain socket communication is inherently between processes on the same machine and involves no network access. The machine in question must be running a POSIX-compliant operating system and abstract socket names (as used in Linux) are not supported. Due to the use of registered names in URIs, a few more restrictions beyond those implied by complete-path? and unix-socket-path? must be satisfied:

procedure

(unix-socket-name->string sock-name)  string?

  sock-name : unix-socket-name?
TODO: document this

1.5 Authorities

struct

(struct authority (host port)
    #:transparent)
  host : (or/c ip6? ip4? reg-name?)
  port : port-number?
Structure type of an authority, as defined in RFC 3986. An authority is a hierarchical representation of some sort of naming authority, which establishes who has the right to respond authoritatively for requests to that authority’s namespace. For example, an authority composed of an IP address and a port number establishes whatever program is listening for connections to that port on the machine reachable at that IP address as a naming authority.

Authorities are a component of the generic syntax of URIs, and are used in URIs to define how to take a URI and establish who to talk to for authoritative information about the resource identified by the URI. Note that URIs include a scheme component that establishes what protocol to use when communicating with an authority.

Currently, including identifying user info in authorites (see RFC 3986 Section 3.2.1) is not supported due to historically widespread security problems and a lack of immediate use cases.

1.6 URIs

1.7 Contract Utilities

procedure

(bytes/c n)  flat-contract?

  n : exact-nonnegative-integer?
Returns a flat contract that recognizes immutable bytestrings of length n.