prosody
9232305618ac
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 @ 8824:9232305618ac

.luacheckrc: Remove mod_pubsub/pubsub.lib.lua from files excluded from checks
author Kim Alvefur <zash@zash.se>
date Wed, 23 May 2018 15:02:55 +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 }