tlaferriere / rama Goto Github PK

🦙 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.

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

Rama's MSRV is 1.75.

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.

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

🎈 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.

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/.

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.

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.

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/.

🤝 Enterprise support, software customisations, integrations, professional support, consultancy and training are available upon request by sending an email to [email protected].

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.

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:

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.

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