#tide #surf #sqlx #honeycomb

preroll

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

5 unstable releases

0.2.0 Jan 13, 2021
0.1.2 Jan 6, 2021
0.1.1 Dec 22, 2020
0.1.0 Dec 22, 2020
0.0.0 Dec 8, 2020

#89 in HTTP server

28 downloads per month

BlueOak-1.0.0

72KB
1.5K SLoC

preroll on crates.io Documentation (latest release)

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][prelude::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, Server};

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(server: &mut Server<Arc<AppState>>) {
    server
        .at("hello-world")
        .get(|req: AppRequest| async move {
            Ok(req.state().greeting)
        });
}

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

License

Licensed under the BlueOak Model License 1.0.0Contributions via DCO 1.1

Dependencies

~13–22MB
~446K SLoC