Preface - Rama

rama banner

🦙 Rama (ラマ) is a modular service framework for the 🦀 Rust language to move and transform your network packets.

The motivations behind Rama's creation are detailed in the "Why Rama" chapter.

While powerful and flexible, Rama might not be the ideal framework for everyone. If you're building a conventional web server or need a simple HTTP client, other crates might better suit your needs. Although we at Plabayo use Rama extensively for our web infrastructure (clients, servers, and proxies), it has a steeper learning curve and a smaller community compared to more established alternatives.

Consider these alternatives for simpler use cases:

Axum for building standard HTTP web servers. It offers extensive community support and ecosystem integrations. However, be aware that Axum's higher-level abstractions may limit your control over the web stack when you need to implement non-standard features.

Reqwest for basic HTTP client needs. It's ideal when you don't require fine-grained control over HTTP requests/responses or TLS configuration details.

If you're specifically building proxies and find Rama's approach doesn't align with your needs, explore the alternatives listed in our project README.

Rama's core philosophy centers on empowerment and modularity. It provides a foundation for building proxies, servers, and clients without imposing restrictions. Any component in a Rama-based web stack can be customized to meet your specific requirements, even if that means implementing custom solutions for particular layers.

We gratefully acknowledge that Rama stands on the shoulders of giants. For more details about our inspirations and dependencies, see our acknowledgements.

In some cases, we've had to fork external crates to accommodate our specific needs or scope requirements. While this creates additional maintenance work, we believe it's worthwhile to support our mission of empowering Rama users. Details about these forks can be found in our FORK.md. We maintain the original code structure in these forks to facilitate upstream synchronization and contribute patches back when possible.

Rama is async-first using Tokio as its only Async Runtime. Please refer to the examples found in the /examples dir to get inspired on how you can use it for your purposes.

💡 If your organization relies on Rama (ラマ) for its operations, we invite you to consider becoming a sponsor 💖. By supporting our project, you'll help ensure its continued development and success. To learn more about sponsorship opportunities, please refer to the "Sponsors" chapter in this book or contact us directly at sponsor@ramaproxy.org.

This framework comes with 🔋 batteries included, giving you the full freedome to build the middleware and services you want, without having to repeat the "common":

category	support list
✅ transports	✅ tcp ⸱ 🏗️ udp ⁽²⁾ ⸱ ✅ middleware
✅ http	✅ auto ⸱ ✅ http/1.1 ⸱ ✅ h2 ⸱ 🏗️ h3 ⁽²⁾ ⸱ ✅ middleware
✅ web server	✅ fs ⸱ ✅ redirect ⸱ ✅ dyn router ⸱ ✅ static router ⸱ ✅ handler extractors ⸱ ✅ k8s healthcheck
✅ http client	✅ easy client ⸱ ✅ high level API ⸱ ✅ Proxy Connect ⸱ ❌ Chromium Http ⁽³⁾
✅ tls	✅ Rustls ⸱ ✅ BoringSSL ⸱ ❌ NSS ⁽³⁾
✅ dns	✅ DNS Resolver
✅ proxy protocols	✅ PROXY protocol ⸱ ✅ http proxy ⸱ ✅ https proxy ⸱ 🏗️ SOCKS5 ⁽²⁾ ⸱ 🏗️ SOCKS5H ⁽²⁾
🏗️ web protocols	🏗️ Web Sockets (WS) ⁽²⁾ ⸱ 🏗️ WSS ⁽²⁾ ⸱ ❌ Web Transport ⁽³⁾ ⸱ ❌ gRPC ⁽³⁾
✅ async-method trait services	✅ Service ⸱ ✅ Layer ⸱ ✅ context ⸱ ✅ dyn dispatch ⸱ ✅ middleware
✅ telemetry	✅ tracing ⸱ ✅ opentelemetry ⸱ ✅ http metrics ⸱ ✅ transport metrics
✅ upstream proxies	✅ MemoryProxyDB ⸱ ✅ L4 Username Config ⸱ ✅ Proxy Filters
✅ User Agent (UA)	✅ Http Emulation ⸱ ✅ Tls Emulation ⸱ ✅ UA Parsing
✅ Fingerprinting	✅ Ja3 ⸱ ✅ Ja4 ⸱ ✅ Ja4H
✅ utilities	✅ error handling ⸱ ✅ graceful shutdown ⸱ 🏗️ Connection Pool ⁽¹⁾ ⸱ 🏗️ IP2Loc ⁽²⁾
🏗️ Graphical Interface	🏗️ traffic logger ⁽²⁾ ⸱ 🏗️ curl export ⁽²⁾ ⸱ 🏗️ TUI implementation ⁽²⁾ ⸱ ❌ traffic intercept ⁽³⁾ ⸱ ❌ traffic replay ⁽³⁾
✅ binary	✅ prebuilt binaries ⸱ 🏗️ proxy config ⁽²⁾ ⸱ ✅ http client ⸱ ❌ WASM Plugins ⁽³⁾
🏗️ data scraping	🏗️ Html Processor ⁽²⁾ ⸱ ❌ Json Processor ⁽³⁾
❌ browser	❌ JS Engine ⁽³⁾ ⸱ ❌ Web API Emulation ⁽³⁾

