Crate preroll[−][src]
Easy boilerplate utilities for Rust http services which use async-std, Tide, Surf, and friends.
Allows for service setup with feature-configured builtins for maximum service consistency with low developer overhead, and for easily integration testing the service without using a live network.
Scroll to the bottom for API Reference
Example
use std::sync::Arc; use tide::{Request, Route}; struct AppState { greeting: &'static str, } type AppRequest = Request<Arc<AppState>>; async fn setup_app_state() -> preroll::SetupResult<AppState> { Ok(AppState { greeting: "Hello World!", }) } fn setup_routes(mut server: Route<'_, Arc<AppState>>) { server .at("hello-world") .get(|req: AppRequest| async move { Ok(req.state().greeting) }); } // The "magic" happens here! preroll::main!("hello-world", setup_app_state, setup_routes);
Features
- Boilerplate
main
setup viapreroll::main!
, with optional features automatically configured. - A
preroll::prelude::*;
with all extension traits. - Response logging with many details.
- Automatic JSON reponses for errors in the form of
JsonError
. - Test utils with easy mock client setup.
Optional features
Add-on features must be enabled via cargo features, e.g.
[dependencies.preroll]
version = "0.4"
features = ["honeycomb", "postgres"]
List of optional add-on features:
"honeycomb"
: Enables tracing to honeycomb.io.- Env variable
HONEYCOMBIO_WRITE_KEY
(required). - Env variable
TRACELEVEL
, sets the tracing level filter, defaults toinfo
. - Writes to a dataset named
{service_name}-{environment}
.service_name
is frompreroll::main!("service_name", ...)
.environment
is fromENVIRONMENT
, or defaults to"development"
.
- Env variable
"postgres"
: Enables a postgres connection pool with transactions.- Env variable
PGURL
, which should be a properly formattedpostgres://
database url.- Defaults to
"postgres://localhost/{service_name}"
(default postgres port). service_name
is frompreroll::main!("service_name", ...)
.
- Defaults to
- Env variable
PGMAXCONNECTIONS
, default 5 connections. - Enables
PostgresRequestExt
andtest_utils::create_client_and_postgres
.
- Env variable
List of other optional features:
"panic-on-error"
: Makes the response logger panic on error rather than log.- Do not use in production. Prevents
--release
compilation.
- Do not use in production. Prevents
General Environment Settings
The following environment variables are read during preroll::main!
:
ENVIRONMENT
: If this starts withprod
, load the production-mode JSON logger, avoid.env
.FORCE_DOTENV
: Override production-mode, force-load environment from.env
.HOST
: Sets the hostname that this service will listen on. Defaults to"127.0.0.1"
.LOGLEVEL
: Set the logger’s level filter, defaults toinfo
in production-mode,debug
in development-mode.PORT
: Sets the port that this service will listen on. Defaults to8080
.
Note:
This crate is intentionally somewhat prescriptive in how it templates a service and the interaction with add-on features such as Postgres (via SQLx).
Modules
prelude | Auto-import of all preroll extension traits. |
test_utils | Utilities for setting up mock clients and test servers with similar features to |
utils | Miscellaneous utilities. |
Macros
main | Begin here. A macro which constructs the equivalent of an |
Structs
JsonError | The structure of an error as formatted by preroll’s error handling middleware. |
VariadicRoutes | Variadic-argument route versioning is implemented via this struct for |
Type Definitions
SetupResult | The result type which is expected from functions passed to |