SoupServer

SoupServer provides a basic implementation of an HTTP server. The recommended usage of this server is for internal use, tasks like a mock server for tests, a private service for IPC, etc. It is not recommended to be exposed to untrusted clients as it may be vulnerable to denial of service attacks or other exploits.

To begin, create a server using soup_server_new(). Add at least one handler by calling soup_server_add_handler() or soup_server_add_early_handler(); the handler will be called to process any requests underneath the path you pass. (If you want all requests to go to the same handler, just pass “/” (or NULL) for the path.)

When a new connection is accepted (or a new request is started on an existing persistent connection), the SoupServer will emit SoupServer::request-started and then begin processing the request as described below, but note that once the message is assigned a status-code, then callbacks after that point will be skipped. Note also that it is not defined when the callbacks happen relative to various SoupServerMessage signals.

Once the headers have been read, SoupServer will check if there is a SoupAuthDomain (qv) covering the Request-URI; if so, and if the message does not contain suitable authorization, then the SoupAuthDomain will set a status of SOUP_STATUS_UNAUTHORIZED on the message.

After checking for authorization, SoupServer will look for “early” handlers (added with soup_server_add_early_handler()) matching the Request-URI. If one is found, it will be run; in particular, this can be used to connect to signals to do a streaming read of the request body.

(At this point, if the request headers contain Expect: 100-continue, and a status code has been set, then SoupServer will skip the remaining steps and return the response. If the request headers contain Expect: 100-continue and no status code has been set, SoupServer will return a SOUP_STATUS_CONTINUE status before continuing.)

The server will then read in the response body (if present). At this point, if there are no handlers at all defined for the Request-URI, then the server will return SOUP_STATUS_NOT_FOUND to the client.

Otherwise (assuming no previous step assigned a status to the message) any “normal” handlers (added with soup_server_add_handler()) for the message’s Request-URI will be run.

Then, if the path has a WebSocket handler registered (and has not yet been assigned a status), SoupServer will attempt to validate the WebSocket handshake, filling in the response and setting a status of SOUP_STATUS_SWITCHING_PROTOCOLS or SOUP_STATUS_BAD_REQUEST accordingly.

If the message still has no status code at this point (and has not been paused with soup_server_message_pause()), then it will be given a status of SOUP_STATUS_INTERNAL_SERVER_ERROR (because at least one handler ran, but returned without assigning a status).

Finally, the server will emit SoupServer::request-finished (or SoupServer::request-aborted if an I/O error occurred before handling was completed).

If you want to handle the special “” URI (eg, “OPTIONS “), you must explicitly register a handler for “*”; the default handler will not be used for that case.

If you want to process https connections in addition to (or instead of) http connections, you can set the SoupServer:tls-certificate property.

Once the server is set up, make one or more calls to soup_server_listen(), soup_server_listen_local(), or soup_server_listen_all() to tell it where to listen for connections. (All ports on a SoupServer use the same handlers; if you need to handle some ports differently, such as returning different data for http and https, you’ll need to create multiple SoupServers, or else check the passed-in URI in the handler function.).

SoupServer will begin processing connections as soon as you return to (or start) the main loop for the current thread-default GMainContext.