Struct tide_disco::app::Module

pub struct Module<'a, State, Error, ModuleError, ModuleVersion>
where
    State: Send + Sync + 'static,
    Error: Error + From<ModuleError> + 'static,
    ModuleError: Send + Sync + 'static,
    ModuleVersion: StaticVersionType + 'static,
{ /* private fields */ }

RAII guard to ensure a module is registered after it is configured.

This type allows the owner to configure an Api module via the Deref and DerefMut traits. Once the API is configured, this object can be dropped, which will automatically register the module with the App.

Panics

Note that if anything goes wrong during module registration (for example, there is already an incompatible module registered with the same name), the drop implementation may panic. To handle errors without panicking, call register explicitly.

Implementations

impl<'a, State, Error, ModuleError, ModuleVersion> Module<'a, State, Error, ModuleError, ModuleVersion>

where State: Send + Sync + 'static, Error: Error + From<ModuleError> + 'static, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

pub fn register(self) -> Result<(), AppError>

Register this module with the linked app.

Methods from Deref<Target = Api<State, ModuleError, ModuleVersion>>

pub fn with_version(&mut self, version: Version) -> &mut Self

Set the API version.

The version information will automatically be included in responses to GET /version. This version can also be used to serve multiple major versions of the same API simultaneously, under a version prefix. For more information, see App::register_module.

This is the version of the application or sub-application which this instance of Api represents. The versioning corresponds to the API specification passed to new, and may be different from the version of the Rust crate implementing the route handlers for the API.

pub fn with_public(&mut self, dir: PathBuf) -> &mut Self

Serve the contents of dir at the URL /public/{{NAME}}.

pub fn at<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &State) -> BoxFuture<'_, Result<T, Error>>, T: Serialize, State: 'static + Send + Sync, VER: 'static + Send + Sync,

Register a handler for a route.

When the server receives a request whose URL matches the pattern of the route name, handler will be invoked with the parameters of the request and a reference to the current state, and the result will be serialized into a response.

Examples

A simple getter route for a state object.

api.toml

[route.getstate]
PATH = ["/getstate"]
DOC = "Gets the current state."

use futures::FutureExt;

type State = u64;
type StaticVer01 = StaticVersion<0, 1>;

api.at("getstate", |req, state| async { Ok(*state) }.boxed());

A counter endpoint which increments a mutable state. Notice how we use METHOD = "POST" to ensure that the HTTP method for this route is compatible with mutable access.

api.toml

[route.increment]
PATH = ["/increment"]
METHOD = "POST"
DOC = "Increment the current state and return the new value."

use async_std::sync::Mutex;
use futures::FutureExt;

type State = Mutex<u64>;
type StaticVer01 = StaticVersion<0, 1>;

api.at("increment", |req, state| async {
    let mut guard = state.lock().await;
    *guard += 1;
    Ok(*guard)
}.boxed());

Warnings

The route will use the HTTP method specified in the TOML specification for the named route (or GET if the method is not specified). Some HTTP methods imply constraints on mutability. For example, GET routes must be “pure”, and not mutate any server state. Violating this constraint may lead to confusing and unpredictable behavior. If the State type has interior mutability (for instance, RwLock) it is up to the handler not to use the interior mutability if the HTTP method suggests it shouldn’t.

If you know the HTTP method when you are registering the route, we recommend you use the safer versions of this function, which enforce the appropriate mutability constraints. For example,

• get
• post
• put
• delete

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but it is not an HTTP route (for example, METHOD = "SOCKET" was used when defining the route in the API specification), ApiError::IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn get<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &<State as ReadState>::State) -> BoxFuture<'_, Result<T, Error>>, T: Serialize, State: 'static + Send + Sync + ReadState, VER: 'static + Send + Sync,

Register a handler for a GET route.

When the server receives a GET request whose URL matches the pattern of the route name, handler will be invoked with the parameters of the request and immutable access to the current state, and the result will be serialized into a response.

The ReadState trait is used to acquire immutable access to the state, so the state reference passed to handler is actually <State as ReadState>::State. For example, if State is RwLock<T>, the lock will automatically be acquired for reading, and the handler will be passed a &T.

