Crate rama

Crate rama 

Source
Expand description

🦙 rama (ラマ) is a modular network service and proxy framework for the 🦀 Rust language.

It gives you programmable control over how packets move through your stack so you can build:

  • production grade reverse and forward proxies
  • HTTP and TLS termination layers
  • security inspection and distortion proxies
  • high volume scraping and data extraction pipelines
  • custom HTTP clients with deep control over the wire

rama is already used in production by companies at scale for use cases such as network security, data extraction, API gateways and routing.

rama is async first and uses tokio as its only async runtime.

§Who is rama for

  • Developers and teams who want fine grained control over transport, TLS and HTTP while staying in safe Rust.
  • Organisations that need a partner to:
    • maintain and evolve a proxy or network platform
    • build custom features on top of rama
    • get support and training for internal teams

§Getting started

  1. Read the “Why rama” chapter for background.
  2. Run one of the examples in https://github.com/plabayo/rama/tree/main/examples.
  3. Use the rama book at https://ramaproxy.org/book and the Rust docs at https://docs.rs/rama or https://ramaproxy.org/docs/rama as references while building your own stack.

You can also use the rama binary if you want to use some of the rama features from the command line without writing your own Rust code. See https://ramaproxy.org/book/deploy/rama-cli.html.

§Experimental status

rama is considered experimental software for the foreseeable future. At the same time it is already used in production by the maintainers and by other organisations.

Real world use helps shape the design and priorities. If you run rama in production, feedback via GitHub issues, email or Discord is very welcome.

§For organisations

If your organisation relies on rama or plans to, the maintainers offer:

  • support and maintenance contracts
  • feature development with higher priority or extended scope
  • consulting and integration work around proxies, scraping and security
  • training and mentoring for your internal teams

To discuss options, contact hello@plabayo.tech.

Enterprise sponsorships are available via GitHub Sponsors and help fund development, maintenance and ecosystem work.

§Batteries included

rama ships with batteries included for transports, HTTP, TLS, DNS, proxy protocols, telemetry, fingerprinting and more. Some highlights:

  • transports: TCP, UDP, Unix domain sockets, connection pooling and middleware
  • HTTP: HTTP 1 and 2 servers and clients, layers and middleware, metrics, tracing
  • TLS: Rustls and BoringSSL support
  • proxy protocols: HTTP connect, HTTPS connect, SOCKS5, HAProxy PROXY protocol
  • fingerprinting and user agent emulation for distortion and anti bot use cases
  • telemetry: tracing integration and OpenTelemetry metrics for HTTP and transport layers

For a detailed and up to date overview see the feature table in the README and the relevant chapters in the rama book.

§Proxies and proxy focused use cases

The primary focus of rama is to help you build proxies and proxy like services:

  • reverse proxies
  • TLS termination proxies
  • HTTP and HTTPS proxies
  • SOCKS5 proxies
  • SNI based routing proxies
  • MITM proxies
  • distortion proxies with UA emulation and fingerprinting

The proxy chapters in the book start at https://ramaproxy.org/book/proxies/intro.html.

Distortion support includes User Agent emulation for HTTP and TLS built on top of data collected by rama-fp and exposed via https://fp.ramaproxy.org.

§Web services

Even though proxies are the main focus, rama can also be used to build general purpose web services. Typical use cases:

  • dynamic HTTP endpoints
  • serving static files
  • websockets and Server Sent Events (SSE)
  • health and readiness endpoints for Kubernetes
  • metrics and control plane services

rama gives you:

  • async method trait based services and layers
  • modular middleware to reuse across services and clients
  • full control from transport through TLS to HTTP and web protocols

Learn more in the web servers chapter of the book: https://ramaproxy.org/book/web_servers.html.

§Datastar integration

rama has built in support for Datastar for reactive web applications using SSE. See the examples at https://github.com/plabayo/rama/tree/main/examples and the docs at:

§Shuttle integration

rama is supported by Shuttle via the shuttle-rama crate. You can deploy rama based services to Shuttle as described at https://ramaproxy.org/book/deploy/shuttle.html.

§Web clients

A large part of rama is built on top of a service concept. A Service takes a Request and produces a Response or Error. Services can be leaf services or middlewares that wrap inner services.

rama provides:

  • an EasyHttpWebClient for HTTP requests
  • many HTTP layers to tune timeouts, retries, telemetry and more
  • a high level HttpClientExt trait to build and send requests with a fluent API

See the client example at https://github.com/plabayo/rama/tree/main/examples/http_high_level_client.rs and the docs at:

§Ecosystem

The rama crate can be used as the one and only dependency. However, as you can also read in the “DIY” chapter of the book at https://ramaproxy.org/book/diy.html#empowering, you are able to pick and choose not only what specific parts of rama you wish to use, but also in fact what specific (sub) crates.

Here is a list of all rama crates:

rama crates that live in https://github.com/plabayo/rama-boring (forks of cloudflare/boring):

repositories in function of rama that aren’t crates:

Repositories that we maintain and are re exported by the root rama crate:

Community crates that extend the ecosystem are encouraged. If you publish a community crate, please prefix it with rama-x so it is easy to discover and clearly distinct from the official crates in this repository.

§Safety and compatibility

  • rama crates avoid unsafe Rust as much as possible and use it only where necessary.
  • Supply chain auditing is done with cargo vet.
  • Tier 1 platforms include macOS, Linux and Windows on modern architectures.
  • The minimum supported Rust version (MSRV) is 1.91.

For details see the compatibility section in the README and the CI configuration in the repository.

§License

rama is free and open source software, dual licensed under MIT and Apache 2.0.

You can use rama for commercial and non commercial purposes. If rama becomes an important part of your stack, please consider supporting the project as a sponsor or partner.

If you are not sure where to start, read “Why rama” in the book, run a proxy example and then iterate from there with the book and docs at hand.

Modules§

bytes
Re-export of bytes crate.
clicli
rama cli utilities
combinators
Combinators for working with or in function of services.
conversion
cryptocrypto
Crypto primitives and dependencies used by rama.
dnsdns
DNS support for Rama.
error
Error utilities for rama and its users.
extensions
Extensions passed to and between services
futures
Re-export of the futures and asynk-strim crates.
graceful
Shutdown management for graceful shutdown of async-first applications.
httphttp
rama http support
layer
Layer type and utilities.
matcher
Matcher utilities for any middleware where need to match on incoming inputs.
netnet
Rama network types and utilities.
proxyproxy or haproxy or socks5
rama proxy support
rt
Runtime utilities used by Rama.
service
Service type and utilities.
stream
tcptcp
TCP support for Rama.
telemetry
Rama telemetry modules.
tlsrustls or boring or acme
uaua
User Agent (UA) parser and profiles.
udpudp
UDP module for Rama.
unixtarget_family=unix and net
Unix (Domain) socket support for Rama.
username
Utilities to work with usernames and pull information out of it.
utils
utilities for rama

Structs§

ServiceInput
A generic service input that implements all rama traits conditionally

Traits§

Layer
A layer that produces a Layered service (middleware(inner service)).
Service
A Service that produces rama services, to serve given an input, be it transport layer Inputs or application layer http requests, or something else entirely.