prosody
a19fdc6e4f09
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 @ 9117:a19fdc6e4f09

util.pubsub: Apply defaults metatable before config check (thanks pep.) Makes it so that the callback sees the default if it’s not in the form, which makes it easier to validate.
author Kim Alvefur <zash@zash.se>
date Sun, 05 Aug 2018 15:17:00 +0200
parent 8781:53178b6ba589
child 9295:6c7d2fb0d369
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
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 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
9 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10
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 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
13 - "*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
14 - "*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
15 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 --- Handle API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 local handle_mt = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 local handle_methods = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 handle_mt.__index = handle_methods;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 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
23 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 function handle_methods:setlistener(listeners)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 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
29 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 function handle_methods:ip()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 function handle_methods:starttls(sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 function handle_methods:write(data)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 function handle_methods:close()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 function handle_methods:pause()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 function handle_methods:resume()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 - 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
52 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 function handle_methods:socket()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 - 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
59 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 function handle_methods:ssl()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 --- Listeners API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65 local listeners = {}
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 --[[ connect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 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
69 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 function listeners.onconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 --[[ incoming
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74 Called when data is received
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 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
76 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77 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
78 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 --[[ status
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81 Known statuses:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82 - "ssl-handshake-complete"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 function listeners.onstatus(handle, status)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 --[[ disconnect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88 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
89 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
90 function listeners.ondisconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 --[[ drain
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94 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
95 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
96 function listeners.ondrain(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
97 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
99 --[[ readtimeout
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
100 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
101 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
102 function listeners.onreadtimeout(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
103 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
104
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
105 --[[ 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
106 Allows for clean-up
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
107 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
108 function listeners.ondetach(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
109 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
110
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
111 --- Top level functions
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 --[[ 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
114
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
115 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
116 - backend: e.g. "select", "epoll"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
117 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
118 local function get_backend()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
120
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
121 --[[ Starts the event loop.
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 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
124 - "quitting"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
125 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
126 local function loop()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
127 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
128
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
129 --[[ Stop a running loop()
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 local function setquitting(quit)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
132 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
133
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
134
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
135 --[[ 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
136
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
137 Arguments:
8728
41c959c5c84b Fix spelling throughout the codebase [codespell]
Kim Alvefur <zash@zash.se>
parents: 8532
diff changeset
138 - 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
139 - 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
140 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
141 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
142 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
143
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
144 --[[ 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
145 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
146
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
147 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
148 - 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
149 - 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
150 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
151 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
152 - 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
153
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
154 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
155 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
156 - 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
157 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
158 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
159 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
160
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
161 --[[ 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
162 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
163 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
164
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
165 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
166 - 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
167 - ip: returned by `handle:ip()`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
168 - port:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
169 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
170 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
171 - 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
172 - 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
173 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
174 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
175 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
176
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
177 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
178 - handle, socket
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
179 - 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
180 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
181 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
182 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
183
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
184 --[[ 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
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 - 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
189 - 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
190 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
191 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
192 - 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
193 - 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
194 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
195 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
196 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
197
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
198 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
199 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
200 - 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
201 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
202 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
203 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
204
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
205 --[[ Close all handles
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 local function closeall()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
208 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
209
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
210 --[[ 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
211 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
212 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
213
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
214 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
215 - 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
216 - callback: function to call.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
217 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
218 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
219 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
220
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
221 --[[ 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
222 Optional to implement
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
223 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
224
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
225 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
226 - 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
227 - handler: callback
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 hook_signal(signal_id, handler)
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
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
232 --[[ 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
233 Arguments:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
234 - 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
235 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
236 - 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
237 - 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
238
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
239 Returns:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
240 - net.server handle
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
241 ]]
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
242 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
243 end
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
244
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
245 return {
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
246 get_backend = get_backend;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
247 loop = loop;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
248 setquitting = setquitting;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
249 link = link;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
250 addserver = addserver;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
251 wrapclient = wrapclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
252 addclient = addclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
253 closeall = closeall;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
254 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
255 watchfd = watchfd;
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
256 }