prosody
82705ec87253
doc/net.server.lua

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody

Annotate

doc/net.server.lua @ 10390:82705ec87253 0.11

util.startup: Ensure prosody.paths are absolute (see #1430) Normally these paths are injected into the installed 'prosody' executable as absolute paths, but it is possible to override at least the config path via environment variable or command line argument. This makes sure a path relative to pwd stays relative to that instead of the data directory.
author Kim Alvefur <zash@zash.se>
date Mon, 04 Nov 2019 00:29:49 +0100
parent 9295:6c7d2fb0d369
child 9846:9a0da809ed4a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 -- Prosody IM
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 -- Copyright (C) 2014,2016 Daurnimator
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 --
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 -- This project is MIT/X11 licensed. Please see the
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 -- COPYING file in the source package for more information.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
9295
6c7d2fb0d369 doc/net.server.lua: Not an actual source file, instruct luacheck to ignore it
Matthew Wild <mwild1@gmail.com>
parents: 8781
diff changeset
7 --luacheck: ignore
6c7d2fb0d369 doc/net.server.lua: Not an actual source file, instruct luacheck to ignore it
Matthew Wild <mwild1@gmail.com>
parents: 8781
diff changeset
8
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 This file is a template for writing a net.server compatible backend.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 Read patterns (also called modes) can be one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 - "*a": Read as much as possible
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 - "*l": Read until end of line
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 --- Handle API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 local handle_mt = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 local handle_methods = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 handle_mt.__index = handle_methods;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24 function handle_methods:set_mode(new_pattern)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 function handle_methods:setlistener(listeners)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 function handle_methods:setoption(option, value)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 function handle_methods:ip()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 function handle_methods:starttls(sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 function handle_methods:write(data)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 function handle_methods:close()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 function handle_methods:pause()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 function handle_methods:resume()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 - socket: the socket object underlying this handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 function handle_methods:socket()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 - boolean: if an ssl context has been set on this handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 function handle_methods:ssl()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 --- Listeners API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 local listeners = {}
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 --[[ connect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 Called when a client socket has established a connection with it's peer
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 function listeners.onconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 --[[ incoming
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76 Called when data is received
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77 If reading data failed this will be called with `nil, "error message"`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79 function listeners.onincoming(handle, buff, err)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82 --[[ status
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 Known statuses:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 - "ssl-handshake-complete"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 function listeners.onstatus(handle, status)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 --[[ disconnect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
90 Called when the peer has closed the connection
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92 function listeners.ondisconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
95 --[[ drain
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
96 Called when the handle's write buffer is empty
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
97 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98 function listeners.ondrain(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
99 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
100
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
101 --[[ readtimeout
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
102 Called when a socket inactivity timeout occurs
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
103 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
104 function listeners.onreadtimeout(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
105 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
106
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
107 --[[ detach: Called when other listeners are going to be removed
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
108 Allows for clean-up
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
109 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
110 function listeners.ondetach(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
111 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
112
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
113 --- Top level functions
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
114
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
115 --[[ Returns the syscall level event mechanism in use.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
116
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
117 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
118 - backend: e.g. "select", "epoll"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
120 local function get_backend()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
121 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
122
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
123 --[[ Starts the event loop.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
124
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
125 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
126 - "quitting"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
127 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
128 local function loop()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
129 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
130
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
131 --[[ Stop a running loop()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
132 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
133 local function setquitting(quit)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
134 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
135
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
136
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
137 --[[ Links to two handles together, so anything written to one is piped to the other
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
138
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
139 Arguments:
8728
41c959c5c84b Fix spelling throughout the codebase [codespell]
Kim Alvefur <zash@zash.se>
parents: 8532
diff changeset
140 - sender, receiver: handles to link
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
141 - buffersize: maximum #bytes until sender will be locked
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
142 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
143 local function link(sender, receiver, buffersize)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
144 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
145
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
146 --[[ Binds and listens on the given address and port
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
147 If `sslctx` is given, the connecting clients will have to negotiate an SSL session
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
148
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
149 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
150 - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
151 - port: port to bind (as number)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
152 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
153 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
154 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
155
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
156 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
157 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
158 - nil, "an error message": on failure (e.g. out of file descriptors)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
159 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
160 local function addserver(address, port, listeners, pattern, sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
161 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
162
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
163 --[[ Wraps a lua-socket socket client socket in a handle.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
164 The socket must be already connected to the remote end.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
165 If `sslctx` is given, a SSL session will be negotiated before listeners are called.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
166
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
167 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
168 - socket: the lua-socket object to wrap
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
169 - ip: returned by `handle:ip()`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
170 - port:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
171 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
172 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
173 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
174 - typ: the socket type, one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
175 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
176 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
177 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
178
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
179 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
180 - handle, socket
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
181 - nil, "an error message": on failure (e.g. )
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
182 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
183 local function wrapclient(socket, ip, serverport, listeners, pattern, sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
184 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
185
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
186 --[[ Connects to the given address and port
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
187 If `sslctx` is given, a SSL session will be negotiated before listeners are called.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
188
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
189 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
190 - address: address to connect to. will be resolved if it is a string.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
191 - port: port to connect to (as number)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
192 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
193 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
194 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
195 - typ: the socket type, one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
196 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
197 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
198 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
199
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
200 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
201 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
202 - nil, "an error message": on failure (e.g. out of file descriptors)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
203 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
204 local function addclient(address, port, listeners, pattern, sslctx, typ)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
205 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
206
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
207 --[[ Close all handles
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
208 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
209 local function closeall()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
210 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
211
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
212 --[[ The callback should be called after `delay` seconds.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
213 The callback should be called with the time at the point of firing.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
214 If the callback returns a number, it should be called again after that many seconds.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
215
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
216 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
217 - delay: number of seconds to wait
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
218 - callback: function to call.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
219 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
220 local function add_task(delay, callback)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
221 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
222
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
223 --[[ Adds a handler for when a signal is fired.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
224 Optional to implement
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
225 callback does not take any arguments
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
226
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
227 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
228 - signal_id: the signal id (as number) to listen for
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
229 - handler: callback
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
230 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
231 local function hook_signal(signal_id, handler)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
232 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
233
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
234 --[[ Adds a low-level FD watcher
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
235 Arguments:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
236 - fd_number: A non-negative integer representing a file descriptor or
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
237 object with a :getfd() method returning one
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
238 - on_readable: Optional callback for when the FD is readable
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
239 - on_writable: Optional callback for when the FD is writable
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
240
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
241 Returns:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
242 - net.server handle
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
243 ]]
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
244 local function watchfd(fd_number, on_readable, on_writable)
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
245 end
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
246
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
247 return {
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
248 get_backend = get_backend;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
249 loop = loop;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
250 setquitting = setquitting;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
251 link = link;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
252 addserver = addserver;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
253 wrapclient = wrapclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
254 addclient = addclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
255 closeall = closeall;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
256 hook_signal = hook_signal;
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
257 watchfd = watchfd;
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
258 }