README.md

# mon

A Rust library that provides the common parts of a server on top of axum.
It brings a shared error type that answers in JSON, and extractors that also fail in JSON.
It also builds HTML, relays requests to another server, and keeps sessions in one of four stores.

Data is stored in SQLite through sqlx.

The Japanese documentation is in [README.ja.md](./README.ja.md).

## Usage

**mon claims no paths.**
The application decides what goes on which path, and whether to place anything at all.
`route::wrap` only applies the middleware and inserts the state; it adds no routes.

```
use axum::Router;
use axum::routing::get;
use mon::{AppState, conf, database, page, relay, route, server, session};
use std::sync::Arc;
use tokio::net::TcpListener;

let conf = Arc::new(conf::load()?); // building a Conf directly also works
let database = database::connect(&conf.database_url).await?;
let store = session::store(&conf, &database);
session::prepare(&store).await?;
session::start_sweep(store.clone(), conf.session_max_age);

// the names, and whether to place each part at all, are decided here
let routes = my_routes()
.route("/health", get(route::health))
.nest("/api/session", session::router())
.nest("/relay", relay::router())
.nest_service("/static", route::assets(&conf))
.fallback(page::not_found);

let state = AppState {
database,
client: relay::client(&conf)?,
session: store,
conf: conf.clone(),
};

// limits the time for receiving headers, and hands the TCP peer to ClientIp
let listener = TcpListener::bind((conf.host, conf.port)).await?;
server::run(listener, route::wrap(routes, state), &conf, shutdown).await?;
```

`shutdown` is a future that completes when the server should stop, such as on Ctrl+C or SIGTERM.
`server::run` then stops accepting and returns after the requests in progress finish.

If you want `/health` to be a page about a clinic's services, simply put that page there.
mon does not take the path first. `tests/collision.rs` checks this.

Names other than paths are not fixed either.
The cookie name comes from `SESSION_COOKIE`, the session table from `SESSION_TABLE`, the store directory from `SESSION_DIRECTORY`, and the request ID header from `REQUEST_ID_HEADER`.
Leave any of them empty and it is not used.

The application creates its own tables.
The only table mon creates is `session`, when the `sqlite` store is chosen, and `session::prepare` creates it with `create table if not exists`.
It does not mix into the application's migrations.

## Running

```
cargo run # mon alone, on http://localhost:3000
cargo run --example todo # an example with /api/todos and a list page
RUST_LOG=debug cargo run # more detailed logs
PORT=8080 cargo run # another port
cargo test # tests
cargo build --release # with LTO and strip
```

The crate uses edition 2024, so it needs rustc 1.85 or later.

## Building for Linux

In production, run the executable from a release build instead of `cargo run`.
No separate application server such as gunicorn is needed.
The executable contains the HTTP server itself (hyper, through `axum::serve`).
It runs on the multi-threaded tokio runtime, so one process uses every CPU core.

Build in the directory of your application that depends on mon.
In mon's own directory, the same commands build `src/main.rs`, which runs mon alone.

A build is native code for one operating system and one CPU.
An executable built on macOS runs only on macOS, so build one for the server.

On a Linux machine, `cargo build --release` is enough, and the executable appears in `target/release/`.

From macOS, cross-compile with cargo-zigbuild.
The bundled SQLite and the TLS library (aws-lc-sys) contain C code, so they need a C compiler for Linux, which zig provides.

```
brew install zig
cargo install cargo-zigbuild
rustup target add x86_64-unknown-linux-gnu
cargo zigbuild --release --target x86_64-unknown-linux-gnu
```

The executable appears in `target/x86_64-unknown-linux-gnu/release/`.
For an ARM server, use `aarch64-unknown-linux-gnu` instead.
Running `uname -m` on the server tells which one it is.
If the server says a `GLIBC` version is not found, add the server's glibc version to the target, as in `x86_64-unknown-linux-gnu.2.28`.
Running `ldd --version` on the server shows that version.

The release profile uses fat LTO and `codegen-units = 1`, so a build takes a lot of memory and CPU time.
Avoid building on a small server that is already answering requests.

## Running on a server

The server needs no Rust toolchain.
SQLite is compiled into the executable, so SQLite does not need to be installed either.
Copy the executable to the server, along with the static directory if `route::assets` serves one.

Run it under systemd, which starts it when the machine boots and starts it again whenever it stops.
The following is an example, where `app` stands for the name of your application.