Examples

A simple getter route for a state object.

api.toml

[route.getstate]
PATH = ["/getstate"]
DOC = "Gets the current state."

use async_std::sync::RwLock;
use futures::FutureExt;

type State = RwLock<u64>;
type StaticVer01 = StaticVersion<0, 1>;

api.get("getstate", |req, state| async { Ok(*state) }.boxed());

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not GET (that is, METHOD = "M" was used in the route definition in api.toml, with M other than GET) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn post<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &mut <State as ReadState>::State) -> BoxFuture<'_, Result<T, Error>>, T: Serialize, State: 'static + Send + Sync + WriteState, VER: 'static + Send + Sync,

Register a handler for a POST route.

When the server receives a POST request whose URL matches the pattern of the route name, handler will be invoked with the parameters of the request and exclusive, mutable access to the current state, and the result will be serialized into a response.

The WriteState trait is used to acquire mutable access to the state, so the state reference passed to handler is actually <State as ReadState>::State. For example, if State is RwLock<T>, the lock will automatically be acquired for writing, and the handler will be passed a &mut T.

Examples

A counter endpoint which increments the state and returns the new state.

api.toml

[route.increment]
PATH = ["/increment"]
METHOD = "POST"
DOC = "Increment the current state and return the new value."

use async_std::sync::RwLock;
use futures::FutureExt;

type State = RwLock<u64>;
type StaticVer01 = StaticVersion<0, 1>;

api.post("increment", |req, state| async {
    *state += 1;
    Ok(*state)
}.boxed());

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not POST (that is, METHOD = "M" was used in the route definition in api.toml, with M other than POST) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn put<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &mut <State as ReadState>::State) -> BoxFuture<'_, Result<T, Error>>, T: Serialize, State: 'static + Send + Sync + WriteState, VER: 'static + Send + Sync,

Register a handler for a PUT route.

When the server receives a PUT request whose URL matches the pattern of the route name, handler will be invoked with the parameters of the request and exclusive, mutable access to the current state, and the result will be serialized into a response.

The WriteState trait is used to acquire mutable access to the state, so the state reference passed to handler is actually <State as ReadState>::State. For example, if State is RwLock<T>, the lock will automatically be acquired for writing, and the handler will be passed a &mut T.

Examples

An endpoint which replaces the current state with a new value.

api.toml

[route.replace]
PATH = ["/replace/:new_state"]
METHOD = "PUT"
":new_state" = "Integer"
DOC = "Set the state to `:new_state`."

use async_std::sync::RwLock;
use futures::FutureExt;

type State = RwLock<u64>;
type StaticVer01 = StaticVersion<0, 1>;

api.post("replace", |req, state| async move {
    *state = req.integer_param("new_state")?;
    Ok(())
}.boxed());

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not PUT (that is, METHOD = "M" was used in the route definition in api.toml, with M other than PUT) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn delete<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &mut <State as ReadState>::State) -> BoxFuture<'_, Result<T, Error>>, T: Serialize, State: 'static + Send + Sync + WriteState, VER: 'static + Send + Sync,

Register a handler for a DELETE route.

When the server receives a DELETE request whose URL matches the pattern of the route name, handler will be invoked with the parameters of the request and exclusive, mutable access to the current state, and the result will be serialized into a response.

The WriteState trait is used to acquire mutable access to the state, so the state reference passed to handler is actually <State as ReadState>::State. For example, if State is RwLock<T>, the lock will automatically be acquired for writing, and the handler will be passed a &mut T.

Examples

An endpoint which clears the current state.

api.toml

[route.state]
PATH = ["/state"]
METHOD = "DELETE"
DOC = "Clear the state."

use async_std::sync::RwLock;
use futures::FutureExt;

type State = RwLock<Option<u64>>;
type StaticVer01 = StaticVersion<0, 1>;

api.delete("state", |req, state| async {
    *state = None;
    Ok(())
}.boxed());

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not DELETE (that is, METHOD = "M" was used in the route definition in api.toml, with M other than DELETE) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn socket<F, ToClient, FromClient>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, Connection<ToClient, FromClient, Error, VER>, &State) -> BoxFuture<'_, Result<(), Error>>, ToClient: 'static + Serialize + ?Sized, FromClient: 'static + DeserializeOwned, State: 'static + Send + Sync, Error: 'static + Send + Display,

