Lib.rs

🦙 Rama (ラマ) is a modular proxy framework for the 🦀 Rust language to move and transform your network packets. The reasons behind the creation of rama can be read in the "Why Rama" chapter.

You can use it to develop:

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

And all kind of other proxies that you can think of. Next to this Rama can also be used for developing web servers. Within a proxy setting this can be useful in case you want to hijack certain requests with your custom server, or because you want to use pseudo domains to serve an API as part of your proxy. Or you might want to serve your MITM TLS certs. And of course you might also use it to develop a regular web service, which comes with all the great benefits that rama has to offer for developing proxies.

^(*) The Distortion proxies support comes with UA emulation capabilities. Part of this uses actual browser fingerprint information generated by rama-fp, Responsible for the collection, storage and transformation of browser fingerprint data, as is relevant for rama.

While this is not meant for humans, you can also use the public facing service yourself, to get to know your own UA a bit better. It also gives you insights in the Rama POV, and what might still need to be improved.

The service is available at https://fp.ramaproxy.org.

Developers can also make use of https://echo.ramaproxy.org, to test if their requests would reach their target in the way they expect it to.

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.

• Learn more by reading the Rama book at https://ramaproxy.org/book;
• or checkout the framework Rust docs at https://docs.rs/rama;
  • edge docs (for main branch) can be found at https://ramaproxy.org/docs/rama.

There is no crates.io release of rama yet. If you already want to start using rama already your can do so by referring to it in your Cargo.toml as follows:

rama = { git = "https://github.com/plabayo/rama" }

💬 Come join us at Discord on the #rama public channel. To ask questions, discuss ideas and ask how rama may be useful for you.

⚠️ rama is early work in progress, use at your own risk.

Not everything that exists is documented and not everything that is documented is implemented.

📖 Rama's full documentation, references and background material can be found in the form of the "rama book" at https://ramaproxy.org/book.

⛨ | Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

🦀 | Compatibility

Rama (ラマ) is developed mostly on MacOS M-Series machines and run in production on a variety of Linux systems. Windows support is not officially guaranteed, but is tested using Github Actions with success.

Please open a ticket in case you have compatibility issues for your setup/platform. Our goal is not to support all possible platformns in the world, but we do want to support as many as we reasonably can.

Minimum supported Rust version

Rama's MSRV is 1.75.

Using GitHub Actions we also test if rama on that version still works on the stable and beta versions of rust as well.

🧭 | Roadmap

Please refer to https://github.com/plabayo/rama/milestones to know what's on the roadmap. Is there something not on the roadmap for the next version that you would really like? Please create a feature request to request it and become a sponsor if you can.

💼 | License

This project is dual-licensed under both the MIT license and Apache 2.0 License.

👋 | Contributing

🎈 Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the rama project.

Contributions often come from people who already know what they want, be it a fix for a bug they encountered, or a feature that they are missing. Please do always make a ticket if one doesn't exist already.

It's possible however that you do not yet know what specifically to contribute, and yet want to help out. For that we thank you. You can take a look at the open issues, and in particular:

• good first issue: issues that are good for those new to the rama codebase;
• easy: issues that are seen as easy;
• mentor available: issues for which we offer mentorship;
• low prio: low prio issues that have no immediate pressure to be finished quick, great in case you want to help out but can only do with limited time to spare;

In general, any issue not assigned already is free to be picked up by anyone else. Please do communicate in the ticket if you are planning to pick it up, as to avoid multiple people trying to solve the same one.

Should you want to contribure this project but you do not yet know how to program in Rust, you could start learning Rust with as goal to contribute as soon as possible to rama by using "the Rust 101 Learning Guide" as your study companion. Glen can also be hired as a mentor or teacher to give you paid 1-on-1 lessons and other similar consultancy services. You can find his contact details at https://www.glendc.com/.

Contribution

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.

Acknowledgements

Special thanks goes to all involved in developing, maintaining and supporting the Rust programming language, the Tokio ecosystem and all other crates that we depend upon. This also includes Hyper and its ecosystem as without those projects Rama would not be. The core http module of rama is a specialised fork of hyper and use the underlying h2 and h3 crates as dependencies.

Extra credits also go to Axum, from which ideas and code were copied as its a project very much in line with the kind of software we want Rama to be, but for a different purpose. Our hats also go off to Tower, its inventors and all the people and creatures that help make it be every day. The service concept is derived from Tower and many of our layers are a Tower fork, adapted where required or desired.

An extra big shoutout goes also to the online communities surrounding and part of these ecosystems. They are a great place to hangout and always friendly and helpful. Thanks.

💖 | Sponsors

Rama is completely free, open-source software which needs lots of effort and time to develop and maintain.

Support this project by becoming a sponsor. One time payments are accepted at GitHub as well as at "Buy me a Coffee".

Sponsors help us continue to maintain and improve rama, as well as other Free and Open Source (FOSS) technology. It also helps us to create educational content such as https://github.com/plabayo/learn-rust-101, and other open source libraries such as https://github.com/plabayo/tower-async.

Next to the many unpaid developer hours we put in a project such as rama, we also have plenty of costs, such as services ranging from hosting to Docker, but also tooling for developers and automated processing. All these costs money.

Sponsors receive perks and depending on your regular contribution it also allows you to rely on us for support and consulting.

Finally, you can also support us by shopping Plabayo <3 ラマ merchandise 🛍️ at https://plabayo.threadless.com/.

Rama Sponsors

We would like to extend our thanks to the following sponsors for funding Rama (ラマ) development. If you are interested in becoming a sponsor, you can do so by becoming a sponsor. One time payments are accepted at GitHub as well as at "Buy me a Coffee".

If you wish to financially support us through other means you can best start a conversation with us by sending an email to glen@plabayo.tech.

Premium Partners

• fly.io
• BrowserStack

Rama (ラマ) is bundled with HTTP/TLS emulation data, gathered for all major platforms and browsers using real devices by BrowserStack. It does this automatically every day by using our public Fingerprinting service which is hosted together with a database on fly.io.

We are grateful to both sponsors for sponsering us these cloud resources.

Professional Services

🤝 Enterprise support, software customisations, integrations, professional support, consultancy and training are available upon request by sending an email to glen@plabayo.tech.

These type of contracts are another way for you to be able to support the project and at the same time get serviced for your own needs and purposes.

Rama is licensed as both MIT and Apache 2.0, as such you are free to use and modify the source code for any purposes, including commercial goals. That said, we would appreciate it if you would consider becoming a sponsor of the project if you do end up using it for commcercial reasons.

Contribute to Open Source

Part of the money we receive from sponsors is used to contribute to other projects that we depend upon. Plabayo sponsors the following organisations and individuals building and maintaining open source software that rama depends upon:

Past Contributions

🌱 | Alternatives

While there are a handful of proxies written in Rust, there are only two other Rust frameworks specifically made for proxy purposes. All other proxy codebases are single purpose code bases, some even just for learning purposes. Or are actually generic http/web libraries/frameworks that facilitate proxy features as an extra.

Cloudflare has been working on a proxy service framework, named pingora, since a couple of years already, and on the 28th of February of 2024 they also open sourced it.

Rama is not for everyone, but we sure hope it is right for you. If not, consider giving pingora a try, it might very well be the next best thing for you.

Secondly, ByteDance has an open source proxy framework written in Rust to developer forward and reverse proxies alike, named g3proxy.

❓| FAQ

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

⭐ | Stargazers