📦 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
Quick Links
- Crates Page: https://crates.io/crates/rama/0.2.0-alpha.3
- Official Docs Page (for releases): https://docs.rs/rama
- Edge (main branch): https://ramaproxy.org/docs/rama/index.html
- Github repo: https://github.com/plabayo/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 allrama-error
: error utilities for rama and its usersrama-macros
: contains the procedural macros used byrama
rama-utils
: utilities crate for ramarama-core
: core crate containing the service, layer and context used by all otherrama
code, as well as some other core utilitiesrama-net
: rama network types and utilitiesrama-dns
: DNS support for ramarama-tcp
: TCP support for ramarama-tls
: TLS support for rama (types,rustls
andboring
)rama-proxy
: proxy types and utilities for ramarama-haproxy
: rama HaProxy supportrama-ua
: User-Agent (UA) support forrama
rama-http-types
: http types and utilitiesrama-http
: rama http services, layers and utilitiesrama-http-backend
: default http backend forrama
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.
platform | tested | test platform |
---|---|---|
MacOS | ✅ | MacOS Apple Silicon (developer laptop) and macos-12 Intel (GitHub Action) |
Linux | ✅ | Ubuntu 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 therama
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 theseneeds 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.