Skip to content
plabayoPublic

About

modular service framework to move and transform network packets

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1.3k stars

Watchers

11 watching

Forks

Latest commit

 

History

3,713 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

rama banner

Crates.io Docs.rs MIT License Apache 2.0 License rust version Build Status Lines of Code

🦙 rama® (ラマ) is a modular service framework for the 🦀 Rust language that provides a cohesive foundation for building network clients, servers, proxies, and combinations thereof.

The framework is intentionally explicit. Your network stack is built from services, layers, transports, protocols, and state that you compose yourself. That makes the shape of the system visible in the code, instead of hidden behind framework magic or configuration.

This makes Rama a good fit not only for proxies, but for network services where the stack itself matters: how traffic enters, how it is decoded, where state lives, what gets inspected, what gets transformed, and where it goes next.

Use it to inspect traffic for security analysis, write web services, emulate clients with custom user agents, control connection behavior for testing, or build high-performance proxies, all on a composable Tokio-native foundation.

Rama is used in production for network security, data extraction, API gateways, routing, and other networked systems.

Note

This framework is developed and maintained by Plabayo, a European software studio based in Gent, Belgium, focused on building resilient, interoperable, and secure digital infrastructure.

rama: modular service framework to move and transform network packets

How the pieces fit together

Start with a service that does one job. Wrap it in a layer to add behavior, or connect it to another service. The same model works across network layers and protocols, so you can start with built-in pieces and add your own Rust code where you need it.

The map and tables below give you an overview. To get a feel for building with Rama, browse the examples, run one close to what you want to build, and make it your own. Try swapping a connector or writing a layer in Rust. The Rama Book explains how the pieces compose, and the edge API docs cover the code you’re working with on main.

The rama CLI lets you run ready-made stacks from the terminal. Try rama serve proxy --mitm to start a proxy with a traffic inspection UI. Alongside the examples, the CLI source shows how a full application composes Rama services into clients, servers, proxies and diagnostic tools.

A client can connect straight to a server. Add a proxy, a gateway, or both when traffic needs an intermediate hop. The server can answer on its own or delegate some or all requests to an application backend.

An optional platform SDK gives your service another entry point. The OS can redirect a flow into your stack before it reaches its original destination.

Clients connect directly or through an optional proxy or gateway. Servers can delegate to a backend. A separate OS or SDK path can deliver redirected flows to a Rama service in any role.

What each part can do

Role Building blocks Guide · Working code
Discovery DNS resolution, load balancing, system proxy settings and environment variables, PAC, bypass rules and route fallback Proxy discovery guide · PAC client example
Client Connection pooling, retries, redirects, Alt-Svc, upstream proxies and browser profiles HTTP client guide · Pooled client example
Proxy Forwarding, tunneling, transparent interception, traffic capture, HAR replay and ICAP adaptation ICAP guide · ICAP example
Gateway SNI routing and request routing, TLS termination, mTLS, ACME certificates and TLS fingerprinting SNI routing guide · SNI router example
Server Typed handlers and routing, static files, uploads, streaming responses, authentication and limits Web server guide · Router example
Application backend FastCGI over TCP or Unix sockets for a whole application, selected routes or a fallback Gateway guide · PHP-FPM examples
OS / SDK Receive OS-selected flows through Apple Network Extension and pass them to a Rama service.

Roadmap. For Rama 0.6, we plan to add integrations for Windows Filtering Platform and Linux eBPF.
Platform guide · Apple Network Extension example
Across the stack Async services, layers, shared state, blocking adapters and Tower interop Service model guide · Tower example
Telemetry Tracing spans, OpenTelemetry metrics for HTTP and transport, and dial9 recordings of Tokio scheduling and protocol activity.

Roadmap. In Rama 0.6, we plan to unify tracing, OpenTelemetry and dial9 behind a shared Rama event system.
Telemetry guide · Local recording example

Protocols by OSI layer

The OSI model gives us a shared vocabulary for teaching and documenting networks. Real protocols often span layers. Here the layers serve as an index into the parts of the stack you can work with in Rama.

