Trait soup::prelude::ServerExtManual

pub trait ServerExtManual: IsA<Server> + Sealed + 'static {
    // Provided methods
    fn add_early_handler<P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static>(
        &self,
        path: Option<&str>,
        callback: P
    ) { ... }
    fn add_handler<P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static>(
        &self,
        path: Option<&str>,
        callback: P
    ) { ... }
    fn add_websocket_handler<P: Fn(&Server, &ServerMessage, &str, &WebsocketConnection) + 'static>(
        &self,
        path: Option<&str>,
        origin: Option<&str>,
        protocols: &[&str],
        callback: P
    ) { ... }
}

Provided Methods

fn add_early_handler<P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static>( &self, path: Option<&str>, callback: P )

Adds an “early” handler to @self for requests prefixed by @path.

Note that “normal” and “early” handlers are matched up together, so if you add a normal handler for “/foo” and an early handler for “/foo/bar”, then a request to “/foo/bar” (or any path below it) will run only the early handler. (But if you add both handlers at the same path, then both will get run.)

For requests under @path (that have not already been assigned a status code by a AuthDomain or a signal handler), @callback will be invoked after receiving the request headers, but before receiving the request body; the message’s method and request-headers properties will be set.

Early handlers are generally used for processing requests with request bodies in a streaming fashion. If you determine that the request will contain a message body, normally you would call MessageBody::set_accumulate() on the message’s request-body to turn off request-body accumulation, and connect to the message’s got-chunk signal to process each chunk as it comes in.

To complete the message processing after the full message body has been read, you can either also connect to got-body, or else you can register a non-early handler for @path as well. As long as you have not set the status-code by the time got-body is emitted, the non-early handler will be run as well.

path

the toplevel path for the handler

callback

callback to invoke for requests under @path

fn add_handler<P: Fn(&Server, &ServerMessage, &str, HashMap<&str, &str>) + 'static>( &self, path: Option<&str>, callback: P )

Adds a handler to @self for requests prefixed by @path.

If @path is None or “/”, then this will be the default handler for all requests that don’t have a more specific handler. (Note though that if you want to handle requests to the special “” URI, you must explicitly register a handler for “”; the default handler will not be used for that case.)

For requests under @path (that have not already been assigned a status code by a AuthDomain, an early server handler, or a signal handler), @callback will be invoked after receiving the request body; the ServerMessage’s method, request-headers, and request-body properties will be set.

After determining what to do with the request, the callback must at a minimum call ServerMessage::set_status() on the message to set the response status code. Additionally, it may set response headers and/or fill in the response body.

If the callback cannot fully fill in the response before returning (eg, if it needs to wait for information from a database, or another network server), it should call ServerMessage::pause() to tell @self to not send the response right away. When the response is ready, call ServerMessage::unpause() to cause it to be sent.

To send the response body a bit at a time using “chunked” encoding, first call MessageHeaders::set_encoding() to set Encoding::Chunked on the response-headers. Then call MessageBody::append() (or MessageBody::append_bytes())) to append each chunk as it becomes ready, and ServerMessage::unpause() to make sure it’s running. (The server will automatically pause the message if it is using chunked encoding but no more chunks are available.) When you are done, call MessageBody::complete() to indicate that no more chunks are coming.

path

the toplevel path for the handler

callback

callback to invoke for requests under @path

fn add_websocket_handler<P: Fn(&Server, &ServerMessage, &str, &WebsocketConnection) + 'static>( &self, path: Option<&str>, origin: Option<&str>, protocols: &[&str], callback: P )

Adds a WebSocket handler to @self for requests prefixed by @path.

If @path is None or “/”, then this will be the default handler for all requests that don’t have a more specific handler.

When a path has a WebSocket handler registered, @self will check incoming requests for WebSocket handshakes after all other handlers have run (unless some earlier handler has already set a status code on the message), and update the request’s status, response headers, and response body accordingly.

If @origin is non-None, then only requests containing a matching “Origin” header will be accepted. If @protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted. More complicated requirements can be handled by adding a normal handler to @path, and having it perform whatever checks are needed and setting a failure status code if the handshake should be rejected.

path

the toplevel path for the handler

origin

the origin of the connection

protocols

the protocols supported by this handler

callback

callback to invoke for successful WebSocket requests under @path

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Server>> ServerExtManual for O