Skip to main content

Crate rama

Crate rama 

Source
Expand description

🦙 rama (ラマ) is a modular Rust framework for building network clients, servers, proxies, and gateways.

A Service handles an input, such as a connection or an HTTP request. A Layer wraps a service to add behavior. The same model works across network layers and protocols, so you can start with a built-in stack and plug in your own Rust code where you need it. For synchronous callers, BlockingService and rt::blocking provide a blocking boundary around an async stack.

Tip for newcomers

Start with the project README to see how the pieces fit together, or visit ramaproxy.org to explore what you can build.

§Common entry points

GoalAPI
Implement a service or wrap one in middlewareService, Layer
Serve HTTP requests and route them to handlershttp::server, http::service::web
Send HTTP requests with a configurable clienthttp::client::EasyHttpWebClient, http::service::client::HttpClientExt
Use an HTTP client from synchronous codehttp::client::BlockingHttpWebClient
Send selected or unmatched requests to a FastCGI backendgateway::fastcgi
Capture or inspect trafficinspect
Build HTTP proxy flowshttp::proxy
Adapt HTTP through ICAPicap::http::layer
Build standalone ICAP servicesicap::client, icap::server
Build SOCKS5 proxy flowsproxy::socks5
Build MASQUE CONNECT-UDP and CONNECT-IP clients and proxiesproxy::masque
Build Linux transparent proxy flowslinux_tproxy_tcp.rs
Build Apple transparent proxy flowsffi/apple/examples/transparent_proxy

§Main API areas

APIPurpose
Service, LayerCore service and middleware traits
BlockingService, rt::blockingSynchronous boundaries for async services, streams, and I/O
httpHTTP/1.1, HTTP/2 and HTTP/3 clients, servers, services, layers, WebSockets, gRPC
icapInternet Content Adaptation Protocol (ICAP)
gatewayApplication server gateways such as FastCGI
ttrpcttRPC clients and servers
proxyProxy primitives, SOCKS5, MASQUE (CONNECT-UDP, CONNECT-IP), HAProxy PROXY protocol
tcp, udp, unixTransport listeners, connectors, and streams
quicQUIC endpoints, connections, ordered streams, and unreliable datagrams
tlsTLS abstractions, Rustls, BoringSSL, ACME
cryptoCertificates, PEM, ASN.1, OCSP, CRL, JOSE, digests and native root certificates
dnsDNS resolvers and related types
netNetwork addresses, sockets, forwarding, fingerprints, and Apple platform integrations in net::apple
uaUser-Agent parsing, profiles, and emulation
inspectProtocol-independent inspection, interception and capture storage
jsonStreaming JSON tokenizer, JSONPath selection and rewriting
jsEmbedded JavaScript runtime and Proxy Auto-Configuration (PAC) support via js::pac
telemetryTracing spans, OpenTelemetry metrics, and dial9 recordings of runtime and protocol activity
utilsUtilities, including Tower compatibility

§Feature flags

The default feature is std. Enable the features for the APIs you use. For example, http-full enables the HTTP client and server stacks. The docs.rs build enables all features, so it also shows APIs you can opt into separately.

§Explore a working stack

The client and server example applies the same HTTP tracing layer to outbound requests and incoming routes. Run it, then try changing the layers on either side. The examples directory has more starting points, including transparent proxies and application gateways. Check the example’s run instructions for its feature flags.

The Rama Book explains the service model and has guides to proxies, HTTP services, and the Rama CLI. The project README maps the available building blocks to network roles and protocols. Use docs.rs for published versions and the edge docs for the API on main.

Modules§

bytes
Re-export of bytes crate.
clicli and std
rama cli utilities
combinators
Combinators for working with or in function of services.
conversion
cryptocrypto and std
Crypto primitives and dependencies used by rama.
dnsdns and std
DNS support for Rama.
error
Error utilities for Rama and its users.
error_sink
A reusable sink for errors that occur in fire-and-forget contexts.
extensions
Extensions passed to and between services
futures
Re-export of the futures and asynk-strim crates.
gatewayfastcgi and std
Application server gateway protocols (FastCGI, and similar).
geo
Geographic identity types shared across rama.
gracefulstd
Cancellation trees with a graceful and a hard phase.
httphttp and std
rama http support
icapicap
Internet Content Adaptation Protocol (ICAP) support for Rama.
inspectinspect
Inspection building blocks independent of traffic protocol and user interface.
iostd
jsjs and std
Embedded javascript execution, see [rama_js] for more info.
jsonstd
Streaming JSON tools for Rama.
layer
Layer type and utilities.
matcher
Matcher utilities for any middleware where need to match on incoming inputs.
netnet
proxyhaproxy and std, or masque and std, or proxy and std, or socks5 and std
rama proxy support
quicquic
QUIC: the deterministic wire-protocol vocabulary and the async engine built on it.
rtstd
Runtime utilities used by Rama.
service
Service type and utilities.
streamstd
tcpstd and tcp
TCP support for Rama.
telemetrystd
Rama telemetry modules.
tlsacme and std, or boring and std, or rustls and std, or std and tls
ttrpcttrpc
ttRPC (“gRPC for low-memory environments”) support.
uastd and ua
User Agent (UA) parser and profiles.
udpstd and udp
Protocol-neutral UDP module for Rama.
unixtarget_family=unix and unix
Unix (Domain) socket support for Rama.
username
Utilities to work with usernames and pull information out of it.
utils
utilities for rama

Structs§

ServiceInputstd
A generic service input that implements all rama traits conditionally

Traits§

BlockingService
A synchronous Service boundary.
Fork
Create a structurally isolated logical child of a value.
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.