🗒️ Footnotes

⁽¹⁾ Part of v0.2.0 milestone (ETA: 2025 Q2)

⁽²⁾ Part of v0.3.0 milestone (ETA: 2025 Q3)

⁽³⁾ No immediate plans, but on our radar. Please open an issue to request this feature if you have an immediate need for it. Please add sufficient motivation/reasoning and consider becoming a sponsor to help accelerate its priority.

The primary focus of Rama is to aid you in your development of proxies:

🚦 Reverse proxies;
🔓 TLS Termination proxies;
🌐 HTTP(S) proxies;
🧦 SOCKS5 proxies (will be implemented in v0.3);
🔎 MITM proxies;
🕵️‍♀️ Distortion proxies.

The Distortion proxies support comes with User Agent (UA) emulation capabilities. The emulations are made possible by patterns and data extracted using rama-fp. The service is publicly exposed at https://fp.ramaproxy.org, made possible by our sponsor host https://fly.io/.

🔁 https://echo.ramaproxy.org/ is another service publicly exposed. In contrast to the Fingerprinting Service it is aimed at developers and allows you to send any http request you wish in order to get an insight on the Tls Info and Http Request Info the server receives from you when making that request.
curl -XPOST 'https://echo.ramaproxy.org/foo?bar=baz' \
  -H 'x-magic: 42' --data 'whatever forever'
Feel free to make use of while crafting distorted http requests, but please do so with moderation. In case you have ideas on how to improve the service, please let us know by opening an issue.

BrowserStack sponsors Rama by providing automated cross-platform browser testing on real devices, which uses the public fingerprinting service to aid in automated fingerprint collection on both the Http and Tls layers. By design we do not consider Tcp and Udp fingerprinting.

Next to proxies, Rama can also be used to develop Web Services and Http Clients.

Rama also has a channel on the official Discord of the Tokio project. Feel free to join us there as well: https://discord.com/channels/500028886025895936/1349098858831024209

Please consult the official docs.rs documentation or explore the examples found in the /examples dir to know how to use rama for your purposes.

💡 You can find the edge docs of the rama framework code at https://ramaproxy.org/docs/rama/index.html, which contains the documentation for the main branch of the project.

🤝 Enterprise support, software customisations, integrations, professional support, consultancy and training are available upon request by sending an email to glen@plabayo.tech. Or get an entireprise subscription via Gihub Sponsors.

💖 Please consider becoming a sponsor if you critically depend upon Rama (ラマ) or if you are a fan of the project.

⌨️ | `rama` binary

The rama binary allows you to use a lot of what rama has to offer without having to code yourself. It comes with a working http client for CLI, which emulates User-Agents and has other utilities. And it also comes with IP/Echo services.

It also allows you to run a rama proxy, configured to your needs.

Learn more about the rama binary and how to install it at /deploy/rama-cli.md.

🧪 | Experimental

🦙 Rama (ラマ) is to be considered experimental software for the foreseeable future. In the meanwhile it is already used in production by ourselves and others alike. This is great as it gives us new perspectives and data to further improve and grow the framework. It does mean however that there are still several non-backward compatible releases that will follow 0.2.

In the meanwhile the async ecosystem of Rust is also maturing, and edition 2024 is also to be expected as a 2024 end of year gift. It goes also without saying that we do not nilly-willy change designs or break on purpose. The core design is by now also well defined. But truth has to be said, there is still plenty to be improve and work out. Production use and feedback from you and other users helps a lot with that. As such, if you use Rama do let us know feedback over Discord, email or a GitHub issue.

👉 If you are a company or enterprise that makes use of Rama, or even an individual user that makes use of Rama for commcercial purposes. Please consider becoming a business/enterprise subscriber. It helps make the development cycle to remain sustainable, and is beneficial to you as well. As part of your benefits we are also available to assist you with migrations between breaking releases. For enterprise users we can even make time to develop those PR's in your integration codebases ourselves on your behalf. A win for everybody. 💪

Rama

⌨️ | rama binary

🧪 | Experimental

⌨️ | `rama` binary