-
-
Notifications
You must be signed in to change notification settings - Fork 191
Expand file tree
/
Copy pathwebserver_runtime.hpp
More file actions
175 lines (157 loc) · 7.29 KB
/
Copy pathwebserver_runtime.hpp
File metadata and controls
175 lines (157 loc) · 7.29 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
/*
This file is part of libhttpserver
Copyright (C) 2011-2019 Sebastiano Merlino
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
USA
*/
#if !defined (_HTTPSERVER_HPP_INSIDE_) && !defined (HTTPSERVER_COMPILATION)
#error "Only <httpserver.hpp> or <httpserverpp> can be included directly."
#endif
// webserver_runtime.hpp -- event-loop, connection-management, and
// feature-reporting surface of class webserver.
//
// This header carries member DECLARATIONS (and a few inline getters)
// only; it is meant to be included from WITHIN the body of `class
// webserver` defined in httpserver/webserver.hpp. Including it in any
// other context produces a compile error (see the inner gate below).
//
// Keeping this surface in its own file lets the webserver.hpp class
// definition stay under the project-wide per-file line-count ceiling
// (FILE_LOC_MAX in scripts/check-file-size.sh) without splitting the
// public class across translation units.
#ifndef SRC_HTTPSERVER_WEBSERVER_RUNTIME_HPP_
#define SRC_HTTPSERVER_WEBSERVER_RUNTIME_HPP_
#ifndef SRC_HTTPSERVER_WEBSERVER_HPP_INSIDE_CLASS_
#error "httpserver/webserver_runtime.hpp must be included from inside the webserver class body in <httpserver/webserver.hpp>."
#endif
/**
* Stop the webserver and wait for in-flight handlers to complete
* before returning.
*
* The wait guarantee is provided by @c MHD_stop_daemon(), which is a
* blocking call that drains all active connections and joins
* libmicrohttpd's worker threads before returning. @c stop() calls
* @c MHD_stop_daemon() internally, and this wrapper delegates to it,
* so the two entry-points are behaviourally equivalent today.
* @c stop_and_wait() exists as a semantically richer named entry-point;
* any future quiesce or application-level waiting logic should be added
* here rather than in @c stop().
*
* @see stop()
**/
void stop_and_wait();
/**
* Run the webserver's event loop once (non-blocking).
* For use with external event loops when the server is started
* without internal threading.
* @return true on success, false on error
* @note Handler exceptions are caught on the dispatch path and
* routed through `internal_error_handler`; no exception
* propagates out of this call.
* @see webserver (handler error-propagation contract)
**/
bool run();
/**
* Run the webserver's event loop, blocking until there is activity
* or the timeout expires.
* @param millisec timeout in milliseconds (-1 for indefinite)
* @return true on success, false on error
* @note Handler exceptions are caught on the dispatch path and
* routed through `internal_error_handler`; no exception
* propagates out of this call.
* @see webserver (handler error-propagation contract)
**/
bool run_wait(int32_t millisec);
/**
* Get the file descriptor sets for select()-based event loop integration.
* `fd_set` is a typedef (anonymous-struct in glibc), so the public header
* includes the platform header that defines it rather than relying on a
* forward declaration. The typed parameters restore compile-time type
* safety: the compiler rejects non-fd_set* arguments that the previous
* void* signature silently accepted (CWE-704).
* @param read_fd_set set of FDs to watch for reading
* @param write_fd_set set of FDs to watch for writing
* @param except_fd_set set of FDs to watch for exceptions
* @param max_fd highest FD number set in any of the sets
* @return true on success, false on error
**/
bool get_fdset(fd_set* read_fd_set, fd_set* write_fd_set,
fd_set* except_fd_set, int* max_fd);
/**
* Get the timeout until the next MHD action is needed.
* @param timeout output: timeout in milliseconds
* @return true if a timeout was set, false if no timeout is needed
**/
bool get_timeout(uint64_t* timeout);
/**
* Add an externally-accepted socket connection.
* `addrlen` is typed as `unsigned int` rather than `socklen_t` so
* this header does not have to include the BSD-socket header.
* `socklen_t` is a 32-bit integer on every supported platform
* (unsigned on POSIX, signed `int` on Windows winsock2); `unsigned
* int` is at least as wide as either, so the conversion in the
* implementation is value-preserving for any realistic `sockaddr`
* length. The implementation passes the value directly to
* MHD_add_connection.
* @param client_socket the accepted client socket
* @param addr the client address (forward-declared `struct sockaddr*`)
* @param addrlen length of the address (in bytes)
* @return true on success, false on error
**/
bool add_connection(int client_socket, const struct sockaddr* addr, unsigned int addrlen);
/**
* Quiesce the daemon: stop accepting new connections while letting
* in-flight requests complete.
* @return the listen socket FD (caller can close it), or -1 on error
**/
int quiesce();
/**
* Get the listen socket file descriptor.
* @return the listen FD, or -1 if not available
**/
int get_listen_fd() const;
/**
* Get the number of currently active connections.
* @return active connection count
**/
unsigned int get_active_connections() const;
/**
* Get the actual port the daemon is bound to.
* Useful when port 0 was specified to let the OS choose.
* @return the bound port, or 0 if not available
**/
uint16_t get_bound_port() const;
/**
* Reports build-time feature availability.
*
* The four boolean fields of the returned struct reflect the
* HAVE_BAUTH / HAVE_DAUTH / HAVE_GNUTLS / HAVE_WEBSOCKET macros at
* the time libhttpserver was compiled. Use this at runtime to
* decide whether to register a feature-dependent handler or to
* surface the configuration to the operator.
*
* The values are determined at library build time (not consumer
* build time): linking against a TLS-disabled libhttpserver always
* reports `tls == false`, even when the consumer TU was compiled
* with HAVE_GNUTLS defined.
*
* Safe to call before start() and from any thread; never throws.
**/
struct features {
bool basic_auth;
bool digest_auth;
bool tls;
bool websocket;
};
static features features() noexcept;
#endif // SRC_HTTPSERVER_WEBSERVER_RUNTIME_HPP_