Annotate

doc/net.server.lua @ 12319:8fc3c06f922d

prosodyctl: check dns: List discovered addresses for diagnostic purposes It is very common to get the "unknown address" warning with this command, but people do not always understand it, or know how to debug it. Now we clearly show the addresses that prosodyctl discovered.
author Matthew Wild <mwild1@gmail.com>
date Wed, 02 Mar 2022 16:02:42 +0000
parent 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
9846
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
163 --[[ Binds and listens on the given address and port
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
164 Mostly the same as addserver but with all optional arguments in a table
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
165
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
166 Arguments:
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
167 - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
168 - port: port to bind (as number)
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
169 - listeners: a table of listeners
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
170 - config: table of extra settings
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
171 - read_size: the amount of bytes to read or a read pattern
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
172 - tls_ctx: is a valid luasec constructor
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
173 - tls_direct: boolean true for direct TLS, false (or nil) for starttls
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
174
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
175 Returns:
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
176 - handle
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
177 - nil, "an error message": on failure (e.g. out of file descriptors)
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
178 ]]
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
179 local function listen(address, port, listeners, config)
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
180 end
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
181
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
182
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
183 --[[ 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
184 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
185 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
186
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
187 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
188 - 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
189 - ip: returned by `handle:ip()`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
190 - port:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
191 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
192 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
193 - 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
194 - 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
195 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
196 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
197 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
198
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
199 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
200 - handle, socket
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
201 - 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
202 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
203 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
204 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
205
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
206 --[[ 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
207 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
208
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
209 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
210 - 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
211 - 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
212 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
213 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
214 - 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
215 - 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
216 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
217 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
218 - "udp"
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 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
221 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
222 - 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
223 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
224 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
225 end
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 --[[ Close all handles
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
228 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
229 local function closeall()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
230 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
231
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
232 --[[ 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
233 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
234 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
235
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
236 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
237 - 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
238 - callback: function to call.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
239 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
240 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
241 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
242
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
243 --[[ 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
244 Optional to implement
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
245 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
246
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
247 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
248 - 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
249 - handler: callback
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
250 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
251 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
252 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
253
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
254 --[[ 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
255 Arguments:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
256 - 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
257 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
258 - 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
259 - 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
260
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
261 Returns:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
262 - net.server handle
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
263 ]]
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
264 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
265 end
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
266
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
267 return {
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
268 get_backend = get_backend;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
269 loop = loop;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
270 setquitting = setquitting;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
271 link = link;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
272 addserver = addserver;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
273 wrapclient = wrapclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
274 addclient = addclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
275 closeall = closeall;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
276 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
277 watchfd = watchfd;
9846
9a0da809ed4a doc/net.server: Document the new server.listen() API
Kim Alvefur <zash@zash.se>
parents: 9295
diff changeset
278 listen = listen;
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
279 }