preroll
Easy boilerplate utilities for Rust http services which use async-std, Tide, Surf, and friends.
Allows for service setup with feature-configured built-ins 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 Arc;
use ;
type AppRequest = ;
async
// The "magic" happens here!
main!;
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 responses 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.
[]
= "0.5"
= ["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
"lambda-http"
: Changes the HTTP listener to connect to an AWS Lambda execution environment.- Is no longer reachable as a regular http server, but accepts http lambda requests as if it were one.
- Some environment variables, such as
PORT
, are disregarded. - If the
"honeycomb"
feature is enabled, trace events are written to stdout, and must be collected via a layer provided by Honeycomb. See: https://docs.honeycomb.io/getting-data-in/integrations/aws/aws-lambda/
"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. - Env variable
PGMAXLIFETIME
, default30
(minutes). - Enables [
PostgresRequestExt
][prelude::PostgresRequestExt] and [test_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).
API Reference
License
Licensed under the BlueOak Model License 1.0.0 — Contributions via DCO 1.1