Crate preroll

Easy boilerplate utilities for Rust http services which use async-std, Tide, Surf, and friends.

This crate is intentionally somewhat prescrptive in how it templates a service and the interaction with add-on features such as Postgres (via SQLx).

Scroll to the bottom for API Reference

Features

• Boilerplate main setup via preroll::main!, with optional features automatically configured.
• A preroll::prelude::*; with all extension traits.
• Response logging with many details.
• Automatic JSON reponses for errors.
• Test utils with easy mock client setup.

Optional features

Add-on features must be enabled via cargo features, e.g.

[dependencies.preroll]
version = "0.1"
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 to info.
  • Writes to a dataset named {service_name}-{environment}.
    • service_name is from preroll::main!("service_name", ...).
    • environment is from ENVIRONMENT, or defaults to "development".
• "postgres": Enables a postgres connection pool with transactions.
  • Env variable PGURL, which should be a properly formatted postgres:// database url.
    • Defaults to "postgres://localhost/{service_name}" (default postgres port).
    • service_name is from preroll::main!("service_name", ...).
  • Env variable PGMAXCONNECTIONS, default 5 connections.
  • Enables PostgresRequestExt and test_utils::create_client_and_postgres.

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.

General Environment Settings

The following environment variables are read during preroll::main!:

• ENVIRONMENT: If this starts with prod, 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 to info in production-mode, debug in development-mode.
• PORT: Sets the port that this service will listen on. Defaults to 8080.

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)
        });
}

preroll::main!("hello-world", setup_app_state, setup_routes);

Modules

prelude	Auto-import of all preroll extension traits.
test_utils	Utilities for setting up mock clients and test servers with similar features to preroll::main!
utils	Miscellaneous utilities.

Macros

main	A macro which constructs the equivalent of an async fn main().

Structs

JsonError

The structure of an error as formatted by preroll's error handling middleware.

Type Definitions

SetupResult

The result type which is expected from functions passed to preroll::main!.