A HTTP server.
Server implements a simple HTTP server.
To begin, create a server using [[email protected]]. Add at least one handler by calling [[email protected]_handler] or [
[email protected]_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 Server
will emit [signal@Server: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 [class@ServerMessage] signals.
Once the headers have been read, Server will check if there is a [class@AuthDomain] `(qv)` covering the
Request-URI; if so, and if the message does not contain suitable authorization, then the [class@AuthDomain] will set a status of
soup_status_unauthorized on the message.
After checking for authorization, Server will look for "early" handlers (added with [
[email protected]_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 Server
will skip the remaining steps and return the response. If the request headers contain `Expect: 100-continue` and no status code
has been set, Server 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 [[email protected]_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), Server 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 [[email protected]_message]), 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 [signal@Server:SoupServer:request-finished] (or [signal@Server:
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 [
property@Server:tls-certificate] property.
Once the server is set up, make one or more calls to [[email protected]], [[email protected]_local], or [[email protected]_all]
to tell it where to listen for connections. (All ports on a Server 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 `SoupServer`s, or else check
the passed-in URI in the handler function.).
Server will begin processing connections as soon as you return to (or start) the main loop for the current
thread-default [[email protected]].
- public bool accept_iostream (IOStream stream, SocketAddress? local_addr, SocketAddress? remote_addr) throws Error
Adds a new client stream to the this
.
- public void add_auth_domain (AuthDomain auth_domain)
Adds an authentication domain to this
.
- public void add_early_handler (string? path, owned ServerCallback callback)
Adds an "early" handler to this for
requests prefixed by path.
- public void add_handler (string? path, owned ServerCallback callback)
Adds a handler to this for requests
prefixed by path.
- public void add_websocket_extension (Type extension_type)
Add support for a WebSocket extension of the given
extension_type.
- public void add_websocket_handler (string? path, string? origin, string[]? protocols, owned ServerWebsocketCallback callback)
Adds a WebSocket handler to this for
requests prefixed by path.
- public void disconnect ()
Closes and frees this's listening
sockets.
- public SList<unowned Socket> get_listeners ()
Gets this's list of listening
sockets.
- public TlsAuthenticationMode get_tls_auth_mode ()
Gets the this SSL/TLS client
authentication mode.
- public unowned TlsCertificate? get_tls_certificate ()
Gets the this SSL/TLS certificate.
- public unowned TlsDatabase? get_tls_database ()
Gets the this SSL/TLS database.
- public SList<Uri> get_uris ()
Gets a list of URIs corresponding to the interfaces
this is listening on.
- public bool is_https ()
Checks whether this is capable of
https.
- public bool listen (SocketAddress address, ServerListenOptions options) throws Error
Attempts to set up this to listen
for connections on address.
- public bool listen_all (uint port, ServerListenOptions options) throws Error
Attempts to set up this to listen
for connections on all interfaces on the system.
- public bool listen_local (uint port, ServerListenOptions options) throws Error
Attempts to set up this to listen
for connections on "localhost".
- public bool listen_socket (Socket socket, ServerListenOptions options) throws Error
Attempts to set up this to listen
for connections on socket.
- public void pause_message (ServerMessage msg)
Pauses I/O on msg.
- public void remove_auth_domain (AuthDomain auth_domain)
Removes auth_domain from this
.
- public void remove_handler (string path)
Removes all handlers (early and normal) registered at path
.
- public void remove_websocket_extension (Type extension_type)
Removes support for WebSocket extension of type extension_type
(or any subclass of extension_type) from this.
- public void set_tls_auth_mode (TlsAuthenticationMode mode)
Sets this's
TlsAuthenticationMode to use for SSL/TLS client authentication.
- public void set_tls_certificate (TlsCertificate certificate)
Sets this up to do https, using the
given SSL/TLS certificate.
- public void set_tls_database (TlsDatabase tls_database)
Sets this's
TlsDatabase to use for validating SSL/TLS client certificates.
- public void unpause_message (ServerMessage msg)
Resumes I/O on msg.