readme engo
1 files changed, 75 insertions(+), 2 deletions(-) M README.md
M README.md => README.md +75 -2
@@ 1,4 1,77 @@ # nex.nelua nightfall express and nightfall postal service servers written in the [nelua](https://nelua.io) programming language [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, 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, 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. 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