net -- basic networking

Module tree

net -- sockets, addresses and miscellaneous functionality

• http -- generic low-level HTTP support

Index

namespace net

Constants

• MAX_BACKLOG -- Largest possible backLog value for TcpListener::listen()
• SELECT_CAP -- Maximum number of file descriptors net.select() can handle for each input list

invar type Ipv4Addr

• Ipv4Addr(value: string)
• Ipv4Addr(a: int, b: int, c: int, d: int)
• .value(self: Ipv4Addr) => string
• .octets(self: Ipv4Addr) => tuple<int,int,int,int>
• (string)(self: Ipv4Addr)
• is(self: Ipv4Addr, what: enum<unspecified,multicast,private,global,loopback,linkLocal,broadcast>) => bool
• <(a: Ipv4Addr, b: Ipv4Addr) => bool
• <=(a: Ipv4Addr, b: Ipv4Addr) => bool
• ==(a: Ipv4Addr, b: Ipv4Addr) => bool
• !=(a: Ipv4Addr, b: Ipv4Addr) => bool
• +(a: Ipv4Addr, b: int) => Ipv4Addr
• -(a: Ipv4Addr, b: int) => Ipv4Addr

invar class SocketAddr

• SocketAddr(value: string)
• SocketAddr(ip: Ipv4Addr, port: int)
• .ip(self: SocketAddr) => Ipv4Addr
• .port(self: SocketAddr) => int
• .value(self: SocketAddr) => string
• (string)(self: SocketAddr)
• ==(a: SocketAddr, b: SocketAddr) => bool
• !=(a: SocketAddr, b: SocketAddr) => bool

class Socket

• fd(invar self: Socket) => int
• .localAddr(invar self: Socket) => SocketAddr
• .state(invar self: Socket ) => enum<closed,bound,listening,connected>
• close(self: Socket)

class TcpStream

• connect(self: TcpStream, addr: string|SocketAddr)
• write(self: TcpStream, data: string)
• writeFile(self: TcpStream, file: string)
• read(self: TcpStream, count = -1) => string
• readAll(self: TcpStream, count: int, prepend = '') => string
• .peerAddr(invar self: TcpStream) => SocketAddr
• check(self: TcpStream, what: enum<readable,writable,open,eof>) => bool
• shutdown(self: TcpStream, what: enum<send,receive,all>)
• .keepAlive(invar self: TcpStream ) => bool
• .keepAlive=(self: TcpStream, value: bool)
• .noDelay(invar self: TcpStream) => bool
• .noDelay=(self: TcpStream, value: bool)

class TcpListener

• listen(self: TcpListener, addr: string|SocketAddr, backLog = 10, binding: enum<exclusive,reused> = $exclusive)
• accept(self: TcpListener) => tuple<stream: TcpStream, addr: SocketAddr>
• for(self: TcpListener, iterator: ForIterator)
• [[]](self: TcpListener, index: ForIterator) => tuple<stream: TcpStream, addr: SocketAddr>

class UdpSocket

• bind(self: UdpSocket, addr: string|SocketAddr, binding: enum<exclusive,reused> = $exclusive)
• write(self: UdpSocket, addr: string|SocketAddr, data: string)
• read(self: UdpSocket, limit = 4096) => tuple<addr: SocketAddr, data: string>
• .broadcast(invar self: UdpSocket) => bool
• .broadcast=(self: UdpSocket, value: bool)
• .multicastLoop(invar self: UdpSocket) => bool
• .multicastLoop=(self: UdpSocket, value: bool)
• joinGroup(self: UdpSocket, group: string|Ipv4Addr)
• leaveGroup(self: UdpSocket, group: string|Ipv4Addr)
• .multicastTtl(invar self: UdpSocket) => int
• .multicastTtl=(self: UdpSocket, value: int)
• .ttl(invar self: UdpSocket) => int
• .ttl=(self: UdpSocket, value: int)

Functions

• listen(addr: string|SocketAddr, backLog = 10, binding: enum<exclusive,reused> = $exclusive) => TcpListener
• bind(addr: string|SocketAddr, binding: enum<exclusive,reused> = $exclusive) => UdpSocket
• connect(addr: string|SocketAddr) => TcpStream
• host(id: string) => tuple<name: string, aliases: list, addrs: list>|none
• service(id: string|int, proto: enum<tcp,udp>) => tuple<name: string, port: int, aliases: list>|none
• select(invar read: list<@R<Socket|int>>, invar write: list<@W<Socket|int>>, timeout: float ) => tuple<status: enum<selected,timeouted,interrupted>, read: list<@R>, write: list<@W>>

Types

####net::Ipv4Addr

