RequestServer

A server control and configuration struct, as a potential alternative to calling GenericMain or cgiMainImpl. See the source of cgiMainImpl for a complete, up-to-date, example of how it is used internally.

As of version 11 (released August 2023), you can also make things like this:

// listens on both a unix domain socket called `foo` and on the loopback interfaces port 8080
RequestServer server = RequestServer(["http://unix:foo", "http://localhost:8080"]);

// can also:
// RequestServer server = RequestServer(0); // listen on an OS-provided port on all interfaces

// NOT IMPLEMENTED YET
// server.initialize(); // explicit initialization will populate any "any port" things and throw if a bind failed

foreach(listenSpec; server.listenSpecs) {
	// you can check what it actually bound to here and see your assigned ports
}

// NOT IMPLEMENTED YET
// server.start!handler(); // starts and runs in the arsd.core event loop

server.serve!handler(); // blocks the thread until the server exits

struct RequestServer {

string listeningHost;

ushort listeningPort;

string[] listenSpec;

bool useFork;

int numberOfThreads;

this(string[] listenTo);

this(string defaultHost, ushort defaultPort);

this(ushort defaultPort);

void configureFromCommandLine(string[] args);

uid_t privilegesDropToUid;

gid_t privilegesDropToGid;

void serveHttpOnce();

void serve();

void serveEmbeddedHttp(ThisFor!fun _this);

void serveScgi();

void serveSingleHttpConnectionOnStdio();

enum ForceStop;

version(!embedded_httpd_processes)

static void stop(ForceStop stopPriority);

}

Constructors

this this(string[] listenTo): Creates a server configured to listen to multiple URLs.
this this(string defaultHost, ushort defaultPort)
this(ushort defaultPort): Creates a server object configured to listen on a single host and port.

Members

Enums

ForceStop enum ForceStop: The stop function sets a flag that request handlers can (and should) check periodically. If a handler doesn't respond to this flag, the library will force the issue. This determines when and how the issue will be forced.

Functions

configureFromCommandLine void configureFromCommandLine(string[] args): Reads the command line arguments into the values here.
serve void serve(): Starts serving requests according to the current configuration.
serveEmbeddedHttp void serveEmbeddedHttp(ThisFor!fun _this): Runs the embedded HTTP thread server specifically, regardless of which build configuration you have.
serveHttpOnce void serveHttpOnce(): Serves a single HTTP request on this thread, with an embedded server, then stops. Designed for cases like embedded oauth responders
serveScgi void serveScgi(): Runs the embedded SCGI server specifically, regardless of which build configuration you have.
serveSingleHttpConnectionOnStdio void serveSingleHttpConnectionOnStdio(): Serves a single "connection", but the connection is spoken on stdin and stdout instead of on a socket.

Static functions

stop void stop(ForceStop stopPriority): Stops serving after the current requests are completed.

Variables

listenSpec string[] listenSpec;: The array of addresses you want to listen on. The format looks like a url but has a few differences.
listeningHost string listeningHost;
listeningPort ushort listeningPort;: Sets the host and port the server will listen on. This is semi-deprecated; the new (as of July 31, 2023) listenSpec parameter obsoletes these. You cannot use both together; the listeningHost and listeningPort are ONLY used if listenSpec is null.
numberOfThreads int numberOfThreads;: Determines the number of worker threads to spawn per process, for server modes that use worker threads. 0 will use a default based on the number of cpus modified by the server mode.
privilegesDropToGid gid_t privilegesDropToGid;: group (gid) to drop privileges to 0 … do nothing
privilegesDropToUid uid_t privilegesDropToUid;: user (uid) to drop privileges to 0 … do nothing
useFork bool useFork;: Uses a fork() call, if available, to provide additional crash resiliency and possibly improved performance. On the other hand, if you fork, you must not assume any memory is shared between requests (you shouldn't be anyway though! But if you have to, you probably want to set this to false and use an explicit threaded server with serveEmbeddedHttp) and stop may not work as well.