#web-framework #framework #web #http-api #command #axum #included

roadster

A "Batteries Included" web framework for rust designed to get you moving fast

11 releases

new 0.3.1 Jun 11, 2024
0.3.0 Jun 10, 2024
0.2.6 Jun 3, 2024
0.2.3 May 27, 2024
0.1.1 May 6, 2024

#74 in HTTP server

Download history 205/week @ 2024-05-01 36/week @ 2024-05-08 442/week @ 2024-05-22 524/week @ 2024-05-29

1,017 downloads per month

MIT/Apache

290KB
7K SLoC

Roadster

crates.io docs.rs Crates.io MSRV Crates.io License GitHub Discussions codecov Checks Feature Powerset 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 sane 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)
  • Structured logs/traces using tokio's tracing crate. Export traces/metrics using OpenTelemetry (requires the otel feature).

Start local DB

# Dev
docker run -d -p 5432:5432 -e POSTGRES_USER=roadster -e POSTGRES_DB=myapp_dev -e POSTGRES_PASSWORD=roadster postgres:15.3-alpine
# Test
docker run -d -p 5433:5432 -e POSTGRES_USER=roadster -e POSTGRES_DB=myapp_test -e POSTGRES_PASSWORD=roadster postgres:15.3-alpine

Start local Redis instance (for Sidekiq.rs)

# Dev
docker run -d -p 6379:6379 redis:7.2-alpine
# Test
docker run -d -p 6380:6379 redis:7.2-alpine

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

Dependencies

~17–38MB
~569K SLoC