IPv4 address as a CPOD type

Methods

Ipv4Addr(value: string)
Ipv4Addr(a: int, b: int, c: int, d: int)

Creates IPv4 address from dotted string value or given the individual octets a, b, c and d

Errors: Param in case of invalid address

.value(self: Ipv4Addr) => string

Address as a dotted string value

.octets(self: Ipv4Addr) => tuple<int,int,int,int>

Individual address octets

(string)(self: Ipv4Addr)

Same as .value()

is(self: Ipv4Addr, kind: enum<unspecified,multicast,private,global,loopback,linkLocal,broadcast>) => bool

Returns true if the address belongs to the specified kind

<(a: Ipv4Addr, b: Ipv4Addr) => bool
<=(a: Ipv4Addr, b: Ipv4Addr) => bool
==(a: Ipv4Addr, b: Ipv4Addr) => bool
!=(a: Ipv4Addr, b: Ipv4Addr) => bool

Address comparison

+(a: Ipv4Addr, b: int) => Ipv4Addr
-(a: Ipv4Addr, b: int) => Ipv4Addr

Address arithmetics

---

####net::SocketAddr

Socket address, consisting of Ipv4Addr and port number

Methods

SocketAddr(value: string)

Creates socket address given 'host:port' value (if the host part is empty, '0.0.0.0' is assumed)

Errors: Param in case of invalid address, 'Network::Host' in case of host lookup error

SocketAddr(ip: Ipv4Addr, port: int)

Creates socket address given or ip and port

Errors: Param in case of invalid address

.ip(self: SocketAddr) => Ipv4Addr

IP address

.port(self: SocketAddr) => int

Port number

.value(self: SocketAddr) => string

'ip:port' string

(string)(self: SocketAddr)

Same as .value()

==(a: SocketAddr, b: SocketAddr) => bool
!=(a: SocketAddr, b: SocketAddr) => bool

Address comparison

---

####net::Socket

Abstract socket type

Methods

.fd(invar self: Socket) => int

Socket file descriptor

.localAddr(invar self: Socket) => SocketAddr

Address to which the socket is bound

Errors: Network in case of failure

.state( invar self: Socket ) => enum<closed,bound,listening,connected>

Current socket state

close(self: Socket)

Closes the socket

---

####net::TcpStream

Connected TCP socket

Methods

connect(self: TcpStream, addr: string|SocketAddr)

Connects to address addr which may be either a 'host:port' string or SocketAddr

Errors: SocketAddr() errors, Network in case of failure

write(self: TcpStream, data: string)

Sends data

Errors: Network in case of failure

writeFile(self: TcpStream, file: string)

Sends file

Errors: Network in case of failure

read(self: TcpStream, count = -1) => string

Receives at most count bytes (64Kb max, 4Kb if count <= 0) and returnes the received data

Errors: Network in case of failure

readAll(self: TcpStream, count: int, prepend = '') => string

Attempts to receive exactly count bytes of data and return it. Will return less data only if the connection was closed.

If prepend is given, it will be prepended to the resulting string. Use case: receiving a message with a header and a large body (e.g., HTTP response). First, the header is read, by which the body size is determined. While doing this, part of the message body might be read along with the header. Concatenating it with the rest of the body after receiving the latter would nullify the performance advantage of using readAll(), so that chunk should be passed as prepend parameter

Errors: Param in case of invalid count, Network in case of failure

.peerAddr(invar self: TcpStream) => SocketAddr

Peer address of the connected socket

Errors: Network in case of failure

check(self: TcpStream, what: enum<readable,writable,open,eof>) => bool

Checks the property specified by what; required to satisfy io::Device interface

shutdown(self: TcpStream, what: enum<send,receive,all>)

Fully or partially shuts down the connection, stopping further operations specified by what

Errors: Network in case of failure

.keepAlive(invar self: TcpStream) => bool
.keepAlive=(self: TcpStream, value: bool)

TCP keep-alive option (SO_KEEPALIVE)

Errors: Network in case of get/set failure

.noDelay(invar self: TcpStream) => bool
.noDelay=(self: TcpStream, value: bool)

TCP no-delay option (SO_NODELAY)

Errors: Network in case of get/set failure

---

####net::TcpListener

Listening TCP socket

Methods

listen(self: TcpListener, addr: string|SocketAddr, backLog = 10, binding: enum<exclusive,reused> = $exclusive)

Binds the socket to address addr (either a 'host:port' string or SocketAddr) using binding option (see net.listen() for its description). Sets the socket into the listening state using backLog as the maximum size of the queue of pending connections (use MAX_BACKLOG constant to assign the maximum queue size)

