1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup timeout Connection timeouts
26
27 APIs related to setting connection timeouts
28*/
29//@{
30
31#if defined(STANDALONE)
32struct lws_context_standalone;
33#define lws_context lws_context_standalone
34#endif
35
36/*
37 * NOTE: These public enums are part of the abi. If you want to add one,
38 * add it at where specified so existing users are unaffected.
39 */
40enum pending_timeout {
41 NO_PENDING_TIMEOUT = 0,
42 PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1,
43 PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2,
44 PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3,
45 PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4,
46 PENDING_TIMEOUT_AWAITING_PING = 5,
47 PENDING_TIMEOUT_CLOSE_ACK = 6,
48 PENDING_TIMEOUT_UNUSED1 = 7,
49 PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8,
50 PENDING_TIMEOUT_SSL_ACCEPT = 9,
51 PENDING_TIMEOUT_HTTP_CONTENT = 10,
52 PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11,
53 PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12,
54 PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13,
55 PENDING_TIMEOUT_CGI = 14,
56 PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15,
57 PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING = 16,
58 PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG = 17,
59 PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD = 18,
60 PENDING_TIMEOUT_AWAITING_SOCKS_GREETING_REPLY = 19,
61 PENDING_TIMEOUT_AWAITING_SOCKS_CONNECT_REPLY = 20,
62 PENDING_TIMEOUT_AWAITING_SOCKS_AUTH_REPLY = 21,
63 PENDING_TIMEOUT_KILLED_BY_SSL_INFO = 22,
64 PENDING_TIMEOUT_KILLED_BY_PARENT = 23,
65 PENDING_TIMEOUT_CLOSE_SEND = 24,
66 PENDING_TIMEOUT_HOLDING_AH = 25,
67 PENDING_TIMEOUT_UDP_IDLE = 26,
68 PENDING_TIMEOUT_CLIENT_CONN_IDLE = 27,
69 PENDING_TIMEOUT_LAGGING = 28,
70 PENDING_TIMEOUT_THREADPOOL = 29,
71 PENDING_TIMEOUT_THREADPOOL_TASK = 30,
72 PENDING_TIMEOUT_KILLED_BY_PROXY_CLIENT_CLOSE = 31,
73 PENDING_TIMEOUT_USER_OK = 32,
74
75 /****** add new things just above ---^ ******/
76
77 PENDING_TIMEOUT_USER_REASON_BASE = 1000
78};
79
80#define lws_time_in_microseconds lws_now_usecs
81
82#define LWS_TO_KILL_ASYNC -1
83/**< If LWS_TO_KILL_ASYNC is given as the timeout sec in a lws_set_timeout()
84 * call, then the connection is marked to be killed at the next timeout
85 * check. This is how you should force-close the wsi being serviced if
86 * you are doing it outside the callback (where you should close by nonzero
87 * return).
88 */
89#define LWS_TO_KILL_SYNC -2
90/**< If LWS_TO_KILL_SYNC is given as the timeout sec in a lws_set_timeout()
91 * call, then the connection is closed before returning (which may delete
92 * the wsi). This should only be used where the wsi being closed is not the
93 * wsi currently being serviced.
94 */
95/**
96 * lws_set_timeout() - marks the wsi as subject to a timeout some seconds hence
97 *
98 * \param wsi: Websocket connection instance
99 * \param reason: timeout reason
100 * \param secs: how many seconds. You may set to LWS_TO_KILL_ASYNC to
101 * force the connection to timeout at the next opportunity, or
102 * LWS_TO_KILL_SYNC to close it synchronously if you know the
103 * wsi is not the one currently being serviced.
104 */
105LWS_VISIBLE LWS_EXTERN void
106lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
107
108/**
109 * lws_set_timeout_us() - marks the wsi as subject to a timeout some us hence
110 *
111 * \param wsi: Websocket connection instance
112 * \param reason: timeout reason
113 * \param us: 0 removes the timeout, otherwise number of us to wait
114 *
115 * Higher-resolution version of lws_set_timeout(). Actual resolution depends
116 * on platform and load, usually ms.
117 */
118void
119lws_set_timeout_us(struct lws *wsi, enum pending_timeout reason, lws_usec_t us);
120
121/* helper for clearer LWS_TO_KILL_ASYNC / LWS_TO_KILL_SYNC usage */
122#define lws_wsi_close(w, to_kill) lws_set_timeout(w, 1, to_kill)
123
124
125#define LWS_SET_TIMER_USEC_CANCEL ((lws_usec_t)-1ll)
126#define LWS_USEC_PER_SEC ((lws_usec_t)1000000)
127
128/**
129 * lws_set_timer_usecs() - schedules a callback on the wsi in the future
130 *
131 * \param wsi: Websocket connection instance
132 * \param usecs: LWS_SET_TIMER_USEC_CANCEL removes any existing scheduled
133 * callback, otherwise number of microseconds in the future
134 * the callback will occur at.
135 *
136 * NOTE: event loop support for this:
137 *
138 * default poll() loop: yes
139 * libuv event loop: yes
140 * libev: not implemented (patch welcome)
141 * libevent: not implemented (patch welcome)
142 *
143 * After the deadline expires, the wsi will get a callback of type
144 * LWS_CALLBACK_TIMER and the timer is exhausted. The deadline may be
145 * continuously deferred by further calls to lws_set_timer_usecs() with a later
146 * deadline, or cancelled by lws_set_timer_usecs(wsi, -1).
147 *
148 * If the timer should repeat, lws_set_timer_usecs() must be called again from
149 * LWS_CALLBACK_TIMER.
150 *
151 * Accuracy depends on the platform and the load on the event loop or system...
152 * all that's guaranteed is the callback will come after the requested wait
153 * period.
154 */
155LWS_VISIBLE LWS_EXTERN void
156lws_set_timer_usecs(struct lws *wsi, lws_usec_t usecs);
157
158struct lws_sorted_usec_list;
159
160typedef void (*sul_cb_t)(struct lws_sorted_usec_list *sul);
161
162typedef struct lws_sorted_usec_list {
163 struct lws_dll2 list; /* simplify the code by keeping this at start */
164 lws_usec_t us;
165 sul_cb_t cb;
166 uint32_t latency_us; /* us it may safely be delayed */
167} lws_sorted_usec_list_t;
168
169/*
170 * There are multiple sul owners to allow accounting for, a) events that must
171 * wake from suspend, and b) events that can be missued due to suspend
172 */
173#define LWS_COUNT_PT_SUL_OWNERS 2
174
175#define LWSSULLI_MISS_IF_SUSPENDED 0
176#define LWSSULLI_WAKE_IF_SUSPENDED 1
177
178/*
179 * lws_sul2_schedule() - schedule a callback
180 *
181 * \param context: the lws_context
182 * \param tsi: the thread service index (usually 0)
183 * \param flags: LWSSULLI_...
184 * \param sul: pointer to the sul element
185 *
186 * Generic callback-at-a-later time function. The callback happens on the
187 * event loop thread context.
188 *
189 * Although the api has us resultion, the actual resolution depends on the
190 * platform and may be, eg, 1ms.
191 *
192 * This doesn't allocate and doesn't fail.
193 *
194 * If flags contains LWSSULLI_WAKE_IF_SUSPENDED, the scheduled event is placed
195 * on a sul owner list that, if the system has entered low power suspend mode,
196 * tries to arrange that the system should wake from platform suspend just
197 * before the event is due. Scheduled events without this flag will be missed
198 * in the case the system is in suspend and nothing else happens to have woken
199 * it.
200 *
201 * You can call it again with another us value to change the delay or move the
202 * event to a different owner (ie, wake or miss on suspend).
203 */
204LWS_VISIBLE LWS_EXTERN void
205lws_sul2_schedule(struct lws_context *context, int tsi, int flags,
206 lws_sorted_usec_list_t *sul);
207
208/*
209 * lws_sul_cancel() - cancel scheduled callback
210 *
211 * \param sul: pointer to the sul element
212 *
213 * If it's scheduled, remove the sul from its owning sorted list.
214 * If not scheduled, it's a NOP.
215 */
216LWS_VISIBLE LWS_EXTERN void
217lws_sul_cancel(lws_sorted_usec_list_t *sul);
218
219/*
220 * lws_sul_earliest_wakeable_event() - get earliest wake-from-suspend event
221 *
222 * \param ctx: the lws context
223 * \param pearliest: pointer to lws_usec_t to take the result
224 *
225 * Either returns 1 if no pending event, or 0 and sets *pearliest to the
226 * MONOTONIC time of the current earliest next expected event.
227 */
228LWS_VISIBLE LWS_EXTERN int
229lws_sul_earliest_wakeable_event(struct lws_context *ctx, lws_usec_t *pearliest);
230
231/*
232 * For backwards compatibility
233 *
234 * If us is LWS_SET_TIMER_USEC_CANCEL, the sul is removed from the scheduler.
235 * New code can use lws_sul_cancel()
236 */
237
238LWS_VISIBLE LWS_EXTERN void
239lws_sul_schedule(struct lws_context *ctx, int tsi, lws_sorted_usec_list_t *sul,
240 sul_cb_t _cb, lws_usec_t _us);
241LWS_VISIBLE LWS_EXTERN void
242lws_sul_schedule_wakesuspend(struct lws_context *ctx, int tsi,
243 lws_sorted_usec_list_t *sul, sul_cb_t _cb,
244 lws_usec_t _us);
245
246#if defined(LWS_WITH_SUL_DEBUGGING)
247/**
248 * lws_sul_debug_zombies() - assert there are no scheduled sul in a given object
249 *
250 * \param ctx: lws_context
251 * \param po: pointer to the object that is about to be destroyed
252 * \param len: length of the object that is about to be destroyed
253 * \param destroy_description: string clue what any failure is related to
254 *
255 * This is an optional debugging helper that walks the sul scheduler lists
256 * confirming that there are no suls scheduled that live inside the object
257 * footprint described by po and len. When internal objects are about to be
258 * destroyed, like wsi / user_data or secure stream handles, if
259 * LWS_WITH_SUL_DEBUGGING is enabled the scheduler is checked for anything
260 * in the object being destroyed. If something found, an error is printed and
261 * an assert fired.
262 *
263 * Internal sul like timeouts should always be cleaned up correctly, but user
264 * suls in, eg, wsi user_data area, or in secure stream user allocation, may be
265 * the cause of difficult to find bugs if valgrind not available and the user
266 * code left a sul in the scheduler after destroying the object the sul was
267 * living in.
268 */
269LWS_VISIBLE LWS_EXTERN void
270lws_sul_debug_zombies(struct lws_context *ctx, void *po, size_t len,
271 const char *destroy_description);
272#else
273#define lws_sul_debug_zombies(_a, _b, _c, _d)
274#endif
275
276/*
277 * lws_validity_confirmed() - reset the validity timer for a network connection
278 *
279 * \param wsi: the connection that saw traffic proving the connection valid
280 *
281 * Network connections are subject to intervals defined by the context, the
282 * vhost if server connections, or the client connect info if a client
283 * connection. If the connection goes longer than the specified time since
284 * last observing traffic that can only happen if traffic is passing in both
285 * directions, then lws will try to create a PING transaction on the network
286 * connection.
287 *
288 * If the connection reaches the specified `.secs_since_valid_hangup` time
289 * still without any proof of validity, the connection will be closed.
290 *
291 * If the PONG comes, or user code observes traffic that satisfies the proof
292 * that both directions are passing traffic to the peer and calls this api,
293 * the connection validity timer is reset and the scheme repeats.
294 */
295LWS_VISIBLE LWS_EXTERN void
296lws_validity_confirmed(struct lws *wsi);
297
298/*
299 * These are not normally needed, they're exported for the case there's code
300 * using lws_sul for which lws is an optional link dependency.
301 */
302
303LWS_VISIBLE LWS_EXTERN int
304__lws_sul_insert(lws_dll2_owner_t *own, lws_sorted_usec_list_t *sul);
305
306LWS_VISIBLE LWS_EXTERN lws_usec_t
307__lws_sul_service_ripe(lws_dll2_owner_t *own, int own_len, lws_usec_t usnow);
308
309#if defined(STANDALONE)
310#undef lws_context
311#endif
312
313///@}
314