libhttpserver/src/httpserver/webserver_runtime.hpp at master · etr/libhttpserver · GitHub

History

175 lines (157 loc) · 7.29 KB

Raw

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

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_

libhttpserver/src/httpserver/webserver_runtime.hpp at master · etr/libhttpserver · GitHub

Uh oh!

Expand file tree

Breadcrumbs

webserver_runtime.hpp

Latest commit

History

Breadcrumbs

webserver_runtime.hpp

File metadata and controls