📦 Rama Crate

Rama is a modular service framework distributed as a Rust crate at https://crates.io/crates/rama/0.2.0-alpha.3. You can add it to your project as follows:

cargo add rama

All Rama Crates

The rama crate can be used as the one and only dependency. However, as you can also read in the "DIY" chapter of the book at https://ramaproxy.org/book/diy.html#empowering, you are able to pick and choose not only what specific parts of rama you wish to use, but also in fact what specific (sub) crates.

Here is a list of all rama crates:

  • rama: one crate to rule them all
  • rama-error: error utilities for rama and its users
  • rama-macros: contains the procedural macros used by rama
  • rama-utils: utilities crate for rama
  • rama-core: core crate containing the service, layer and context used by all other rama code, as well as some other core utilities
  • rama-net: rama network types and utilities
  • rama-dns: DNS support for rama
  • rama-tcp: TCP support for rama
  • rama-tls: TLS support for rama (types, rustls and boring)
  • rama-proxy: proxy types and utilities for rama
  • rama-haproxy: rama HaProxy support
  • rama-ua: User-Agent (UA) support for rama
  • rama-http-types: http types and utilities
  • rama-http: rama http services, layers and utilities
  • rama-http-backend: default http backend for rama

Examples

Examples to help you get started can be found in the examples found in the /examples dir to know how to use rama for your purposes.

⛨ | Safety

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

We also make use of cargo vet to audit our supply chain.

🦀 | Compatibility

Rama (ラマ) is developed mostly on MacOS M-Series machines and run in production on a variety of Linux systems. There is no windows support, and neither do we test on that platform.

platformtestedtest platform
MacOSMacOS Apple Silicon (developer laptop) and macos-12 Intel (GitHub Action)
LinuxUbuntu 22.04 (GitHub Action)

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

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.

📰 | Media Appearances

Rama (0.2) was featured in a 📻 Rustacean episode on the 19th of May 2024, and available to listen at https://rustacean-station.org/episode/glen-de-cauwsemaecker/. In this episode Glen explains the history of Rama, why it exists, how it can be used and more.

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

💡 Some issues have a needs input label. These mean that the issue is not yet ready for development. First of all prior to starting working on an issue you should always look for alignment with the rama maintainers. However these needs input issues require also prior R&D work:

  • add and discuss missing knowledge or other things not clear;
  • figure out pros and cons of the solutions (as well as what if we choose to not not resolve the issue);
  • discuss and brainstorm on possible implementations, desire features, consequences, benefits, ...

Only once this R&D is complete and alignment is confirmed, shall the feature be started to be implemented.

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.