Register a handler for a SOCKET route.

When the server receives any request whose URL matches the pattern for this route and which includes the WebSockets upgrade headers, the server will negotiate a protocol upgrade with the client, establishing a WebSockets connection, and then invoke handler. handler will be given the parameters of the request which initiated the connection and a reference to the application state, as well as a Connection object which it can then use for asynchronous, bi-directional communication with the client.

The server side of the connection will remain open as long as the future returned by handler is remains unresolved. The handler can terminate the connection by returning. If it returns an error, the error message will be included in the CloseFrame sent to the client when tearing down the connection.

Examples

A socket endpoint which receives amounts from the client and returns a running sum.

api.toml

[route.sum]
PATH = ["/sum"]
METHOD = "SOCKET"
DOC = "Stream a running sum."

use futures::{FutureExt, SinkExt, StreamExt};
use tide_disco::{error::ServerError, socket::Connection, Api};

api.socket("sum", |_req, mut conn: Connection<i32, i32, ServerError, StaticVersion<0, 1>>, _state| async move {
    let mut sum = 0;
    while let Some(amount) = conn.next().await {
        sum += amount?;
        conn.send(&sum).await?;
    }
    Ok(())
}.boxed());

In some cases, it may be desirable to handle messages to and from the client in separate tasks. There are two ways of doing this:

Split the connection into separate stream and sink

use async_std::task::spawn;
use futures::{future::{join, FutureExt}, sink::SinkExt, stream::StreamExt};
use tide_disco::{error::ServerError, socket::Connection, Api};

api.socket("endpoint", |_req, mut conn: Connection<i32, i32, ServerError, StaticVersion<0, 1>>, _state| async move {
    let (mut sink, mut stream) = conn.split();
    let recv = spawn(async move {
        while let Some(Ok(msg)) = stream.next().await {
            // Handle message from client.
        }
    });
    let send = spawn(async move {
        loop {
            let msg = // get message to send to client
            sink.send(msg).await;
        }
    });

    join(send, recv).await;
    Ok(())
}.boxed());

This approach requires messages to be sent to the client by value, consuming the message. This is because, if we were to use the Sync<&ToClient> implementation for Connection, the lifetime for &ToClient would be fixed after split is called, since the lifetime appears in the return type, SplitSink<Connection<...>, &ToClient>. Thus, this lifetime outlives any scoped local variables created after the split call, such as msg in the loop.

If we want to use the message after sending it to the client, we would have to clone it, which may be inefficient or impossible. Thus, there is another approach:

Clone the connection

use async_std::task::spawn;
use futures::{future::{join, FutureExt}, sink::SinkExt, stream::StreamExt};
use tide_disco::{error::ServerError, socket::Connection, Api};

api.socket("endpoint", |_req, mut conn: Connection<i32, i32, ServerError, StaticVersion<0, 1>>, _state| async move {
    let recv = {
        let mut conn = conn.clone();
        spawn(async move {
            while let Some(Ok(msg)) = conn.next().await {
                // Handle message from client.
            }
        })
    };
    let send = spawn(async move {
        loop {
            let msg = // get message to send to client
            conn.send(&msg).await;
            // msg is still live at this point.
            drop(msg);
        }
    });

    join(send, recv).await;
    Ok(())
}.boxed());

Depending on the exact situation, this method may end up being more verbose than the previous example. But it allows us to retain the higher-ranked trait bound conn: for<'a> Sink<&'a ToClient> instead of fixing the lifetime, which can prevent an unnecessary clone in certain situations.

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not SOCKET (that is, METHOD = "M" was used in the route definition in api.toml, with M other than SOCKET) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn stream<F, Msg>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &State) -> BoxStream<'_, Result<Msg, Error>>, Msg: 'static + Serialize + Send + Sync, State: 'static + Send + Sync, Error: 'static + Send + Display, VER: 'static + Send + Sync,

Register a uni-directional handler for a SOCKET route.

