Lib.rs

🦙 Rama (ラマ) 是一个为 🦀 Rust 语言设计的模块化服务框架，用于移动和转换您的网络数据包。关于创建拉马的原因，可以阅读 “为什么选择拉马”章节。

拉马是异步优先的，使用 Tokio 作为其 唯一 的异步运行时。请参考 位于 /examples 目录中的示例，以获得如何将其用于您的目的的灵感。

💡 如果您的组织依赖于 Rama (ラマ) 进行运营，我们邀请您考虑成为赞助商 💖。通过支持我们的项目，您将帮助确保其持续的发展和成功。有关赞助机会的更多信息，请参阅下面的 “赞助商”部分 或直接联系我们在 [email protected]。

此框架内置了 🔋 电池，让您完全自由地构建您想要的中间件和服务，而无需重复“通用”

🗒️ 脚注

• ⁽¹⁾ 属于 v0.2.0 里程碑 (预计：2024 年第三季度中)
• ⁽²⁾ 属于 v0.3.0 里程碑 (预计：2024 年第三季度末)
• ⁽³⁾ 目前没有计划，但已纳入我们的考虑范围内。如果您迫切需要此功能，请 提交问题。请提供充分的动机/理由，并考虑 成为赞助商 以帮助加速其优先级。

Rama 的主要重点是帮助您开发 代理

• 🚦 反向代理；
• 🔓 TLS 终止代理；
• 🌐 HTTP(S) 代理；
• 🧦 SOCKS5 代理 (将在 v0.3 中实现)；
• 🔎 MITM 代理；
• 🕵️‍♀️ 扭曲代理。

💡 请查看 Rama 书籍中的 "代理简介" 章节以了解更多关于不同类型代理的信息。如果您是代理开发新手，这可能有所帮助。

扭曲代理支持包含 用户代理 (UA) 模拟功能。通过使用 rama-fp 提取的模式和数据，实现了模拟。该服务在 https://fp.ramaproxy.org 公开提供，由我们的赞助商主机 https://fly.io/ 实现。

🔁 另一个公开提供的服务是 https://echo.ramaproxy.org/。与指纹服务相比，它面向开发者，允许您发送任何您希望的 HTTP 请求，以便在发送请求时了解服务器从您那里接收的 TLS 信息和 HTTP 请求信息。

curl -XPOST 'https://echo.ramaproxy.org/foo?bar=baz' \
  -H 'x-magic: 42' --data 'whatever forever'

您可以在构建扭曲的 HTTP 请求时自由使用它，但请适度使用。如果您有任何改进服务的想法，请通过 提交问题 告诉我们。

使用 rama 二进制文件，您还可以自己运行 echo 和 fp 服务，本地或作为外部面对服务的网络服务。

如果您计划向 echo 服务发送大量流量，请运行您自己的 echo 服务，而不是使用 echo.ramaproxy.org。

BrowserStack 通过提供真实设备上的跨平台浏览器自动化测试来赞助 Rama，该服务使用公共指纹服务来帮助在 HTTP 和 TLS 层面上进行自动指纹收集。按设计，我们不考虑 Tcp 和 Udp 指纹。

除了代理外，Rama 还可用于开发 Web 服务 和 HTTP 客户端。

• 通过阅读 https://ramaproxy.org/book 中的 Rama 书籍了解更多信息；
• 或者查看Rama框架的文档：https://docs.rs/rama;
  • 边缘文档（主分支）可以在https://ramaproxy.org/docs/rama找到。

📖 Rama的完整文档、参考材料和背景资料可以以“rama书”的形式在https://ramaproxy.org/book找到。

💬 加入我们的Discord频道#rama，链接：Discord。在这里可以提问、讨论想法以及了解Rama如何为您所用。

⌨️ | rama二进制文件

rama二进制文件允许您使用Rama的大部分功能，而无需自己编写代码。它包含用于CLI的工作HTTP客户端，模拟User-Agent并提供其他实用工具。它还包含IP/Echo服务。

它还允许您运行一个配置满足您需求的rama代理。

更多关于rama二进制文件及其安装信息，请访问https://ramaproxy.org/book/binary/rama。

🧪 | 实验

🦙 Rama（ラマ）在可预见的未来被视为实验性软件。同时，我们和他人已在生产中使用。这很好，因为它为我们提供了新的视角和数据，以进一步改进和扩展框架。但这意味着，在0.2之后，还将有多个不向后兼容的版本发布。

同时，Rust的异步生态系统也在成熟，预计2024年也将迎来2024年的年终礼物。不言而喻，我们不会随意更改设计或故意破坏。核心设计现在也已经非常明确。但必须说，还有很多需要改进和解决的问题。您的生产使用和其他用户的反馈对此有很大帮助。因此，如果您使用Rama，请通过Discord、电子邮件或GitHub问题告诉我们您的反馈。

👉 如果您是使用Rama的公司或企业，或者甚至是个体用户，为了商业目的使用Rama，请考虑成为商业/企业订阅者。这有助于使开发周期保持可持续，同时也对您有益。作为您的好处之一，我们还可以协助您在破坏性发布之间进行迁移。对于企业用户，我们甚至可以代表您自己开发集成代码库中的PR。这对每个人都是双赢。💪

🏢 | 代理示例

