/roadster

"Batteries Included" web framework for Rust designed to get you moving fast 🏎️

Primary LanguageRustApache License 2.0Apache-2.0

Roadster

crates.io docs.rs Crates.io MSRV Crates.io License GitHub Discussions codecov Checks Feature Powerset Book dependency status

A "Batteries Included" web framework for rust designed to get you moving fast 🏎️. Inspired by other fully-featured frameworks such as Rails, Django, Laravel, Loco, and Poem.

Features

  • Built on Tokio's web stack (axum, tower, hyper, tracing). App behavior can be easily extended by taking advantage of all the resources in the tokio ecosystem.
  • Built-in support for HTTP APIs via Axum (with the http feature) and gRPC APIs via Tonic (with the grpc feature).
  • Auto-generates an OpenAPI schema for HTTP API routes defined with aide (requires the open-api feature).
  • Support for running arbitrary long-running services (e.g., an API format not supported out of the box) with minimal boilerplate. Simply provide a FunctionService with your async function and register it in the App#services method.
  • Provides sensible defaults so you can focus on building your app, but most (all?) of the built-in behavior can be customized or disabled via per-environment configuration files.
  • Uses #![forbid(unsafe_code)] to ensure all code in Roadster is 100% safe rust.
  • Provides a CLI for common commands, and allows consumers to provide their own CLI commands using clap (requires the cli feature)
  • Provides sample JWT extractor for Axum (requires the jwt-ietf and/or jwt-openid features). Also provides a general JWT extractor for Axum that simply puts all claims into a map (available with the jwt feature)
  • Built-in support for SeaORM, including creating DB connections (requires the db-sql feature)
  • Built-in support for Sidekiq.rs for running async/background jobs (requires the sidekiq feature)
  • Built-in support for sending emails via SMTP (requires the email-smtp feature) or Sendgrid's Mail Send API (requires the email-sendgrid feature)
  • Structured logs/traces using tokio's tracing crate. Export traces/metrics using OpenTelemetry (requires the otel feature).
  • Health checks to ensure the app's external dependencies are healthy
  • Pre-built migrations for common DB tables, e.g. user (requires the db-sql feature)
  • Support for auto-updating timestamp columns, e.g. updated_at, when updating DB rows (Postgres only currently) ( requires the db-sql feature)

Getting started

Start local DB

# Replace `example_dev` with your app name, e.g., `myapp_dev`
docker run -d -p 5432:5432 -e POSTGRES_USER=roadster -e POSTGRES_DB=example_dev -e POSTGRES_PASSWORD=roadster postgres:15.3-alpine

Start local Redis instance (for Sidekiq.rs)

docker run -d -p 6379:6379 redis:7.2-alpine

Start local SMTP server instance

Mailpit

docker run -d -p 8025:8025 -p 1025:1025 axllent/mailpit

smtp4dev

docker run -d -p 1080:80 -p 1025:25 rnwood/smtp4dev

maildev

docker run -d -p 1080:1080 -p 1025:1025 maildev/maildev

Create your app

# Todo: Add instructions for creating a new app
# Using one of our examples for now 
git clone https://github.com/roadster-rs/roadster.git
cd roadster/examples/full

Set the environment (production/development/test)

# Either set it as an environment variable
export ROADSTER__ENVIRONMENT=development
# Or add it to a `.env` file
echo ROADSTER__ENVIRONMENT=development >> .env

Start your app

cargo run

Explore the API

Navigate to http://localhost:3000/api/_docs to explore the app's OpenAPI playground

Add a UI

Currently, Roadster is focused on back-end API development with Rust. We leave it to the consumer to decide how they prefer to add a front-end, e.g., using an established JS/TS framework (React / Next / Vue / Svelte / Solid / etc) or using a Rust front-end framework (Leptos / Yew / Perseus / Sycamore / etc). That said, we do have some examples of how to use Roadster with some these frameworks.

Examples

Framework Example
Leptos leptos-ssr

Email

Local testing of sending emails via SMTP

If you're using our SMTP integration to send emails, you can test locally using a mock SMTP server. Some options:

Tracing + OpenTelemetry

Roadster allows reporting traces and metrics using the tracing and opentelemetry_rust integrations. Provide the URL of your OTLP exporter in order to report the trace/metric data to your telemetry provider (e.g., SigNoz, New Relic, Datadog, etc).

View traces locally

You can also view traces locally using, for example, Jaeger or SigNoz.

Jaeger

The easiest way to view OpenTelemetry Traces locally is by running Jaeger.

  1. Set ROADSTER__TRACING__OTLP_ENDPOINT="http://localhost:4317" in your .env file, or in your config/development.toml or config/test.toml configs as appropriate.
  2. Run the following command: 
    docker run --rm --name jaeger \
    -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
    -p 6831:6831/udp \
    -p 6832:6832/udp \
    -p 5778:5778 \
    -p 16686:16686 \
    -p 4317:4317 \
    -p 4318:4318 \
    -p 14250:14250 \
    -p 14268:14268 \
    -p 14269:14269 \
    -p 9411:9411 \
    jaegertracing/all-in-one:1.53
  3. Navigate to the UI, which is available at localhost:16686.

Signoz

Another option to view traces (and metrics) locally is to run Signoz.

  1. Set ROADSTER__TRACING__OTLP_ENDPOINT="http://localhost:4317" in your .env file, or in your config/development.toml or config/test.toml configs as appropriate.
  2. Install and run Signoz in a directory of your choice 
    # Clone the repo
git clone -b main https://github.com/SigNoz/signoz.git && cd signoz/deploy/
# Remove the sample application: https://signoz.io/docs/operate/docker-standalone/#remove-the-sample-application-from-signoz-dashboard
vim docker/clickhouse-setup/docker-compose.yaml
# Remove the `services.hotrod` and `services.load-hotrod` sections, then exit `vim`
# Run the `docker compose` command
./install.sh
  3. Navigate to the UI, which is available at localhost:3301.
  4. To stop Signoz, run the following: 
    docker compose -f docker/clickhouse-setup/docker-compose.yaml stop

Background/async job queue using Sidekiq.rs

This crate is a rust implementation of Sidekiq, which is usually used with Ruby on Rails. All we need in order to use this is a Redis instance.

Sidekiq dashboard

We provide a sample repo to run the sidekiq dashboard locally in a standalone docker container.

git clone https://github.com/roadster-rs/standalone_sidekiq_dashboard.git
cd standalone_sidekiq_dashboard
docker build -t standalone-sidekiq .
# Linux docker commands
# Development
docker run -d --network=host standalone-sidekiq
# Test
docker run -d --network=host -e REDIS_URL='redis://localhost:6380' standalone-sidekiq

# Mac docker commands -- todo: see if there's a command that will work on both mac and linux
# Development
docker run -d -p 9292:9292 -e REDIS_URL=redis://host.docker.internal:6379 standalone-sidekiq
# Test
docker run -d -p 9292:9292 -e REDIS_URL=redis://host.docker.internal:6380 standalone-sidekiq

Redis Insights

You can also inspect the Redis DB directly using RedisInsight.

# Linux docker commands
docker run -d --name redisinsight --network=host -p 5540:5540 redis/redisinsight:latest
# Mac docker commands -- todo: see if there's a command that will work on both mac and linux
# Use `host.docker.internal` as the host domain in redis insight (instead of `127.0.0.1`)
docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest