# Networking

The package `core.net` contains classes to communicate through a network. To allow this, the library provides a representation of IP addresses, sockets, and listener sockets. The network interfaces generally throw the `core.net.NetError` when an error occurs.

## Address

The `core.net.Address` class is an abstract representation of an internet address (e.g. IPv4 or IPv6 addresses), and an associated port. If the port is zero, then the port is unspecified, and will be allocated automatically by the system. The `Address` class is immutable, which means that it is not possible to modify an instance that has been created. Instead, it is necessary to create a copy with the desired modifications.

Subclassing the `Address` class requires low-level access to the memory representation used by the operating system. Therefore, it is not possible to create new derived classes from Storm. For this reason, the `Address` class has no public constructors exposed to Storm.

`Address` classes are typically created by calling the function `core.Array<core.net.Address> lookupAddress(core.Str addr)` to parse a string into an address. This interface supports DNS queries as well.

The `Address` class has the following members in additional to the usual `toS` and `hash` members:

- `core.Nat port()`

  Get the port.

- `core.net.Address withPort(core.Nat port)`

  Create a copy bound to a different port.

The system currently provides two subclasses, one for IPv4 addresses, and another for IPv6 addresses. The IPv4 class, `core.net.Inet4Address`, has the following additional members:

- `core.Nat data()`

  Get the raw address.

- `core.Nat count()`

  Number of bytes. Allows iterating through the individual parts.

- `core.Byte [](core.Nat id)`

  Access individual parts by index.

For IPv6 addresses, the class `core.net.Inet6Address` is used. It has the following additional members:

- `core.Nat count()`

  Number of 16-bit parts. Allows iterating through the individual parts.

- `core.Nat [](core.Nat id)`

  Access individual parts by index. Each part is 16 bits long.

- `core.Nat flowInfo()`

  Get flow info.

- `core.Nat scope()`

  Get scope.

## Sockets

Generic sockets are represented by the class `core.net.Socket`. This class provides generic socket control operations that are relevant both for TCP and UDP. Currently, only TCP sockets are supported. A TCP socket is represented by the class `core.net.NetStream`.

A client socket is created by calling one of the `connect` functions:

- `core.Maybe<core.net.NetStream> connect(core.net.Address to)`

  Create a socket that is connected to a specific address.

- `core.Maybe<core.net.NetStream> connect(core.Str host, core.Nat port)`

  Create a socket that is connected to a specific address, resolving the name first. If `host` specifies a port, it overrides the port in `port`.

A `NetStream` contains the following members:

- `core.net.NetIStream input()`

  Get the input stream.

- `core.net.NetOStream output()`

  Get the output stream.

- `core.Bool nodelay()`

  Get the value of the `nodelay` socket option.

- `void nodelay(core.Bool v)`

  Set the `nodelay` socket option.

- `core.net.Address remote()`

  Get the remote host we're connected to.

- `void close()`

  Close both ends of the socket.

Closing the input and/or output streams shuts down that part of the TCP stream. The socket itself must also be closed for a proper shutdown. It is possible to simply close the socket without closing either of the input and output streams. Some protocols do, however, require graceful shutdown of one or both ends.

The generic `Socket` interface also contains the following properties that can be get and set using getters and setters: `inputTimeout`, `outputTimeout`, `inputBufferSize`, and `outputBufferSize`.

## Listener

A `core.net.Listener` represents an open TCP socket that accepts incoming connections. A `Listener` is created by calling one of the `listen` functions as follows. The socket option `SO_REUSEADDR` is set by default so that it is possible to reuse a port immediately, even after a previous process failed to shut down properly. This can be overridden by specifying `reuseAddr` to `false` in the calls to the `listen` functions below:

- `core.Maybe<core.net.Listener> listen(core.Nat port)`

  Listen on all interfaces on `port`. If `port` is zero, pick an unused port.

- `core.Maybe<core.net.Listener> listen(core.Nat port, core.Bool reuseAddr)`

  Listen on all interfaces on `port`, explicitly specifying the use of SO_REUSEADDR.

- `core.Maybe<core.net.Listener> listen(core.net.Address addr)`

  Listen on the address specified by `addr`.

- `core.Maybe<core.net.Listener> listen(core.net.Address addr, core.Bool reuseAddr)`

  Listen on the address specified by `addr`, explicitly specifying the use of SO_REUSEADDR.

The `Listener` class inherits from `core.net.Socket`, and adds the function:

- `core.Maybe<core.net.NetStream> accept()`

  Accept a new connection. Returns `null` if the listener has been closed.

- `void close()`

  Close the socket. Calls 'close' on both the input and output streams.

As with all sockets, the listener should be closed when it is no longer needed.