• /examples/tls_termination.rs：启动一个迷你手工HTTP服务器以及一个TLS终止代理，将明文流转发到第一个。
• /examples/tls_termination.rs：启动一个迷你手工HTTP服务器以及一个TLS终止代理，将明文流转发到第一个。
• /examples/mtls_tunnel_and_service.rs：如何使用Rama进行mTls（手动Tls，客户端也需要证书）的示例，以及如何使用此概念提供隧道服务的示例；
• /examples/http_connect_proxy.rs：启动一个最小的HTTP代理，它接受http/1.1和h2连接，并将它们代理到目标主机。

🌐 | 网络服务

开发代理是Rama（ラマ）的主要关注点。但它也可以用于开发网络服务，用于提供网页、Http API和静态内容。这带来了与使用Rama开发代理时相同的许多好处。

• 使用异步方法特质；
• 使用扩展以及强类型状态重用类似Tower的中间件；
• 能够从传输层（Tcp、Udp）到Tls和Http，全面控制您的Web堆栈；
• 如果您只关心Http层，那也完全没问题。
• 相信您的传入应用程序Http数据没有被修改（例如，Http头大小写和顺序保持不变）；
• 轻松在请求层和高层功能上开发您的服务，选择由您决定，并可组合使用。

以下是一些您可能使用rama结合您的代理服务构建的Web服务示例

• 一个k8s健康服务（/examples/http_k8s_health.rs）；
• 一个指标暴露服务；
• 一个最小化的api服务（例如，用于暴露设备配置文件或证书）；
• 一个图形界面/控制面板；

📖 在Rama书中了解更多关于开发Web服务的信息：https://ramaproxy.org/book/web_servers.html。

🌐 | Web服务示例

以下是一些没有花哨功能的底层Web服务示例

• /examples/http_listener_hello.rs：这是如何提供一个无需端点或其他任何东西的根服务的最基本示例（例如，对于一些与健康服务或指标暴露相关的用例来说足够好）；
  • /examples/http_health_check.rs是一个更简化的健康检查服务示例，它对任何传入请求都返回200 OK。
• /examples/http_service_hello.rs：与前面的示例类似，但展示了您还可以在将数据传递给Http服务之前对底层传输（TCP）层进行操作；

还有一个现成的webservice，可以用作代理k8s工作负载的健康服务

• /examples/http_k8s_health.rs：内置的web服务，可以作为部署为k8s部署的代理的k8s健康服务使用；

以下是一些使用请求/状态提取器和IntoResponse转换器的高级概念示例，这些概念您在axum中已经熟悉，同样也适用于rama服务

• /examples/http_key_value_store.rs：一个Web服务示例，展示了如何使用Rama实现键值存储Web服务；
• /examples/http_web_service_dir_and_api.rs：一个Web服务示例，展示了如何构建一个Web服务来提供包含XHR API的网站；

对于类似生产环境的Web服务示例，您还可以阅读rama cli fp cmd源代码。这是Rama指纹服务背后的webservice，该服务由🦙 Rama（ラマ）的维护者使用，以生成Http和TLS层的UA仿真数据。它不是用来指纹人类或用户的。相反，它是用来帮助自动化过程看起来像人类。

💡 此示例展示了如何使用match_service宏来创建一个无Box的服务路由器。此方法的其他示例可以在http_service_match.rs示例中看到。

🧑‍💻 | Http客户端

在《rama书》中，你可以阅读并学习到，Rama架构的一个大支柱是基于服务概念构建的。一个Service将用户定义的State（例如包含你的数据库池）和一个Request作为输入，并使用它来提供Response或Error。这样的Service可以直接产生响应（也称为☘️Leaf服务）或者将请求和状态传递给它包装的内部Service（所谓🍔Middlewares）。

这是一个强大的概念，最初由Tower生态系统引入到Rust中，允许你以模块化和简单的方式构建满足你需求的复杂堆栈。更酷的是，这对客户端和服务器都适用。

Rama提供了一个HttpClient，它通过网络发送你的Http Request，并在接收到并读取响应或错误时返回。结合Rama提供的众多层（中间件）以及你可能开发的一些，可以创建一个满足你需求的强大Http客户端。

作为🍒蛋糕上的樱桃，你可以在你的Rust模块中导入HttpClientExt特性，以便能够使用高级API轻松构建和发送请求来使用你的Http客户端Service堆栈。

🧑‍💻 | Http客户端示例

💡完整的“高级”示例可以在/examples/http_high_level_client.rs找到。

use rama::http::client::HttpClientExt;

let client = (
    TraceLayer::new_for_http(),
    DecompressionLayer::new(),
    AddAuthorizationLayer::basic("john", "123")
        .as_sensitive(true)
        .if_not_present(),
    RetryLayer::new(
        ManagedPolicy::default().with_backoff(ExponentialBackoff::default()),
    ),
).layer(HttpClient::default());

#[derive(Debug, Deserialize)]
struct Info {
    name: String,
    example: String,
    magic: u64,
}

let info: Info = client
    .get("http://example.com/info")
    .header("x-magic", "42")
    .typed_header(Accept::json())
    .send(Context::default())
    .await
    .unwrap()
    .try_into_json()
    .await
    .unwrap();

⛨ | 安全性

这个crate使用#![forbid(unsafe_code)]来确保所有内容都是在100%安全的Rust中实现的。

我们还使用了cargo vet来审计我们的供应链。

🦀 | 兼容性

Rama（ラマ）主要在MacOS M-Series机器上开发，并在各种Linux系统上运行生产环境。没有Windows支持，并且我们也没有在该平台上进行测试。

如果你在设置/平台上遇到兼容性问题，请打开一个票据。我们的目标不是支持世界上所有可能的平台，但我们确实希望尽可能多地支持。

最小支持的Rust版本

Rama的MSRV是1.75