preroll 0.1.0

Name reserved for a crate of prerolled Rust tools.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

[![preroll on crates.io](https://img.shields.io/crates/v/preroll)](https://crates.io/crates/preroll) [![Documentation (latest release)](https://docs.rs/preroll/badge.svg)](https://docs.rs/preroll/)

# 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.

```toml
[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

```rust
use std::sync::Arc;

use tide::{Request, Server};

struct AppState {
    greeting: &'static str,
}

type AppRequest = Request<Arc<AppState>>;

async fn setup_app_state() -> preroll::setup::Result<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);
```

[async-std]: https://async.rs/
[honeycomb.io]: https://www.honeycomb.io/
[SQLx]: https://github.com/launchbadge/sqlx#sqlx
[Surf]: https://github.com/http-rs/surf#surf
[Tide]: https://github.com/http-rs/tide#tide

## License

Licensed under the [BlueOak Model License 1.0.0](LICENSE.md) — _[Contributions via DCO 1.1](contributing.md#developers-certificate-of-origin)_