{"id":18926395,"url":"https://github.com/plabayo/rama","last_synced_at":"2025-04-07T08:18:52.618Z","repository":{"id":59777875,"uuid":"522327873","full_name":"plabayo/rama","owner":"plabayo","description":"modular service framework to move and transform network packets","archived":false,"fork":false,"pushed_at":"2024-04-30T21:11:27.000Z","size":5723,"stargazers_count":69,"open_issues_count":39,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-01T09:48:17.795Z","etag":null,"topics":["http","https","mitm","network","network-programming","networking","proxy","rust","scraping","tls"],"latest_commit_sha":null,"homepage":"https://ramaproxy.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plabayo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"plabayo","buy_me_a_coffee":"plabayo","custom":["https://www.paypal.com/donate/?hosted_button_id=P3KCGT2ACBVFE","https://plabayo.threadless.com/"]}},"created_at":"2022-08-07T21:24:56.000Z","updated_at":"2024-05-02T12:41:16.221Z","dependencies_parsed_at":"2023-10-15T13:45:34.142Z","dependency_job_id":"9ba2a440-732a-4619-9c88-6174debdeed9","html_url":"https://github.com/plabayo/rama","commit_stats":null,"previous_names":["plabayo/llama"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plabayo%2Frama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plabayo%2Frama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plabayo%2Frama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plabayo%2Frama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plabayo","download_url":"https://codeload.github.com/plabayo/rama/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615385,"owners_count":20967184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http","https","mitm","network","network-programming","networking","proxy","rust","scraping","tls"],"created_at":"2024-11-08T11:16:07.371Z","updated_at":"2025-04-07T08:18:52.595Z","avatar_url":"https://github.com/plabayo.png","language":"Rust","funding_links":["https://github.com/sponsors/plabayo","https://buymeacoffee.com/plabayo","https://www.paypal.com/donate/?hosted_button_id=P3KCGT2ACBVFE","https://plabayo.threadless.com/","https://www.buymeacoffee.com/plabayo","https://github.com/sponsors/plabayo/sponsorships?tier_id=300734"],"categories":["Applications","Recently Updated","Rust"],"sub_categories":["Web Servers","[Apr 03, 2025](/content/2025/04/03/README.md)"],"readme":"[![rama banner](./docs/img/rama_banner.jpeg)](https://ramaproxy.org/)\n\n[![Crates.io][crates-badge]][crates-url]\n[![Docs.rs][docs-badge]][docs-url]\n[![MIT License][license-mit-badge]][license-mit-url]\n[![Apache 2.0 License][license-apache-badge]][license-apache-url]\n[![rust version][rust-version-badge]][rust-version-url]\n[![Build Status][actions-badge]][actions-url]\n[![Lines of Code][loc-badge]][loc-url]\n\n[crates-badge]: https://img.shields.io/crates/v/rama.svg\n[crates-url]: https://crates.io/crates/rama\n[docs-badge]: https://img.shields.io/docsrs/rama/latest\n[docs-url]: https://docs.rs/rama/latest/rama/index.html\n[license-mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[license-mit-url]: https://github.com/plabayo/rama/blob/main/LICENSE-MIT\n[license-apache-badge]: https://img.shields.io/badge/license-APACHE-blue.svg\n[license-apache-url]: https://github.com/plabayo/rama/blob/main/LICENSE-APACHE\n[rust-version-badge]: https://img.shields.io/badge/rustc-1.85+-blue?style=flat-square\u0026logo=rust\n[rust-version-url]: https://www.rust-lang.org\n[actions-badge]: https://github.com/plabayo/rama/actions/workflows/CI.yml/badge.svg?branch=main\n[actions-url]: https://github.com/plabayo/rama/actions/workflows/CI.yml\n[loc-badge]: https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/plabayo/rama/badge?filter=.rs$\u0026style=flat\u0026logoColor=white\u0026label=LoC\n[loc-url]: https://github.com/plabayo/rama\n\n[discord-badge]: https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge\u0026logo=discord\u0026logoColor=white\n[discord-url]: https://discord.gg/29EetaSYCD\n[bmac-badge]: https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black\n[bmac-url]: https://www.buymeacoffee.com/plabayo\n[ghs-badge]: https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA\n[ghs-url]: https://github.com/sponsors/plabayo\n[paypal-badge]: https://img.shields.io/badge/paypal-contribution?style=for-the-badge\u0026color=blue\n[paypal-url]: https://www.paypal.com/donate/?hosted_button_id=P3KCGT2ACBVFE\n\n🦙 Rama (ラマ) is a modular service framework for the 🦀 Rust language to move and transform your network packets.\n\n\u003e The reasons behind the creation of Rama can be read in [the \"Why Rama\" chapter](https://ramaproxy.org/book/why_rama).\n\u003e\n\u003e However, this framework might not be for everyone. Particularly if you're building a typical simple web server\n\u003e or just need an HTTP client for making standard requests, you might be better served by other crates.\n\u003e While we at [Plabayo](https://plabayo.tech) use Rama for most of our web needs (clients, servers, and proxies),\n\u003e it is not the most straightforward framework to use and doesn't yet have the large community backing that other crates enjoy.\n\u003e\n\u003e - Consider using [Axum](https://github.com/tokio-rs/axum) if you're building a typical HTTP web server.\n\u003e   It comes with many community crates to help with virtually anything you can think of. However, using\n\u003e   Axum means giving up full control over your web stack, which could become limiting when you need something\n\u003e   that isn't typical or standards-enforced.\n\u003e - Consider using [Reqwest](https://docs.rs/reqwest/latest/reqwest/) if you only need to make typical\n\u003e   HTTP requests without fine-grained control over the requests sent or responses received,\n\u003e   and where TLS is merely a detail indicated by the `https` protocol (where 's' stands for secure).\n\u003e\n\u003e If you're building proxies and feel that Rama isn't the right approach for you,\n\u003e you might want to check out [the alternatives mentioned at the bottom of this README](#--alternatives).\n\u003e\n\u003e Rama emphasizes empowerment and modularity. It helps you build proxies, servers, and clients\n\u003e without getting in your way or limiting your mission where Rama might fall short. A web stack\n\u003e built with Rama can always be customized to your needs, even if a particular part or layer is specific to your purpose.\n\u003e\n\u003e It's worth noting that Rama is built upon the shoulders of giants.\n\u003e Please refer to [the acknowledgements](#Acknowledgements) for more information.\n\u003e\n\u003e When necessary, we've forked other crates due to incompatibilities in needs or scope.\n\u003e While this creates additional work for us, we willingly do so when it aligns with our mission\n\u003e of empowering Rama users, including ourselves. You can find more information about these forks\n\u003e in the [FORK.md](./FORK.md) document.\n\u003e We strive to preserve the code layout of forked modules to maintain synchronization with upstream\n\u003e and push patches upstream where possible.\n\nRama is async-first using [Tokio](https://tokio.rs/) as its _only_ Async Runtime.\nPlease refer to [the examples found in the `/examples` dir](https://github.com/plabayo/rama/tree/main/examples)\nto get inspired on how you can use it for your purposes.\n\n[![GitHub Sponsors][ghs-badge]][ghs-url]\n[![Buy Me A Coffee][bmac-badge]][bmac-url]\n[![Paypal Donation][paypal-badge]][paypal-url]\n[![Discord][discord-badge]][discord-url]\n\n\u003e 💡 If your organization relies on Rama (ラマ) for its operations,\n\u003e we invite you to consider becoming a sponsor 💖. By supporting our project,\n\u003e you'll help ensure its continued development and success.\n\u003e To learn more about sponsorship opportunities, please refer to [the \"Sponsors\" section below](#--sponsors)\n\u003e or contact us directly at [sponsor@ramaproxy.org](mailto:sponsor@ramaproxy.org).\n\nThis framework comes with 🔋 batteries included, giving you the full freedom to build the middleware and services you want, without _having_ to repeat the \"common\":\n\n| category | support list |\n|-|-|\n| ✅ [transports](https://ramaproxy.org/docs/rama/net/stream/index.html) | ✅ [tcp](https://ramaproxy.org/docs/rama/tcp/index.html) ⸱ 🏗️ udp \u003csup\u003e(2)\u003c/sup\u003e ⸱ ✅ [middleware](https://ramaproxy.org/docs/rama/net/stream/layer/index.html) |\n| ✅ [http](https://ramaproxy.org/docs/rama/http/index.html) | ✅ [auto](https://ramaproxy.org/docs/rama/http/server/service/struct.HttpServer.html#method.auto) ⸱ ✅ [http/1.1](https://ramaproxy.org/docs/rama/http/server/service/struct.HttpServer.html#method.http1) ⸱ ✅ [h2](https://ramaproxy.org/docs/rama/http/server/service/struct.HttpServer.html#method.h2) ⸱ 🏗️ h3 \u003csup\u003e(2)\u003c/sup\u003e ⸱ ✅ [middleware](https://ramaproxy.org/docs/rama/http/layer/index.html) |\n| ✅ web server | ✅ [fs](https://ramaproxy.org/docs/rama/http/service/fs/index.html) ⸱ ✅ [redirect](https://ramaproxy.org/docs/rama/http/service/redirect/struct.Redirect.html) ⸱ ✅ [dyn router](https://ramaproxy.org/docs/rama/http/service/web/struct.WebService.html) ⸱ ✅ [static router](https://docs.rs/rama-http/latest/rama_http/service/web/macro.match_service.html) ⸱ ✅ [handler extractors](https://ramaproxy.org/docs/rama/http/service/web/extract/index.html) ⸱ ✅ [k8s healthcheck](https://ramaproxy.org/docs/rama/http/service/web/k8s/index.html) |\n| ✅ http [client](https://ramaproxy.org/docs/rama/http/client/index.html) | ✅ [easy client](https://ramaproxy.org/docs/rama/http/client/struct.EasyHttpWebClient.html) ⸱ ✅ [high level API](https://ramaproxy.org/docs/rama/http/service/client/trait.HttpClientExt.html) ⸱ ✅ [Proxy Connect](https://ramaproxy.org/docs/rama/http/client/proxy/layer/struct.HttpProxyConnector.html) ⸱ ❌ [Chromium Http](https://github.com/plabayo/rama/issues/189) \u003csup\u003e(3)\u003c/sup\u003e |\n| ✅ [tls](https://ramaproxy.org/docs/rama/tls/index.html) | ✅ [Rustls](https://ramaproxy.org/docs/rama/tls/rustls/index.html) ⸱ ✅ [BoringSSL](https://ramaproxy.org/docs/rama/tls/boring/index.html) ⸱ ❌ NSS \u003csup\u003e(3)\u003c/sup\u003e |\n| ✅ [dns](https://ramaproxy.org/docs/rama/dns/index.html) | ✅ [DNS Resolver](https://ramaproxy.org/docs/rama/dns/trait.DnsResolver.html) |\n| ✅ [proxy protocols](https://ramaproxy.org/docs/rama/proxy/index.html) | ✅ [PROXY protocol](https://ramaproxy.org/docs/rama/proxy/haproxy/index.html) ⸱ ✅ [http proxy](https://github.com/plabayo/rama/blob/main/examples/http_connect_proxy.rs) ⸱ ✅ [https proxy](https://github.com/plabayo/rama/blob/main/examples/https_connect_proxy.rs) ⸱ 🏗️ SOCKS5 \u003csup\u003e(2)\u003c/sup\u003e ⸱ 🏗️ SOCKS5H \u003csup\u003e(2)\u003c/sup\u003e |\n| 🏗️ web protocols | 🏗️ Web Sockets (WS) \u003csup\u003e(2)\u003c/sup\u003e ⸱ 🏗️ WSS \u003csup\u003e(2)\u003c/sup\u003e ⸱ ❌ Web Transport \u003csup\u003e(3)\u003c/sup\u003e ⸱ ❌ gRPC \u003csup\u003e(3)\u003c/sup\u003e |\n| ✅ [async-method trait](https://blog.rust-lang.org/inside-rust/2023/05/03/stabilizing-async-fn-in-trait.html) services | ✅ [Service](https://ramaproxy.org/docs/rama/service/trait.Service.html) ⸱ ✅ [Layer](https://ramaproxy.org/docs/rama/layer/trait.Layer.html) ⸱ ✅ [context](https://ramaproxy.org/docs/rama/context/index.html) ⸱ ✅ [dyn dispatch](https://ramaproxy.org/docs/rama/service/struct.BoxService.html) ⸱ ✅ [middleware](https://ramaproxy.org/docs/rama/layer/index.html) |\n| ✅ [telemetry](https://ramaproxy.org/docs/rama/telemetry/index.html) | ✅ [tracing](https://tracing.rs/tracing/) ⸱ ✅ [opentelemetry](https://ramaproxy.org/docs/rama/telemetry/opentelemetry/index.html) ⸱ ✅ [http metrics](https://ramaproxy.org/docs/rama/http/layer/opentelemetry/index.html) ⸱ ✅ [transport metrics](https://ramaproxy.org/docs/rama/net/stream/layer/opentelemetry/index.html) |\n| ✅ upstream [proxies](https://ramaproxy.org/docs/rama/proxy/index.html) | ✅ [MemoryProxyDB](https://ramaproxy.org/docs/rama/proxy/struct.MemoryProxyDB.html) ⸱ ✅ [L4 Username Config](https://ramaproxy.org/docs/rama/username/index.html) ⸱ ✅ [Proxy Filters](https://ramaproxy.org/docs/rama/proxy/struct.ProxyFilter.html) |\n| ✅ [User Agent (UA)](https://ramaproxy.org/book/intro/user_agent) | ✅ [Http Emulation](https://ramaproxy.org/docs/rama/ua/profile/struct.HttpProfile.html) ⸱ ✅ [Tls Emulation](https://ramaproxy.org/docs/rama/ua/profile/struct.TlsProfile.html) ⸱ ✅ [UA Parsing](https://ramaproxy.org/docs/rama/ua/struct.UserAgent.html) |\n| ✅ [Fingerprinting](https://ramaproxy.org/docs/rama/net/fingerprint/index.html) | ✅ [Ja3](https://ramaproxy.org/docs/rama/net/fingerprint/struct.Ja3.html) ⸱ ✅ [Ja4](https://ramaproxy.org/docs/rama/net/fingerprint/struct.Ja4.html) ⸱ ✅ [Ja4H](https://ramaproxy.org/docs/rama/net/fingerprint/struct.Ja4H.html) |\n| ✅ utilities | ✅ [error handling](https://ramaproxy.org/docs/rama/error/index.html) ⸱ ✅ [graceful shutdown](https://ramaproxy.org/docs/rama/graceful/index.html) ⸱ 🏗️ Connection Pool \u003csup\u003e(1)\u003c/sup\u003e ⸱ 🏗️ IP2Loc \u003csup\u003e(2)\u003c/sup\u003e |\n| 🏗️ Graphical Interface | 🏗️ traffic logger \u003csup\u003e(2)\u003c/sup\u003e ⸱ 🏗️ curl export \u003csup\u003e(2)\u003c/sup\u003e ⸱ 🏗️ [TUI implementation](https://ratatui.rs/) \u003csup\u003e(2)\u003c/sup\u003e ⸱ ❌ traffic intercept \u003csup\u003e(3)\u003c/sup\u003e ⸱ ❌ traffic replay \u003csup\u003e(3)\u003c/sup\u003e |\n| ✅ binary | ✅ [prebuilt binaries](https://ramaproxy.org/book/deploy/rama-cli) ⸱ 🏗️ proxy config \u003csup\u003e(2)\u003c/sup\u003e ⸱ ✅ http client ⸱ ❌ WASM Plugins \u003csup\u003e(3)\u003c/sup\u003e |\n| 🏗️ data scraping | 🏗️ Html Processor \u003csup\u003e(2)\u003c/sup\u003e ⸱ ❌ Json Processor \u003csup\u003e(3)\u003c/sup\u003e |\n| ❌ browser | ❌ JS Engine \u003csup\u003e(3)\u003c/sup\u003e ⸱ ❌ [Web API](https://developer.mozilla.org/en-US/docs/Web/API) Emulation \u003csup\u003e(3)\u003c/sup\u003e |\n\n\u003e 🗒️ _Footnotes_\n\u003e\n\u003e * \u003csup\u003e(1)\u003c/sup\u003e Part of [`v0.2.0` milestone (ETA: 2025 Q2)](https://github.com/plabayo/rama/milestone/1)\n\u003e * \u003csup\u003e(2)\u003c/sup\u003e Part of [`v0.3.0` milestone (ETA: 2025 Q3)](https://github.com/plabayo/rama/milestone/2)\n\u003e * \u003csup\u003e(3)\u003c/sup\u003e No immediate plans, but on our radar. Please [open an issue](https://github.com/plabayo/rama/issues) to request this feature if you have an immediate need for it. Please add sufficient motivation/reasoning and consider [becoming a sponsor](#--sponsors) to help accelerate its priority.\n\nThe primary focus of Rama is to aid you in your development of [proxies](https://ramaproxy.org/book/proxies/intro.html):\n\n- 🚦 [Reverse proxies](https://ramaproxy.org/book/proxies/reverse);\n- 🔓 [TLS Termination proxies](https://ramaproxy.org/book/proxies/tls);\n- 🌐 [HTTP(S) proxies](https://ramaproxy.org/book/proxies/http);\n- 🧦 [SOCKS5 proxies](https://ramaproxy.org/book/proxies/socks5) (will be implemented in `v0.3`);\n- 🔎 [MITM proxies](https://ramaproxy.org/book/proxies/mitm);\n- 🕵️‍♀️ [Distortion proxies](https://ramaproxy.org/book/proxies/distort).\n\n\u003e 💡 Check out [the \"Intro to Proxies\" chapters in the Rama book](https://ramaproxy.org/book/proxies/intro.html)\n\u003e to learn more about the different kind of proxies. It might help in case you are new to developing proxies.\n\nThe [Distortion proxies](https://ramaproxy.org/book/proxies/distort) support\ncomes with [User Agent (UA)](https://ramaproxy.org/book/intro/user_agent) emulation capabilities. The emulations are made possible by patterns\nand data extracted using [`rama-fp`](https://github.com/plabayo/rama/tree/main/rama-fp/). The service is publicly exposed at\n\u003chttps://fp.ramaproxy.org\u003e, made possible by our sponsor host \u003chttps://fly.io/\u003e.\n\n\u003e 🔁 \u003chttps://echo.ramaproxy.org/\u003e is another service publicly exposed.\n\u003e In contrast to the Fingerprinting Service it is aimed at developers\n\u003e and allows you to send any http request you wish in order to get an insight\n\u003e on the Tls Info and Http Request Info the server receives\n\u003e from you when making that request.\n\u003e\n\u003e ```bash\n\u003e curl -XPOST 'https://echo.ramaproxy.org/foo?bar=baz' \\\n\u003e   -H 'x-magic: 42' --data 'whatever forever'\n\u003e ```\n\u003e\n\u003e Feel free to make use of while crafting distorted http requests,\n\u003e but please do so with moderation. In case you have ideas on how to improve\n\u003e the service, please let us know [by opening an issue](https://github.com/plabayo/rama/issues).\n\u003e\n\u003e Using the [`rama` binary](https://ramaproxy.org/book/deploy/rama-cli.html)\n\u003e you can also run both the `echo` and `fp` service yourself, locally or as an\n\u003e external facing web service.\n\u003e\n\u003e Please run your own echo service instead of using `echo.ramaproxy.org`\n\u003e in case you are planning to send a lot of traffic to the echo service.\n\n[BrowserStack](https://browserstack.com) sponsors Rama by providing automated cross-platform browser testing\non real devices, which [uses the public fingerprinting service](./rama-fp/browserstack/main.py) to aid in automated fingerprint collection\non both the Http and Tls layers. By design we do not consider Tcp and Udp fingerprinting.\n\nNext to proxies, Rama can also be used to develop [Web Services](#--web-services) and [Http Clients](#--http-clients).\n\n- Learn more by reading the Rama book at \u003chttps://ramaproxy.org/book\u003e;\n- or checkout the framework Rust docs at \u003chttps://docs.rs/rama\u003e;\n    - edge docs (for main branch) can be found at \u003chttps://ramaproxy.org/docs/rama\u003e.\n\n📖 Rama's full documentation, references and background material can be found in the form of the \"rama book\" at \u003chttps://ramaproxy.org/book\u003e.\n\n💬 Come join us at [Discord][discord-url] on the `#rama` public channel. To ask questions, discuss ideas and ask how rama may be useful for you.\n\n\u003e Rama also has a public channel on the official Discord of the tokio project.\n\u003e Feel free to join us there instead or as well: \u003chttps://discord.com/channels/500028886025895936/1349098858831024209\u003e\n\n## ⌨️ | `rama` binary\n\nThe `rama` binary allows you to use a lot of what `rama` has to offer without\nhaving to code yourself. It comes with a working http client for CLI, which emulates\nUser-Agents and has other utilities. And it also comes with IP/Echo services.\n\nIt also allows you to run a `rama` proxy, configured to your needs.\n\nLearn more about the `rama` binary and how to install it at \u003chttps://ramaproxy.org/book/deploy/rama-cli\u003e.\n\n## 🧪 | Experimental\n\n🦙 Rama (ラマ) is to be considered experimental software for the foreseeable future. In the meanwhile it is already used\nin production by ourselves and others alike. This is great as it gives us new perspectives and data to further improve\nand grow the framework. It does mean however that there are still several non-backward compatible releases that will follow `0.2`.\n\nIn 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.\nIt goes also without saying that we do not willy-nilly change designs or break on purpose. The core design is by now also well defined. But truth has to be said,\nthere is still plenty to be improved and worked out. Production use and feedback from you and other users helps a lot with that. As such,\nif you use Rama do let us know feedback over [Discord][discord-url], [email](mailto:glen@plabayo.tech) or a [GitHub issue](https://github.com/plabayo/rama/issues).\n\n👉 If you are a company or enterprise that makes use of Rama, or even an individual user that makes use of Rama for commercial purposes. Please consider becoming [a business/enterprise subscriber](https://github.com/sponsors/plabayo/sponsorships?tier_id=300734). 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. 💪\n\n## 📣 | Rama Ecosystem\n\nFor now there are only the rama crates found in this repository, also referred to as \"official\" rama crates.\n\nWe welcome however community contributions not only in the form of contributions to this repository,\nbut also have people write their own crates as extensions to the rama ecosystem.\nE.g. perhaps you wish to support an alternative http/tls backend.\n\nIn case you have ideas for new features or stacks please let us know first.\nPerhaps there is room for these within an official rama crate.\nIn case it is considered out of scope you are free to make your own community rama crate.\nPlease prefix all rama community crates with \"rama-x\", this way the crates are easy to find,\nand are sufficiently different from \"official\" rama crates\".\n\nOnce you have such a crate published do let us know it, such that we can list them here.\n\n### 📦 | Rama Crates\n\nThe `rama` crate can be used as the one and only dependency.\nHowever, as you can also read in the \"DIY\" chapter of the book\nat \u003chttps://ramaproxy.org/book/diy.html#empowering\u003e, you are able\nto pick and choose not only what specific parts of `rama` you wish to use,\nbut also in fact what specific (sub) crates.\n\nHere is a list of all `rama` crates:\n\n- [`rama`](https://crates.io/crates/rama): one crate to rule them all\n- [`rama-error`](https://crates.io/crates/rama-error): error utilities for rama and its users\n- [`rama-macros`](https://crates.io/crates/rama-macros): contains the procedural macros used by `rama`\n- [`rama-utils`](https://crates.io/crates/rama-utils): utilities crate for rama\n- [`rama-core`](https://crates.io/crates/rama-core): core crate containing the service, layer and\n  context used by all other `rama` code, as well as some other _core_ utilities\n- [`rama-net`](https://crates.io/crates/rama-net): rama network types and utilities\n- [`rama-dns`](https://crates.io/crates/rama-dns): DNS support for rama\n- [`rama-tcp`](https://crates.io/crates/rama-tcp): TCP support for rama\n- [`rama-udp`](https://crates.io/crates/rama-udp): UDP support for rama\n- [`rama-tls`](https://crates.io/crates/rama-tls): TLS support for rama (types, `rustls` and `boring`)\n- [`rama-proxy`](https://crates.io/crates/rama-proxy): proxy types and utilities for rama\n- [`rama-socks5`](https://crates.io/crates/rama-socks5): SOCKS5 support for rama\n- [`rama-haproxy`](https://crates.io/crates/rama-haproxy): rama HaProxy support\n- [`rama-ua`](https://crates.io/crates/rama-ua): User-Agent (UA) support for `rama`\n- [`rama-http-types`](https://crates.io/crates/rama-http-types): http types and utilities\n- [`rama-http`](https://crates.io/crates/rama-http): rama http services, layers and utilities\n- [`rama-http-backend`](https://crates.io/crates/rama-http-backend): default http backend for `rama`\n- [`rama-http-core`](https://crates.io/crates/rama-http-core): http protocol implementation driving `rama-http-backend`\n\n`rama` crates that live in \u003chttps://github.com/plabayo/rama-boring\u003e (forks of `cloudflare/boring`):\n\n- [`rama-boring`](https://crates.io/crates/rama-boring): BoringSSL bindings for Rama\n- [`rama-boring-sys`](https://crates.io/crates/rama-boring-sys): FFI bindings to BoringSSL for Rama\n- [`rama-boring-tokio`](https://crates.io/crates/rama-boring-tokio): an implementation of SSL streams for Tokio backed by BoringSSL in function of Rama\n\nrepositories in function of rama that aren't crates:\n\n- \u003chttps://github.com/plabayo/rama-boringssl\u003e:\n  Fork of [mirror of BoringSSL](https://github.com/plabayo/rama-boringssl)\n  in function of [rama-boring](https://github.com/plabayo/rama-boring)\n- \u003chttps://github.com/plabayo/homebrew-rama\u003e: Homebrew formula for the rama Cli tool\n\n## 🏢 | Proxy Examples\n\n- [/examples/tls_termination.rs](https://github.com/plabayo/rama/tree/main/examples/tls_termination.rs):\n  Spawns a mini handmade http server, as well as a TLS termination proxy, forwarding the\n  plain text stream to the first.\n- [/examples/tls_termination.rs](https://github.com/plabayo/rama/tree/main/examples/tls_termination.rs):\n  Spawns a mini handmade http server, as well as a TLS termination proxy, forwarding the\n  plain text stream to the first.\n- [/examples/mtls_tunnel_and_service.rs](https://github.com/plabayo/rama/blob/main/examples/mtls_tunnel_and_service.rs):\n  Example of how to do mTls (manual Tls, where the client also needs a certificate) using rama,\n  as well as how one might use this concept to provide a tunnel service build with these concepts;\n- [/examples/http_connect_proxy.rs](https://github.com/plabayo/rama/tree/main/examples/http_connect_proxy.rs):\n  Spawns a minimal http proxy which accepts http/1.1 and h2 connections alike,\n  and proxies them to the target host.\n\n## 🌐 | Web Services\n\nDeveloping proxies are the primary focus of Rama (ラマ). It can however also be used to develop web services to serve web pages, Http API's and static content. This comes with many of the same benefits that you get when developing proxies using Rama:\n\n* Use Async Method Traits;\n* Reuse modular [Tower](https://github.com/tower-rs/tower)-like middleware using extensions as well as strongly typed state;\n* Have the ability to be in full control of your web stack from Transport Layer (Tcp, Udp), through Tls and Http;\n* If all you care about is the Http layer then that is fine to.\n* Be able to trust that your incoming Application Http data has not been modified (e.g. Http header casing and order is preserved);\n* Easily develop your service at a Request layer and High level functions alike, choices are yours and can be combined.\n\nExamples of the kind of web services you might build with rama in function of your proxy service:\n\n- a k8s health service ([/examples/http_k8s_health.rs](https://github.com/plabayo/rama/tree/main/examples/http_k8s_health.rs));\n- a metric exposure service;\n- a minimal api service (e.g. to expose device profiles or certificates);\n- a graphical interface / control panel;\n\n\u003e 📖 Learn more about developing web services in the Rama book: \u003chttps://ramaproxy.org/book/web_servers.html\u003e.\n\n## 🌐 | Web Service Examples\n\nHere are some low level web service examples without fancy features:\n\n- [/examples/http_listener_hello.rs](https://github.com/plabayo/rama/blob/main/examples/http_listener_hello.rs): is the most basic example on how to provide\n  a root service with no needs for endpoints or anything else (e.g. good enough for some use cases related\n  to health services or metrics exposures);\n  - [/examples/http_health_check.rs](https://github.com/plabayo/rama/blob/main/examples/http_health_check.rs) is an even more minimal example\n    of a health check service returning a _200 OK_ for any incoming request.\n- [/examples/http_service_hello.rs](https://github.com/plabayo/rama/blob/main/examples/http_service_hello.rs): is an example similar to the previous\n  example but shows how you can also operate on the underlying transport (TCP) layer, prior to passing it to your\n  http service;\n\nThere's also a premade webservice that can be used as the health service for your proxy k8s workloads:\n\n- [/examples/http_k8s_health.rs](https://github.com/plabayo/rama/tree/main/examples/http_k8s_health.rs):\n  built-in web service that can be used as a k8s health service for proxies deploying as a k8s deployment;\n\nThe following are examples that use the high level concepts of Request/State extractors and IntoResponse converters,\nthat you'll recognise from `axum`, just as available for `rama` services:\n\n- [/examples/http_key_value_store.rs](https://github.com/plabayo/rama/tree/main/examples/http_key_value_store.rs):\n  a web service example showcasing how one might do a key value store web service using `Rama`;\n- [/examples/http_web_service_dir_and_api.rs](https://github.com/plabayo/rama/tree/main/examples/http_web_service_dir_and_api.rs):\n  a web service example showcasing how one can make a web service to serve a website which includes an XHR API;\n\nFor a production-like example of a web service you can also read the [rama cli `fp` cmd source code](https://github.com/plabayo/rama/tree/main/rama-cli/src/cmd/fp).\nThis is the webservice behind the Rama fingerprinting service, which is used by the maintainers of 🦙 Rama (ラマ) to generate\nthe UA emulation data for the Http and TLS layers. It is not meant to fingerprint humans or users. Instead it is meant to help\nautomated processes look like a human.\n\n\u003e 💡 This example showcases how you can make use of the [`match_service`](https://docs.rs/rama-http/latest/rama_http/service/web/macro.match_service.html)\n\u003e macro to create a `Box`-free service router. Another example of this approach can be seen in the\n\u003e [http_service_match.rs](https://github.com/plabayo/rama/tree/main/examples/http_service_match.rs) example.\n\n## 🧑‍💻 | Http Clients\n\nIn [The rama book](https://ramaproxy.org/book) you can read and learn that a big pillar of Rama's architecture is built on top of [the Service concept](https://ramaproxy.org/book/intro/services_all_the_way_down.html). A [`Service`][rama-service] takes as input a user-defined `State` (e.g. containing your database Pool) and a `Request`, and uses it to serve either a `Response` or `Error`. Such a [`Service`][rama-service] can produce the response \"directly\" (also called ☘️ Leaf services) or instead pass the request and state to an inner [`Service`][rama-service] which it wraps around (so called 🍔 Middlewares).\n\n[rama-service]: https://ramaproxy.org/docs/rama/service/trait.Service.html\n\nIt's a powerful concept, originally introduced to Rust by [the Tower ecosystem](https://github.com/tower-rs/tower) and allows you build complex stacks specialised to your needs in a modular and easy manner. Even cooler is that this works for both clients and servers alike.\n\nRama provides an [`EasyHttpWebClient`](https://ramaproxy.org/docs/rama/http/client/struct.EasyHttpWebClient.html) which sends your _Http_ `Request` over the network and returns the `Response` if it receives and read one or an `Error` otherwise. Combined with [the many Layers (middleware)](https://ramaproxy.org/docs/rama/http/layer/index.html) that `Rama` provides and perhaps also some developed by you it is possible to create a powerful _Http_ client suited to your needs.\n\nAs a 🍒 cherry on the cake you can import the [`HttpClientExt`](https://ramaproxy.org/docs/rama/http/service/client/trait.HttpClientExt.html) trait in your Rust module to be able to use your _Http_ Client [`Service`][rama-service] stack using a high level API to build and send requests with ease.\n\n### 🧑‍💻 | Http Client Example\n\n\u003e 💡 The full \"high level\" example can be found at [/examples/http_high_level_client.rs](https://github.com/plabayo/rama/tree/main/examples/http_high_level_client.rs).\n\n```rust\nuse rama::http::service::client::HttpClientExt;\n\nlet client = (\n    TraceLayer::new_for_http(),\n    DecompressionLayer::new(),\n    AddAuthorizationLayer::basic(\"john\", \"123\")\n        .as_sensitive(true)\n        .if_not_present(),\n    RetryLayer::new(\n        ManagedPolicy::default().with_backoff(ExponentialBackoff::default()),\n    ),\n).into_layer(EasyHttpWebClient::default());\n\n#[derive(Debug, Deserialize)]\nstruct Info {\n    name: String,\n    example: String,\n    magic: u64,\n}\n\nlet info: Info = client\n    .get(\"http://example.com/info\")\n    .header(\"x-magic\", \"42\")\n    .typed_header(Accept::json())\n    .send(Context::default())\n    .await\n    .unwrap()\n    .try_into_json()\n    .await\n    .unwrap();\n```\n\n## 💪 | Performance\n\n`rama`'s default http implementation is forked from [`hyper`] and adds very little\noverhead. So `rama`'s performance is comparable to [`hyper`] and frameworks that built on top of that.\n\n[`hyper`]: https://github.com/hyperium/hyper\n\nHere's a list of external benchmarks:\n\n- http server benchmark @ \u003chttps://web-frameworks-benchmark.netlify.app/result\u003e\n\nPlease [open an issue](https://github.com/plabayo/rama/issues) or Pull Request (PR) in case\nyou are aware of any other benchmarks of interest in regards to http(s) servers,\nhttp(s) clients or proxies such as Man-In-The-Middle (MITM) proxies.\n\n## ⛨ | Safety\n\nThe rama crates avoid `unsafe_code`, but do make use of it for some low level primitives (e.g. http core)\nor indirectly because of bindgens to C (e.g. boring).\n\nWe also make use of [`cargo vet`](https://github.com/mozilla/cargo-vet) to [audit our supply chain](./supply-chain/).\n\n## 🦀 | Compatibility\n\nRama (ラマ) is developed mostly on MacOS M-Series machines and run in production\non a variety of Linux systems. There is no windows support, and neither do we test on that platform.\n\n| platform | tested | test platform |\n|----------|--------|---------------|\n| MacOS    | ✅     | MacOS Apple Silicon (developer laptop) and macos-12 Intel ([GitHub Action](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners)) |\n| Linux    | ✅     | Ubuntu 22.04 ([GitHub Action](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners)) |\n\nPlease [open a ticket](https://github.com/plabayo/rama/issues) in case you have compatibility issues for your setup/platform.\nOur goal is not to support all possible platforms in the world, but we do want to\nsupport as many as we reasonably can.\n\n### Minimum supported Rust version\n\nRama's MSRV is `1.85`.\n\n[Using GitHub Actions we also test](https://github.com/plabayo/rama/blob/main/.github/workflows/CI.yml) if `rama` on that version still works on\nthe stable and beta versions of _rust_ as well.\n\n## 🧭 | Roadmap\n\nPlease refer to \u003chttps://github.com/plabayo/rama/milestones\u003e 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](https://github.com/plabayo/rama/issues) to request it and [become a sponsor](#--sponsors) if you can.\n\n## 📰 | Media Appearances\n\nRama (`0.2`)  was featured in a 📻 Rustacean episode on the 19th of May 2024, and available to listen at \u003chttps://rustacean-station.org/episode/glen-de-cauwsemaecker/\u003e. In this episode [Glen](https://www.glendc.com/) explains the history of Rama, why it exists, how it can be used and more.\n\n## 💼 | License\n\nThis project is dual-licensed under both the [MIT license][mit-license] and [Apache 2.0 License][apache-license].\n\n## 👋 | Contributing\n\n🎈 Thanks for your help improving the project! We are so happy to have\nyou! We have a [contributing guide][contributing] to help you get involved in the\n`rama` project.\n\nContributions often come from people who already know what they want, be it a fix for a bug they encountered,\nor a feature that they are missing. Please do always make a ticket if one doesn't exist already.\n\nIt's possible however that you do not yet know what specifically to contribute, and yet want to help out.\nFor that we thank you. You can take a look at the open issues, and in particular:\n\n- [`good first issue`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22): issues that are good for those new to the `rama` codebase;\n- [`easy`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy): issues that are seen as easy;\n- [`mentor available`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3A%22mentor+available%22): issues for which we offer mentorship;\n- [`low prio`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3A%22low+prio%22): 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;\n\nIn general, any issue not assigned already is free to be picked up by anyone else. Please do communicate in the ticket\nif you are planning to pick it up, as to avoid multiple people trying to solve the same one.\n\n\u003e 💡 Some issues have a [`needs input`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs+input%22+) label.\n\u003e 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\n\u003e alignment with the rama maintainers. However these\n\u003e [`needs input`](https://github.com/plabayo/rama/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs+input%22+) issues require also prior R\u0026D work:\n\u003e\n\u003e - add and discuss missing knowledge or other things not clear;\n\u003e - figure out pros and cons of the solutions (as well as what if we choose to not not resolve the issue);\n\u003e - discuss and brainstorm on possible implementations, desire features, consequences, benefits, ...\n\u003e\n\u003e Only once this R\u0026D is complete and alignment is confirmed, shall the feature be started to be implemented.\n\nShould you want to contribute to 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](https://rust-lang.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 \u003chttps://www.glendc.com/\u003e.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in `rama` by you, shall be licensed as both [MIT][mit-license] and [Apache 2.0][apache-license],\nwithout any additional terms or conditions.\n\n[contributing]: https://github.com/plabayo/rama/blob/main/CONTRIBUTING.md\n[mit-license]: https://github.com/plabayo/rama/blob/main/LICENSE-MIT\n[apache-license]: https://github.com/plabayo/rama/blob/main/LICENSE-APACHE\n\n### Acknowledgements\n\nSpecial thanks goes to all involved in developing, maintaining and supporting [the Rust programming language](https://www.rust-lang.org/), the [Tokio ecosystem](https://tokio.rs/) and [all other crates](./Cargo.toml) that we depend upon. This also includes [Hyper and its ecosystem](https://github.com/hyperium) 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.\n\nExtra credits also go to [Axum](https://github.com/tokio-rs/axum), from which ideas and code were copied as it's 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][Tower], its inventors and all the people and creatures that help make it be every day. The service concept is derived from [Tower][Tower] and many of our layers are a [Tower][Tower] fork, adapted where required or desired.\n\nAn 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.\n\n[Tower]: https://github.com/tower-rs/tower\n\n## 💖 | Sponsors\n\nRama is **completely free, open-source software** which needs lots of effort and time to develop and maintain.\n\nYou can become a regular financial contributor to Rama by paying for a monthly subscription at [Github Sponsors][ghs-url]. One time contributions are possible as well.\n\nSponsors help us continue to maintain and improve `rama`, as well as other\nFree and Open Source (FOSS) technology. It also helps us to create\neducational content such as \u003chttps://github.com/plabayo/learn-rust-101\u003e,\nand other open source libraries such as \u003chttps://github.com/plabayo/tokio-graceful\u003e and \u003chttps://venndb.rs\u003e.\n\nNext to the many unpaid developer hours we put in a project such as `rama`,\nwe also have plenty of costs, such as services ranging from hosting to Docker,\nbut also tooling for developers and automated processing. All these costs money.\n\nSponsors receive perks and depending on your regular contribution it also\nallows you to rely on us for support and consulting.\n\nFinally, you can also support us by shopping Plabayo \u003c3 `ラマ` merchandise 🛍️ at \u003chttps://plabayo.threadless.com/\u003e.\n\n[![Plabayo's Store With Rama Merchandise](./docs/img/plabayo_mech_store_rama.png)](https://plabayo.threadless.com/)\n\n### Rama Sponsors\n\nWe 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][ghs-url]. One time payments are accepted [at GitHub][ghs-url] as well as at [\"Buy me a Coffee\"][bmac-url]. One-time and monthly financial contributions are also possible via Paypal, should you feel more at ease with that at [\"Paypal Donations\"][paypal-url].\n\nIf you wish to financially support us through other means you can best\nstart a conversation with us by sending an email to [glen@plabayo.tech](mailto:glen@plabayo.tech).\n\n#### Premium Partners\n\n* [fly.io](https://fly.io)\n* [BrowserStack](https://browserstack.com)\n\nRama (ラマ) is bundled with Http/Tls emulation data, gathered for all major platforms and browsers using real devices by [BrowserStack](https://browserstack.com). It does this automatically every day by using [our public Fingerprinting service](https://fp.ramaproxy.org) which is hosted together with a database on [fly.io](https://fly.io).\n\nWe are grateful to both sponsors for sponsering us these cloud resources.\n\n### Professional Services\n\n🤝 Enterprise support, software customisations, integrations, professional support, consultancy and training are available upon request by sending an email to [glen@plabayo.tech](mailto:glen@plabayo.tech). Or get an enterprise subscription via [Gihub Sponsors](https://github.com/sponsors/plabayo/sponsorships?tier_id=300734).\n\nThese type of contracts are another way for you to be able to support the project and\nat the same time get serviced for your own needs and purposes.\n\nRama is licensed as both [MIT][mit-license] and [Apache 2.0][apache-license], as such you are free to use\nand modify the source code for any purposes, including commercial goals. That said, we would appreciate it\nif you would consider becoming a sponsor of the project if you do end up using it for commcercial reasons.\n\n## 🌱 | Alternatives\n\nWhile there are a handful of proxies written in Rust, there are only two other Rust frameworks\nspecifically made for proxy purposes. All other proxy codebases are single purpose code bases,\nsome even just for learning purposes. Or are actually generic http/web libraries/frameworks\nthat facilitate proxy features as an extra.\n\n[Cloudflare] has been working on a proxy service framework, named [`pingora`], since a couple of years already,\nand on the 28th of February of 2024 they also open sourced it.\n\nRama is not for everyone, but we sure hope it is right for you.\nIf not, consider giving [`pingora`] a try, it might very well be the next best thing for you.\n\nSecondly, [ByteDance] has an open source proxy framework written in Rust to develop forward\nand reverse proxies alike, named [`g3proxy`].\n\n[Cloudflare]: https://www.cloudflare.com/\n[`pingora`]: https://github.com/cloudflare/pingora\n[ByteDance]: https://www.bytedance.com/en/\n[`g3proxy`]: https://github.com/bytedance/g3\n\n## ❓| FAQ\n\nAvailable at \u003chttps://ramaproxy.org/book/faq.html\u003e.\n\n## ⭐ | Stargazers\n\n[![Star History Chart](https://api.star-history.com/svg?repos=plabayo/rama\u0026type=Date)](https://star-history.com/#plabayo/rama\u0026Date)\n\n[![original (OG) rama logo](./docs/book/src/img/old_logo.png)](https://ramaproxy.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplabayo%2Frama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplabayo%2Frama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplabayo%2Frama/lists"}