```
[Unit]
Description=app
After=network.target

[Service]
User=app
WorkingDirectory=/srv/app
ExecStart=/srv/app/app
Environment=PORT=3000
Environment=SESSION_SECURE=true
Environment=CLIENT_IP_HEADER=x-forwarded-for
UMask=0077
Restart=always

[Install]
WantedBy=multi-user.target
```

```
sudo cp app.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now app
```

Always set `WorkingDirectory`.
By default, mon.db, `static` and `session` are looked up relative to the directory the process starts in.
Absolute paths can be given instead through `DATABASE_URL`, `STATIC_DIRECTORY` and `SESSION_DIRECTORY`.
The account in `User=` needs write access to that directory, because mon.db and its WAL files are created there.
`UMask=0077` makes mon.db, its WAL files and the session files readable only by that account.
Logs go to standard output, so `journalctl -u app` shows them.

To update, put the new executable next to the old one, rename it over the old one, and run `sudo systemctl restart app`.
Overwriting a running executable in place fails with "Text file busy".
rsync writes to a new file and then renames it, so it can be used as it is.
`systemctl restart` sends SIGTERM first.
`src/main.rs` passes Ctrl+C and SIGTERM to `server::run` as `shutdown`, so the requests in progress finish before the process exits.

Put a reverse proxy such as nginx in front to handle TLS.
Inside the server block for your domain, pass requests to mon like this.

```
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
```

With a single nginx, `CLIENT_IP_HEADER=x-forwarded-for` and `TRUSTED_PROXY=0` read the client IP correctly, as described under "Client IP".
`SESSION_SECURE=true` is needed because browsers reach the site over HTTPS.

mon listens on the address in `HOST`, which defaults to 127.0.0.1.
Requests that do not pass through the proxy therefore cannot reach it.
When the proxy runs on another machine or mon runs in a container, set `HOST=0.0.0.0` and let nothing but the proxy reach the port.
While `CLIENT_IP_HEADER` is set, a request that reaches the port directly can forge `X-Forwarded-For`.

Start your application with `server::run`, not `axum::serve`.
`axum::serve` sets no limit on the time for receiving headers, so a client that sends headers slowly, or connects and sends nothing, keeps the connection.
`server::run` closes such connections after `REQUEST_TIMEOUT`.

## Parts mon provides

The application decides where each part goes.
Paths that appear below assume the arrangement in the example above.

- `route::health` - returns only `{"status": "ok"}` and does not touch the database
- `session::router()` - reads with `GET`, writes with `POST`, and discards with `DELETE`
- `relay::router()` - relays `/` and everything under it
- `route::assets(&conf)` - a service that serves static files
- `page::not_found` - the HTML for a request that matches no route
- `server::run` - listens with a limit on the time for receiving headers, and stops after the requests in progress finish

Every error is JSON of the form `{"error": "..."}`. Panics and timeouts take the same form.
A timeout answers 503, not 408, because 408 would allow the client to send the same request again.
There are three exceptions. `page::not_found` returns HTML.
The 404 from `route::assets` and the 413 for a body over the limit are text/plain.
Both come from tower-http as they are.

## Environment variables

All of them are optional. They are read in one place, conf.rs.

An unset variable takes its default, but **a variable that is set and cannot be read stops the startup**.
Quietly falling back to the default would start the server on a port nobody asked for, and the process would run while the proxy in front sees 502, the hardest failure to track down.

mon stops with messages like these. They are written in Japanese.

```
PORT=800o -> PORT=800o を数として読めません（invalid digit found in string）
PORT=0 -> PORT=0 は 1 以上にしてください
CORS_CREDENTIALS=ture -> CORS_CREDENTIALS=ture は true か false で書いてください
```

Numeric settings do not accept 0, because `PORT=0` lets the OS pick any free port.
Only two accept 0: `CORS_MAX_AGE`, where it means preflights are not cached, and `TRUSTED_PROXY`, where it means nothing is skipped.

