aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorKim Alvefur <zash@zash.se>2018-02-23 17:10:21 +0100
committerKim Alvefur <zash@zash.se>2018-02-23 17:10:21 +0100
commit7a08d4ca2777bda6abf220d17f69ef5d8338211e (patch)
treee235844694db8a66dcbeb8b82764bd670422de95 /doc
parentc27281a72055b599acab5272f17b869914ef936d (diff)
downloadprosody-7a08d4ca2777bda6abf220d17f69ef5d8338211e.tar.gz
prosody-7a08d4ca2777bda6abf220d17f69ef5d8338211e.zip
doc: Add template / API specification for net.server (thanks Daurnimator)
Diffstat (limited to 'doc')
-rw-r--r--doc/net.server.lua243
1 files changed, 243 insertions, 0 deletions
diff --git a/doc/net.server.lua b/doc/net.server.lua
new file mode 100644
index 00000000..11fc317d
--- /dev/null
+++ b/doc/net.server.lua
@@ -0,0 +1,243 @@
+-- Prosody IM
+-- Copyright (C) 2014,2016 Daurnimator
+--
+-- This project is MIT/X11 licensed. Please see the
+-- COPYING file in the source package for more information.
+
+--[[
+This file is a template for writing a net.server compatible backend.
+]]
+
+--[[
+Read patterns (also called modes) can be one of:
+ - "*a": Read as much as possible
+ - "*l": Read until end of line
+]]
+
+--- Handle API
+local handle_mt = {};
+local handle_methods = {};
+handle_mt.__index = handle_methods;
+
+function handle_methods:set_mode(new_pattern)
+end
+
+function handle_methods:setlistener(listeners)
+end
+
+function handle_methods:setoption(option, value)
+end
+
+function handle_methods:ip()
+end
+
+function handle_methods:starttls(sslctx)
+end
+
+function handle_methods:write(data)
+end
+
+function handle_methods:close()
+end
+
+function handle_methods:pause()
+end
+
+function handle_methods:resume()
+end
+
+--[[
+Returns
+ - socket: the socket object underlying this handle
+]]
+function handle_methods:socket()
+end
+
+--[[
+Returns
+ - boolean: if an ssl context has been set on this handle
+]]
+function handle_methods:ssl()
+end
+
+
+--- Listeners API
+local listeners = {}
+
+--[[ connect
+Called when a client socket has established a connection with it's peer
+]]
+function listeners.onconnect(handle)
+end
+
+--[[ incoming
+Called when data is received
+If reading data failed this will be called with `nil, "error message"`
+]]
+function listeners.onincoming(handle, buff, err)
+end
+
+--[[ status
+Known statuses:
+ - "ssl-handshake-complete"
+]]
+function listeners.onstatus(handle, status)
+end
+
+--[[ disconnect
+Called when the peer has closed the connection
+]]
+function listeners.ondisconnect(handle)
+end
+
+--[[ drain
+Called when the handle's write buffer is empty
+]]
+function listeners.ondrain(handle)
+end
+
+--[[ readtimeout
+Called when a socket inactivity timeout occurs
+]]
+function listeners.onreadtimeout(handle)
+end
+
+--[[ detach: Called when other listeners are going to be removed
+Allows for clean-up
+]]
+function listeners.ondetach(handle)
+end
+
+--- Top level functions
+
+--[[ Returns the syscall level event mechanism in use.
+
+Returns:
+ - backend: e.g. "select", "epoll"
+]]
+local function get_backend()
+end
+
+--[[ Starts the event loop.
+
+Returns:
+ - "quitting"
+]]
+local function loop()
+end
+
+--[[ Stop a running loop()
+]]
+local function setquitting(quit)
+end
+
+
+--[[ Links to two handles together, so anything written to one is piped to the other
+
+Arguments:
+ - sender, reciever: handles to link
+ - buffersize: maximum #bytes until sender will be locked
+]]
+local function link(sender, receiver, buffersize)
+end
+
+--[[ Binds and listens on the given address and port
+If `sslctx` is given, the connecting clients will have to negotiate an SSL session
+
+Arguments:
+ - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
+ - port: port to bind (as number)
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+
+Returns:
+ - handle
+ - nil, "an error message": on failure (e.g. out of file descriptors)
+]]
+local function addserver(address, port, listeners, pattern, sslctx)
+end
+
+--[[ Wraps a lua-socket socket client socket in a handle.
+The socket must be already connected to the remote end.
+If `sslctx` is given, a SSL session will be negotiated before listeners are called.
+
+Arguments:
+ - socket: the lua-socket object to wrap
+ - ip: returned by `handle:ip()`
+ - port:
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+ - typ: the socket type, one of:
+ - "tcp"
+ - "tcp6"
+ - "udp"
+
+Returns:
+ - handle, socket
+ - nil, "an error message": on failure (e.g. )
+]]
+local function wrapclient(socket, ip, serverport, listeners, pattern, sslctx)
+end
+
+--[[ Connects to the given address and port
+If `sslctx` is given, a SSL session will be negotiated before listeners are called.
+
+Arguments:
+ - address: address to connect to. will be resolved if it is a string.
+ - port: port to connect to (as number)
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+ - typ: the socket type, one of:
+ - "tcp"
+ - "tcp6"
+ - "udp"
+
+Returns:
+ - handle
+ - nil, "an error message": on failure (e.g. out of file descriptors)
+]]
+local function addclient(address, port, listeners, pattern, sslctx, typ)
+end
+
+--[[ Close all handles
+]]
+local function closeall()
+end
+
+--[[ The callback should be called after `delay` seconds.
+The callback should be called with the time at the point of firing.
+If the callback returns a number, it should be called again after that many seconds.
+
+Arguments:
+ - delay: number of seconds to wait
+ - callback: function to call.
+]]
+local function add_task(delay, callback)
+end
+
+--[[ Adds a handler for when a signal is fired.
+Optional to implement
+callback does not take any arguments
+
+Arguments:
+ - signal_id: the signal id (as number) to listen for
+ - handler: callback
+]]
+local function hook_signal(signal_id, handler)
+end
+
+
+return {
+ get_backend = get_backend;
+ loop = loop;
+ setquitting = setquitting;
+ link = link;
+ addserver = addserver;
+ wrapclient = wrapclient;
+ addclient = addclient;
+ closeall = closeall;
+ hook_signal = hook_signal;
+}