# nex.nelua

[nightfall express](https://nightfall.city/nex/info/specification.txt)
and [nightfall postal service](https://nightfall.city/nps/info/specification.txt)
servers written in the [nelua](https://nelua.io) programming language.

these aren't intended as full servers, they serve entirely from code.
you'll need to write up your backend yourself, but it's more fun that
way.

this implementation relies on the `epoll` family of syscalls, so YMMV
on non-linux or non-freebsd systems.

## building

install the nelua compiler, clone the repo. `nex.nelua` and `nps.nelua`
are the 2 base scripts to play with. their implementations are
barebones but should serve as a good starting point.

once you're happy with your setup, make them into binaries with

    nelua -r -o nex nex.nelua
    nelua -r -o nps nps.nelua

and throw them up somewhere

## socket.nelua

a pretty minimal asynchronous socket library. it should have a
familiar-if-limited interface to anyone who has used a higher-level
asynchronous API. it is sufficient to implement most text-mode network
protocols, so long as they are not reliant on multiple sockets.

it exposes the following methods from its return value:

### `socket.listen_tcp(addr: string, conn_cap: uinteger, handler: function(): void)`

listens on the host/port in `addr`. panics if it can't connect or if
`addr` is malformed. `addr` is either of the format `IPV4:PORT` or
`{IPV6}:PORT`. passes the connection to `socket.listen_sock`.

### `socket.listen_sock(fd: cint, conn_cap: uinteger, handler: function(): void)`

`fd` must be a valid socket, bound to some address and ready to
`accept` incoming connections. as connections are made, `handler` will
be executed in the context of a coroutine. it is expected to call one
of the provided [yielding functions](#yielding-functions) eventually.

will begin refusing incoming requests at `conn_cap` open connections

if there is any error reading from or writing to the socket, the
handler coroutine is deleted and the connection is dropped.

it is unwise to `coroutine.yield` manually from the context of a
handler function.

### yielding functions

functions provided for handlers to interact with their associated
socket

#### `socket.send(data: string)`

writes `data` over the network

#### `socket.send_line(data: string)`

writes `data` over the network with newline appended

#### `socket.recv_line(): string`

waits for an incoming line of text. returns it with newline stripped

this function is not CRLF-aware, and you make need to strip those
manually.

#### `socket.end_conn()`

closes the connection and deletes this coroutine