- `PORT` - the port to listen on. Default 3000
- `HOST` - the address to listen on. Default 127.0.0.1, which only the same machine can reach
- `DATABASE_URL` - where the SQLite database is. Default `sqlite:mon.db`
- `STATIC_DIRECTORY` - the directory of static files. Default `static`
- `STATIC_CACHE_CONTROL` - the Cache-Control sent with static files. Default `no-cache`. Empty sends none
- `RELAY_ORIGIN` - the origin the relay forwards to. Default `http://localhost:6060`
- `CORS_ORIGIN` - allowed origins, separated by commas. Empty allows every origin
- `CORS_METHOD` - allowed methods, separated by commas. Empty leaves it to the defaults
- `CORS_HEADER` - allowed request headers, separated by commas. Empty leaves it to the defaults
- `CORS_EXPOSE_HEADER` - response headers that JavaScript may read. Empty leaves it to the defaults
- `CORS_MAX_AGE` - seconds the browser may keep a preflight result. Default 3600
- `CORS_CREDENTIALS` - whether requests with cookies are allowed. Default false
- `SESSION_STORE` - where sessions are kept: `none` `memory` `file` `sqlite`. Default sqlite
- `SESSION_MEMORY_LIMIT` - the maximum number of sessions the memory store holds. Default 100000
- `SESSION_DIRECTORY` - the directory for the file store. Default `session`
- `SESSION_TABLE` - the table name for the sqlite store. Default `session`
- `SESSION_COOKIE` - the cookie name. Default `sid`
- `SESSION_MAX_AGE` - seconds a session is kept. Default 2592000 (30 days)
- `SESSION_SECURE` - whether the cookie gets Secure. Default false. Turn it on in production
- `SESSION_SAME_SITE` - `lax` `strict` `none`. Default lax
- `REQUEST_ID_HEADER` - the header that carries the request ID. Default `x-request-id`. Empty adds none
- `CLIENT_IP_HEADER` - the header to read the client IP from. Empty by default, which means the TCP peer is used
- `TRUSTED_PROXY` - how many entries of that header to skip from the right. Default 0
- `CONTENT_SECURITY_POLICY` - the CSP added to responses. Empty by default, which adds none
- `BODY_LIMIT` - the maximum request body size in bytes. Default 2 MiB
- `REQUEST_TIMEOUT` - the maximum seconds for one request, which `server::run` also applies to receiving headers. Default 10
- `RELAY_TIMEOUT` - the maximum seconds to wait for the upstream of the relay. Default 3

## CORS

With `CORS_ORIGIN` empty, requests from any origin pass; when it is set, only those origins pass.
CorsLayer answers the preflight OPTIONS itself, so no handler is needed for it.

A value in `CORS_ORIGIN` must match the Origin the browser sends, character for character.
Write it as `scheme://host`, with a port if needed, and without a path or a trailing slash.
Write it in lowercase.
Any other form stops the startup, because a setting that is written yet has no effect is the hardest to notice.
`CORS_ORIGIN=*` is refused too. To allow every origin, leave it empty.
`*` in `CORS_METHOD`, `CORS_HEADER` and `CORS_EXPOSE_HEADER` is refused in the same way, and so is a value that cannot be read as a method or a header name.

`CORS_CREDENTIALS=true` lets requests with cookies through.
CORS then forbids answering `*` for the origin, the methods and the headers.
If credentials are turned on while `CORS_ORIGIN` is empty, mon logs a warning and drops only the credentials.
When methods and headers are not specified, mon answers with the following.

- Methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
- Request headers: content-type, authorization
- Response headers readable from JavaScript: x-request-id

Without credentials, all three are `*`.

## Client IP

Behind a proxy such as nginx, the TCP peer is the proxy itself.
The real client's address arrives in `X-Forwarded-For` or `X-Real-IP`.
`CLIENT_IP_HEADER` names the header to read, and `TRUSTED_PROXY` sets how many entries to skip from the right.

The client can write anything at the left end of the header.
nginx's `$proxy_add_x_forwarded_for` appends the address it saw on the right, so only the right side can be trusted.
With one nginx, set only `CLIENT_IP_HEADER=x-forwarded-for` and leave `TRUSTED_PROXY` at 0.
When a CDN is added in front, set it to 1.

Unless `CLIENT_IP_HEADER` is set, mon does not look at any header.
A forgotten setting never results in a forged value being taken.

In a handler, use it like this.

```
async fn where_from(ClientIp(address): ClientIp) -> String {
address.map(|value| value.to_string()).unwrap_or_default()
}
```

`server::run` hands the TCP peer to `ClientIp`.
With `axum::serve`, pass `into_make_service_with_connect_info::<SocketAddr>()` to get the same.
Without either, the header alone decides, and if that is missing too, the value is `None`.
The resolved address also goes into the log span.

## Sessions

The cookie holds only the ID, and the contents are saved in a store.
`SESSION_STORE` chooses the store.
`sqlite` uses the `session` table in mon.db, `file` writes one JSON file per session, `memory` keeps sessions inside the process, and `none` uses no sessions.