This function is very similar to socket, but it permits the handler only to send messages to the client, not to receive messages back. As such, the handler does not take a Connection. Instead, it simply returns a stream of messages which are forwarded to the client as they are generated. If the stream ever yields an error, the error is propagated to the client and then the connection is closed.

This function can be simpler to use than socket in case the handler does not need to receive messages from the client.

pub fn metrics<F, T>( &mut self, name: &str, handler: F, ) -> Result<&mut Self, ApiError>

where F: 'static + Send + Sync + Fn(RequestParams, &State::State) -> BoxFuture<'_, Result<Cow<'_, T>, Error>>, T: 'static + Clone + Metrics, State: 'static + Send + Sync + ReadState, Error: 'static, VER: 'static + Send + Sync,

Register a handler for a METRICS route.

When the server receives any request whose URL matches the pattern for this route and whose headers indicate it is a request for metrics, the server will invoke this handler instead of the regular HTTP handler for the endpoint. Instead of returning a typed object to serialize, handler will return a Metrics object which will be serialized to plaintext using the Prometheus format.

A request is considered a request for metrics, for the purpose of dispatching to this handler, if the method is GET and the Accept header specifies text/plain as a better response type than application/json and application/octet-stream (other Tide Disco handlers respond to the content types application/json or application/octet-stream). As a special case, a request with no Accept header or Accept: * will return metrics when there is a metrics route matching the request URL, since metrics are given priority over other content types when multiple routes match the URL.

Examples

A metrics endpoint which keeps track of how many times it has been called.

api.toml

[route.metrics]
PATH = ["/metrics"]
METHOD = "METRICS"
DOC = "Export Prometheus metrics."

use prometheus::{Counter, Registry};

struct State {
    counter: Counter,
    metrics: Registry,
}
type StaticVer01 = StaticVersion<0, 1>;

let mut api: Api<Mutex<State>, ServerError, StaticVer01>;
api.metrics("metrics", |_req, state| async move {
    state.counter.inc();
    Ok(Cow::Borrowed(&state.metrics))
}.boxed())?;

Errors

If the route name does not exist in the API specification, or if the route already has a handler registered, an error is returned. Note that all routes are initialized with a default handler that echoes parameters and shows documentation, but this default handler can replaced by this function without raising ApiError::HandlerAlreadyRegistered.

If the route name exists, but the method is not METRICS (that is, METHOD = "M" was used in the route definition in api.toml, with M other than METRICS) the error IncorrectMethod is returned.

Limitations

Like many function parameters in tide_disco, the handler function is required to return a [BoxFuture].

pub fn with_health_check<H>( &mut self, handler: impl 'static + Send + Sync + Fn(&State) -> BoxFuture<'_, H>, ) -> &mut Self

where State: 'static + Send + Sync, H: 'static + HealthCheck, VER: 'static + Send + Sync,

Set the health check handler for this API.

This overrides the existing handler. If health_check has not yet been called, the default handler is one which simply returns Health::default().

Trait Implementations

impl<'a, State, Error, ModuleError, ModuleVersion> Debug for Module<'a, State, Error, ModuleError, ModuleVersion>

where State: Send + Sync + 'static + Debug, Error: Error + From<ModuleError> + 'static + Debug, ModuleError: Send + Sync + 'static + Debug, ModuleVersion: StaticVersionType + 'static + Debug,

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

Formats the value using the given formatter.

impl<'a, State, Error, ModuleError, ModuleVersion> DerefMut for Module<'a, State, Error, ModuleError, ModuleVersion>

where State: Send + Sync + 'static, Error: Error + From<ModuleError> + 'static, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a, State, Error, ModuleError, ModuleVersion> Drop for Module<'a, State, Error, ModuleError, ModuleVersion>

where State: Send + Sync + 'static, Error: Error + From<ModuleError> + 'static, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, State, Error, ModuleError, ModuleVersion> Deref for Module<'a, State, Error, ModuleError, ModuleVersion>

where State: Send + Sync + 'static, Error: Error + From<ModuleError> + 'static, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

type Target = Api<State, ModuleError, ModuleVersion>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.