Errors: SocketAddr() errors, Param on invalid backLog, Network in case of failure

accept(self: TcpListener) => tuple<stream: TcpStream, addr: SocketAddr>

Accepts new connection, returning the corresponding TcpStream and peer address

Errors: Network in case of failure

for(self: TcpListener, iterator: ForIterator)
[](self: TcpListener, index: ForIterator) => tuple<stream: TcpStream, addr: SocketAddr>

Equivalient to an infinite loop calling .accept() on each iteration

---

####net::UdpSocket

UDP socket

Methods

bind(self: UdpSocket, addr: string|SocketAddr, binding: enum<exclusive,reused> = $exclusive)

Binds the socket to address addr (either a 'host:port' string or SocketAddr) using binding option (see net.listen() for its description)

Errors: SocketAddr() errors, Network in case of failure

write(self: UdpSocket, addr: string|SocketAddr, data: string)

Sends data to the receiver specified by address addr which is either a 'host:port' string or SocketAddr

Errors: Network in case of failure

read(self: UdpSocket, limit = 4096 ) => tuple<addr: SocketAddr, data: string>)

Receives at most limit bytes and returnes the received data and the address of its sender

Errors: Network in case of failure

.broadcast(invar self: UdpSocket) => bool
.broadcast=(self: UdpSocket, value: bool)

UDP broadcast option (SO_BROADCAST)

Errors: Network in case of get/set failure

.multicastLoop(invar self: UdpSocket) => bool
.multicastLoop=(self: UdpSocket, value: bool)

Multicast loop socket option (IP_MULTICAST_LOOP)

Errors: Network in case of get/set failure

joinGroup(self: UdpSocket, group: string|Ipv4Addr)

Joins multicast group specified by its host name or ip address

Errors: Network::Host on host lookup error, Network in case of failure

leaveGroup(self: UdpSocket, group: string|Ipv4Addr)

**Errors:** `Network::Host` on host lookup error, `Network` in case of failure

.multicastTtl(invar self: UdpSocket) => int
.multicastTtl=(self: UdpSocket, value: int)

Multicast TTL value (IP_MULTICAST_TTL)

Errors: Network in case of get/set failure

.ttl(invar self: UdpSocket) => int
.ttl=(self: UdpSocket, value: int)

TTL value (IP_TTL)

Errors: Network in case of get/set failure

Functions

listen(addr: string|SocketAddr, backLog = 10, binding: enum<exclusive,reused> = $exclusive) => TcpListener

Returns new TCP listener bound to address addr (either a 'host:port' string or SocketAddr) with binding option used to regulate the possibility of address rebinding. The socket is put in the listening state using backLog as the maximum size of the queue of pending connections (use MAX_BACKLOG constant to assign the maximum queue size).

Meaning of binding values: -exclusive -- exclusive binding of the address which excludes rebinding (SO_EXCLUSIVEADDRUSE on Windows, ignored on Unix) -reused -- allows the address to be rebound if it is not already bound exclusively (SO_REUSEADDR on Windows and Unix)

Errors: SocketAddr() errors, Param on invalid backLog, Network in case of failure

bind(addr: string|SocketAddr, binding: enum<exclusive,reused> = $exclusive) => UdpSocket

Returns new UDP socket bound to address addr (either a 'host:port' string or SocketAddr) with binding option (see net.listen() for its description)

Errors: SocketAddr() errors, Network in case of failure

connect(addr: string|SocketAddr) => TcpStream

Returns client-side TCP connection endpoint connected to address addr which may be either a 'host:port' string or SockAddr

Errors: SocketAddr() errors, Network in case of failure

host(id: string) => tuple<name: string, aliases: list<string>, addrs: list<Ipv4Addr>>|none

Returns information for host with the given id (which may be either a name or an IPv4 address in dotted form). Returns none if the host is not found or does not have an IP address

Errors: Network::Host on host lookup error

service(id: string|int, proto: enum<tcp,udp>) => tuple<name: string, port: int, aliases: list<string>>|none

Returns information for service with the given id (which may be either a name or a port number) to be used with the protocol proto. Returns none if the corresponding service was not found

select(invar read: list<@R<Socket|int>>, invar write: list<@W<Socket|int>>, timeout: float) => tuple<status: enum<selected,timeouted,interrupted>, read: list<@R>, write: list<@W>>

Waits timeout seconds for any Socket or file descriptor in read or write list to become available for reading or writing accordingly. Returns sub-lists of read and write containing available sockets/descriptors.

Note: On Windows, only socket descriptors can be selected Errors: Param if both lists are empty or one of them contains an invalid file descriptor or closed socket, Network in case of failure