The `memory` store is emptied by a restart, and with two processes, a session goes missing in one of them.
It is for development.
`SESSION_MEMORY_LIMIT` caps how many sessions it holds.
When it is full, a request that would create a new session gets 500.

**A session is not issued until it is written.**
A client that only reads gets nothing created and no `Set-Cookie`.
Only when a handler writes to the session does mon create an ID, save it and send the cookie.
Otherwise one record would accumulate for every first-time visitor, crawlers included.
A route where an anonymous client can write to its session still adds one record per request.
Keep the number of such requests down in the proxy, for example with nginx's `limit_req`.

The ID is 32 random bytes written in hex.
mon decides by whether the ID exists in the store, so it does not sign it.
An ID sent by the client is used only when the store actually holds it.
An unknown ID is not adopted; mon creates a new one instead.

The stores keep the SHA-256 of the ID instead of the ID itself.
A leaked table, file or backup therefore does not reveal any cookie value.

The `file` store creates its directory with mode 0700 and each file with 0600, so other accounts on the machine cannot read them.
It writes a temporary file and renames it into place, so a reader never sees a half-written file.
The sweep removes only files named the way mon names them, and leaves everything else in the directory alone.

`SESSION_SECURE` defaults to false so that mon runs on `http://localhost` in development.
Set `SESSION_SECURE=true` in production.
Browsers discard a `SESSION_SAME_SITE=none` cookie without Secure, so mon refuses to start with that combination.

Expired sessions are removed when read, and by a sweep every hour.
A session past half its lifetime is saved again even without changes, which extends it.

`Set-Cookie` is sent only when a session is saved. Responses that only read get none.
Sending it every time would keep even static file responses out of shared caches and CDNs.
When `Set-Cookie` is sent, mon adds `private` to `Cache-Control` and removes `public` and `s-maxage`.
Shared caches may store a response that carries `Set-Cookie` (RFC 9111), and would then hand one person's `sid` to another.

Where the client's status changes, such as at login, call `session.renew().await` to change the ID.
The contents stay, and the old ID is removed from the store.
Without this, an attacker can place an ID they obtained themselves into the victim's browser and pass authentication with it.
mon never adopts an unknown ID, which stops forged IDs, but an ID obtained legitimately can only be made useless by changing it.

In a handler, use it like this.

```
async fn login(session: Session) -> ... {
session.write().await.language = Some("ja".to_owned())
}
```

Calling `write()` marks the session to be saved. `read()` only looks and does not save.
`write()` returns a copy of the contents, which is written back when it is dropped.
While it is held, `read()`, `renew()` and `destroy()` still return at once, and `read()` shows the contents before the write-back.
Holding two results of `write()` at the same time panics, because the one dropped first would be lost.

Add the fields a session holds to `SessionData` in session.rs.
They are saved as JSON, so adding fields changes nothing in the stores.

`session::router()` accepts a `language` of up to 35 letters, digits and hyphens, and answers 422 otherwise.
It returns only `language`, so fields added to `SessionData` are not shown to the client.

If saving what a handler wrote fails, mon answers 500 instead of the handler's response, so that the client does not believe it was saved.
The same goes for `destroy()` when the session cannot be removed from the store.

## Logging

`log::start(default)` sends logs to standard output.
Writing happens on a dedicated thread, so request handling does not stop even when the output blocks.
The span of each request records the path without the query string, because query strings can carry tokens.

```
// keep the guard until the end. Dropping it stops the writer thread and loses lines not yet written
let _log = log::start("info,tower_http=debug");
```

`RUST_LOG`, when set, takes precedence over the level given here.
When writing cannot keep up, lines are dropped instead of waiting, so that request handling never stops.
The buffer holds 128,000 lines, and lines beyond that are lost.
`dropped()` tells how many were lost. Nothing reports it unless you ask.

The library does not install this on its own, so the application decides whether to call it.
To set it up yourself, use `tracing_appender::non_blocking` directly instead of this function.

## Relay

The path and query after `/relay/` are joined to `RELAY_ORIGIN` and forwarded there.
The method, headers and body are sent as they are, and the status, headers and body that come back are returned as they are.
Only headers about the connection itself (connection, host, transfer-encoding and so on) are neither sent nor returned.
Redirects are not followed. A 302 from the upstream reaches the client as it is, location included.
Following it would deliver only the final response to the client and lose the original 302.

