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.