Crate trillium_api 

An extractor-based API layer for trillium.

This crate provides api, which wraps an async function into a trillium Handler. The function receives a &mut Conn and an extracted value (deserialized body, shared state, route parameters, etc.) and returns any type that implements Handler.

use trillium_api::{api, Json};
use trillium::Conn;

/// An api handler that takes no input and returns a JSON response.
async fn hello(_conn: &mut Conn, _: ()) -> Json<&'static str> {
    Json("hello, world")
}

/// An api handler that deserializes a JSON body and echoes it back.
async fn echo(_conn: &mut Conn, Json(body): Json<trillium_api::Value>) -> Json<trillium_api::Value> {
    Json(body)
}

How it works

When a request arrives, api does three things:

1. Extract — calls TryFromConn on the second parameter to pull typed data out of the conn (body, state, headers, etc.)
2. Call — passes &mut Conn and the extracted value to your function
3. Run — takes whatever your function returned (which must implement Handler) and runs it on the conn

If extraction fails, your function is never called. Instead, the TryFromConn::Error type — which must itself implement Handler — is run on the conn, typically setting an error status.

Guide

Module	Topic
extractors	Pulling data out of requests — Body, Json, State, tuples
extractors::custom	Writing your own FromConn / TryFromConn implementations
return_types	What you can return from an api handler
error_handling	How extraction errors and Result return types work
recipes	Patterns and ideas: middleware, type aliases, and more

Extractors at a glance

Type	Extracts	Fallible?
()	Nothing (no-op)	No
Body<T>	Deserialized request body (content-type negotiated)	Yes
Json<T>	Deserialized request body (JSON only)	Yes
State<T>	A T from conn state (via take_state)	No*
String	Request body as a string	Yes
Vec<u8>	Request body as raw bytes	Yes
Headers	Clone of request headers	No
Method	The HTTP method	No
(A, B, ...)	Multiple extractors as a tuple (up to 12)	Depends

*State<T> returns None (halting the conn) if the state is missing.

Formats supported

This crate supports receiving application/json and application/x-www-form-urlencoded, gated on cargo features. Response serialization uses Accept header negotiation when Body<T> is used.

trillium-api does not enable any default features, but you likely want to select either serde_json or sonic-rs to get the most out of this crate. sonic-rs is faster, and the serde_json feature exists mostly for backwards compatability or for applications that cannot avoid compiling serde_json.

It is quite easy to add additional negotiated content types to this crate, so please open an issue if you need that.

cargo features

• forms: enable form-urlencoded content negotiation (request/response bodies)
• url: implement TryFromConn for url::Url
• serde_json: use serde_json for json bodies
• sonic-rs: use sonic-rs for json bodies

note that rustdocs on docs.rs are generated with the following features enabled: forms, url, sonic-rs

Modules

error_handling

Error handling

extractors

Extractors — pulling data out of Conns

recipes

Recipes

return_types

Return types — handlers all the way down

Macros

jsonsonic-rs

Construct a sonic_rs::Value from a JSON literal.

Structs

ApiHandler

An interface layer built on trillium

BeforeSend

Run a trillium::Handler in before_send

Body

Body extractor

CancelOnDisconnect

A struct that cancels a handler if the client disconnects.

Halt

a struct that halts the Conn handler sequence. see Conn::halt for more.

Jsonserde_json or sonic-rs

A newtype wrapper struct for any serde::Serialize type. Note that this currently must own the serializable type. Body extractor

State

State extractor

Valuesonic-rs

Represents any valid JSON value.

Enums

Error

A serde-serializable error

Traits

ApiConnExt

Extension trait that adds api methods to trillium::Conn

FromConn

A trait to extract content from Conns to be used as the second argument to an api handler. Implement this for your types.

TryFromConn

Like FromConn, but with an Error.

Functions

api

constructs a new ApiHandler from the provided async fn(&mut conn, TryFromConn) -> impl Handler

cancel_on_disconnect

Construct a new CancelOnDisconnect handler.

Type Aliases

Result

trait alias for a result with this crate’s Error