Whether `CLIENT_IP_HEADER` is set also tells mon whether a proxy stands in front of it.
When it is set, `X-Forwarded-For`, `-Proto` and `-Host` are added only when missing.
The ones present were added by the proxy, and rewriting them would shift the entries the upstream counts.
When it is empty, mon regards itself as the front.
It drops every `X-Forwarded-*`, `Forwarded` and `X-Real-IP` header the client sent, and writes `X-Forwarded-For`, `-Proto` and `-Host` itself.
The host header is not forwarded, so without these headers the upstream cannot learn the public host.
The status depends on the upstream: 502 when it cannot be reached, and 504 when it accepts the connection but does not answer.
Timeouts apply to two waits: until the connection is made, and until the next chunk arrives.
A timeout on the whole response would cut off a large response in the middle of streaming.

mon's session cookie is removed from the `Cookie` header sent to the upstream.
A `Set-Cookie` from the upstream for that cookie name is dropped as well.
Otherwise the upstream would learn session IDs, or could replace the client's session.

## Static files

`route::assets(&conf)` is a service that serves `STATIC_DIRECTORY`.
It adds the value of `STATIC_CACHE_CONTROL`.
The default is `no-cache`, and an empty value adds nothing.

Without the header, the browser guesses an expiry from the time since Last-Modified and does not ask again until then.
Replacing a file under the same name still shows the old one.
`no-cache` does not mean the response is not stored; it means the browser must ask before using it.
If the file has not changed, a 304 comes back, so one round trip is enough.

If file names include a hash, use `max-age=31536000, immutable`.

## CSP

The value of `CONTENT_SECURITY_POLICY` is added to every response as Content-Security-Policy.
It is empty by default, and then nothing is added.
What a page may load differs between applications, so mon has no default value.

```
CONTENT_SECURITY_POLICY="default-src 'self'; img-src 'self' data:; frame-ancestors 'none'"
```

If a handler sets its own policy, that one is kept.
To vary it per page, set it in the handler.

`frame-ancestors` replaces X-Frame-Options. With it in the policy, X-Frame-Options is not needed.

`html::document` writes its styles directly into a `<style>` element.
With only `default-src 'self'`, the styles of `page::not_found` stop working, so add `style-src 'unsafe-inline'` or put your own 404 in place.

## Storage

The application prepares its own tables.
The only table mon creates is the session table, which `session::prepare` creates with `create table if not exists`.
mon has no migration system.
If the library had one, mon's tables would mix into the application's migrations.

The table name can also be set with `SESSION_TABLE`.
The default is `session`; change it if a table with that name already exists.
Its `id` column holds the SHA-256 of each session ID.

The compile-time macro `sqlx::query!` is not used.
It would need a database connection or the `.sqlx/` cache on every build.
Runtime `query_as` and the `FromRow` derive are used instead.

## Layout

```
src/
├── lib.rs the public API
├── main.rs a binary that runs mon alone
├── conf.rs settings: Conf::default, and load, which reads the environment
├── state.rs the state shared by every handler
├── database.rs the SQLite pool
├── route.rs routing and middleware (tests are here too)
├── server.rs listening, with a limit on the time for receiving headers
├── session.rs sessions (the cookie and the stores)
├── error.rs the shared error type
├── extract.rs Json / Path / Query
├── html.rs HTML building
├── ip.rs the client IP (how far to trust the headers)
├── log.rs logging setup (calling it is the application's choice)
├── page.rs the HTML when no route matches (placing it is the application's choice)
└── relay.rs the relay to another server

examples/
└── todo.rs an example with /api/todos and a list page

tests/
├── collision.rs mon claims no paths
├── relay.rs the relay, checked against an upstream started inside the test
└── server.rs server::run, checked over real TCP connections
```

## Trying it

Start `cargo run --example todo` first.

```
curl -X POST localhost:3000/api/todos -H 'content-type: application/json' -d '{"title":"shopping"}'
curl localhost:3000/api/todos
curl -X PATCH localhost:3000/api/todos/<id> -H 'content-type: application/json' -d '{"done":true}'
curl -i -X DELETE localhost:3000/api/todos/<id>
curl -i -X POST localhost:3000/api/session \
-H 'content-type: application/json' -d '{"language":"ja"}'
```

## Formatting

rustfmt is not used.
rustfmt collapses the two blank lines between functions into one.
It also has no option to drop the spaces inside braces, which this code writes as `{key: value}`.
Neither can be expressed in its settings, so the code is aligned by hand.

## License

Dual licensed under MIT and Apache-2.0. Take whichever you prefer.

- [LICENSE-MIT](./LICENSE-MIT)
- [LICENSE-APACHE](./LICENSE-APACHE)