Struct soup::Server

pub struct Server { /* private fields */ }

A HTTP server.

#SoupServer implements a simple HTTP server.

To begin, create a server using Server::new(). Add at least one handler by calling ServerExtManual::add_handler() or ServerExtManual::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 None) for the path.)

When a new connection is accepted (or a new request is started on an existing persistent connection), the #SoupServer will emit 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 ServerMessage signals.

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

After checking for authorization, #SoupServer will look for “early” handlers (added with ServerExtManual::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 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 Status::NotFound to the client.

Otherwise (assuming no previous step assigned a status to the message) any “normal” handlers (added with ServerExtManual::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 Status::SwitchingProtocols or Status::BadRequest accordingly.

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

Finally, the server will emit request-finished (or 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 tls-certificate property.

Once the server is set up, make one or more calls to ServerExt::listen(), ServerExt::listen_local(), or ServerExt::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 glib::MainContext.

Properties

raw-paths

If true, percent-encoding in the Request-URI path will not be automatically decoded.

Readable | Writeable | Construct Only

server-header

Server header.

If non-None, the value to use for the “Server” header on ServerMessages processed by this server.

The Server header is the server equivalent of the User-Agent header, and provides information about the server and its components. It contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although “-”, “_”, and “.” are also allowed), and may optionally include a “/” followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.

Some HTTP server implementations intentionally do not use version numbers in their Server header, so that installations running older versions of the server don’t end up advertising their vulnerability to specific security holes.

As with user_agent, if you set a server-header property that has trailing whitespace, #SoupServer will append its own product token (eg, libsoup/2.3.2) to the end of the header for you.

Readable | Writeable | Construct

tls-auth-mode

A gio::TlsAuthenticationMode for SSL/TLS client authentication.

Readable | Writeable | Construct

tls-certificate

A gio::TlsCertificate[] that has a private-key set.

If this is set, then the server will be able to speak https in addition to (or instead of) plain http.

Readable | Writeable | Construct

tls-database

A gio::TlsDatabase to use for validating SSL/TLS client certificates.

Readable | Writeable | Construct

Signals

request-aborted

Emitted when processing has failed for a message.

This could mean either that it could not be read (if request-read has not been emitted for it yet), or that the response could not be written back (if request-read has been emitted but request-finished has not been).

@message is in an undefined state when this signal is emitted; the signal exists primarily to allow the server to free any state that it may have allocated in request-started.

request-finished

Emitted when the server has finished writing a response to a request.

request-read

Emitted when the server has successfully read a request.

@message will have all of its request-side information filled in, and if the message was authenticated, @client will have information about that. This signal is emitted before any (non-early) handlers are called for the message, and if it sets the message’s #status_code, then normal handler processing will be skipped.

request-started

Emitted when the server has started reading a new request.

@message will be completely blank; not even the Request-Line will have been read yet. About the only thing you can usefully do with it is connect to its signals.

If the request is read successfully, this will eventually be followed by a request_read signal]. If a response is then sent, the request processing will end with a request-finished signal. If a network error occurs, the processing will instead end with request-aborted.

Implements

ServerExt, [trait@glib::ObjectExt], ServerExtManual

Implementations

impl Server

pub const NONE: Option<&'static Server> = None

pub fn builder() -> ServerBuilder

Creates a new builder-pattern struct instance to construct Server objects.

This method returns an instance of ServerBuilder which can be used to create Server objects.

Trait Implementations

impl Clone for Server

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Server

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for Server

type ParamSpec = ParamSpecObject

type SetValue = Server

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Server>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Server

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Server

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for Server

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Server

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Server

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Server

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Server