OSI layer Protocols and capabilities Guide · Working code
7 · Application HTTP/1.1, HTTP/2 and HTTP/3, WebSocket, SSE, gRPC, ttRPC, FastCGI, ICAP, DNS, ACME. Proxying with HTTP CONNECT, SOCKS5 and MASQUE. MASQUE guide · CONNECT-UDP example
6 · Presentation TLS handshakes and certificates with Rustls or BoringSSL. Content encoding and compression. TLS guide · mTLS example
5 · Session Connection pooling, client TLS resumption policy and QUIC connection migration. HTTP client guide · Pooled client example
4 · Transport TCP streams, UDP datagrams, QUIC v1 and v2 over UDP. Unix sockets for local transport.

Roadmap. Userspace TCP and UDP stacks are planned for Rama 0.6.
Transport guide · QUIC client and server example
3 · Network IPv4 and IPv6 packet parsing, ICMP forwarding errors and IP tunneling with CONNECT-IP.

Roadmap. In Rama 0.6, we plan to integrate platform tunnel interfaces, including Apple’s utun, so Rama services can send and receive IP packets through OS-managed tunnels.
CONNECT-IP guide · CONNECT-IP interop test

Where to start for your use case

If you're building… Start here Then try
An endpoint security proxy Apple Network Extension example or Linux TPROXY example Decide which hosts to intercept in the HTTP/3 inspection example.
A data collection client Emulation guide for browser TLS and HTTP profiles Select an outbound profile per client in the emulating proxy example.
An edge router or API gateway SNI router example for routing encrypted connections by name Terminate TLS and authenticate both peers in the mTLS example.
A web service alongside an existing app Router example for typed Rust handlers Move routes from PHP-FPM to Rust one at a time with the PHP-FPM examples.
A traffic debugging tool CLI inspection guide for the MITM proxy and its web UI Reproduce a recorded exchange with the HAR replay example.

Rama can be the networking foundation for a project of any size. You can start with a single service, then build across the layers and roles in the map as your needs grow. The same services and layers you use in a small tool can become part of an endpoint agent, a gateway, or a network stack of your own design.

Note

Commercial partnerships

Plabayo can help your team migrate an existing system to Rama or build your first MVP or project for you. We also offer ongoing maintenance, code audits, and training for the engineers who will run and extend it.

Partnerships help fund Rama’s maintenance and shape its development. Working with teams in production shows us which features and fixes matter, and those improvements benefit everyone using the framework. Explore partnership options.

Built for production

Production deployments have shaped Rama from the start. Whether a service runs on an endpoint device, at a gateway, or on a server, we design its network stack to bound resource use and avoid unnecessary copies on hot paths. We track protocol performance with benchmarks such as the QUIC benchmark suite.

  • Deployment targets. Linux, macOS, and Windows are tier 1 platforms. CI also checks Android and iOS targets. The minimum supported Rust version is 1.96.
  • Dependency audits. We use cargo vet to audit third-party dependencies.

Sponsors and support

GitHub Sponsors Buy Me A Coffee Paypal Donation

Rama is free and open-source software. Sponsorships help fund development, infrastructure, testing, and maintenance.

Commercial support, consulting, training, and custom development are available through ramaproxy.com. More background is available in the Sponsor chapter.

Community

Discord

Questions, ideas, and project discussion are welcome on Discord. Bug reports and feature requests can be opened as GitHub issues.

Rama also has a public channel on the official Discord of the Tokio project: https://discord.com/channels/500028886025895936/1349098858831024209.

All rama and other crates developed by Plabayo

Most users can start with rama. The smaller crates exist for users who want finer control over dependencies or extension points.

See the ecosystem chapter for more context.

Rama crates in this repository:

Related Plabayo crates and projects:

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Good places to start:

Some issues have a needs input label. These usually need discussion, research, or design work before implementation starts.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in rama by you shall be licensed as both MIT and Apache-2.0, without any additional terms or conditions.

License

Rama is licensed under either of:

FAQ

Available at https://ramaproxy.org/book/faq.html.

original (OG) rama logo

Tip

📚 If you like Rama, you might also like Netstack.FM®, a podcast about networking, Rust, and everything in between.

About

modular service framework to move and transform network packets

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1.3k stars

Watchers

11 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages