rama 0.3.0-rc1

modular service framework
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456

//! ๐Ÿฆ™ **rama** (ใƒฉใƒž) is a modular network service and proxy framework for the ๐Ÿฆ€ Rust language.
//!
//! It gives you programmable control over how packets move through your stack so you can build:
//!
//! - production grade reverse and forward proxies
//! - HTTP and TLS termination layers
//! - security inspection and distortion proxies
//! - high volume scraping and data extraction pipelines
//! - custom HTTP clients with deep control over the wire
//!
//! rama is already used in production by companies at scale for use cases such as network
//! security, data extraction, API gateways and routing.
//!
//! rama is async first and uses [`tokio`](https://tokio.rs) as its only async runtime.
//!
//! ---
//!
//! ## At a glance
//!
//! New here? Start with the [book](https://ramaproxy.org/book) for narrative explanations
//! and the [examples](https://github.com/plabayo/rama/tree/main/examples) to see real code.
//! Use this section to jump straight into the API.
//!
//! **Core abstractions** (always available, re-exported from
//! [`rama-core`](https://docs.rs/rama-core)):
//!
//! - [`Service`] โ€” central trait: takes a request, produces a response or error
//! - [`Layer`] โ€” wraps a [`Service`] to add behavior (timeouts, retries, telemetry, โ€ฆ)
//! - support: [`error`], [`graceful`], [`rt`], [`combinators`], [`extensions`], [`matcher`],
//!   [`stream`], [`io`], [`bytes`], [`futures`]
//!
//! **Networking (transports and primitives)**:
//!
//! - [`tcp`] ยท [`udp`] ยท `unix` โ€” listeners, connectors, sockets
//! - [`net`] โ€” shared addresses / sockets / fingerprints (Apple-only items live in
//!   `net::apple`)
//! - [`dns`] โ€” DNS resolvers and types (native resolvers or opt-in HickoryDNS)
//! - [`tls`] โ€” TLS via [rustls](`tls::rustls`) / [boring](`tls::boring`) and
//!   [`tls::acme`](`tls::acme`)
//!
//! **Application protocols**:
//!
//! - [`http`] โ€” HTTP/1 + HTTP/2: [`http::server`], [`http::client`],
//!   [`http::layer`], [`http::service`], [`http::tls`], [`http::ws`], [`http::grpc`],
//!   [`http::proxy`]
//! - [`proxy`] โ€” proxy primitives, [`proxy::socks5`], [`proxy::haproxy`]
//!
//! **Cross-cutting**:
//!
//! - [`telemetry`] โ€” tracing and OpenTelemetry
//! - [`json`] โ€” streaming JSON tokenizer, JSONPath selection, and rewriting utilities
//! - [`ua`] โ€” User-Agent emulation and fingerprinting
//! - [`utils`] (incl. [`utils::tower`] for tower compat), [`crypto`], [`cli`]
//!
//! **Common entry points** for first-time readers:
//!
//! - HTTP client: [`http::client::EasyHttpWebClient`] +
//!   [`http::service::client::HttpClientExt`]
//! - HTTP server / web service: [`http::server`] and [`http::service::web`]
//! - SOCKS5 server: [`proxy::socks5`]
//! - Reverse / forward proxy: [`http::proxy`] (HTTP CONNECT) +
//!   [`proxy::socks5`] / [`proxy::haproxy`]
//! - L4 transparent proxy
//!   - On Linux: rama services on top of `IP_TRANSPARENT` / `TPROXY`. See the
//!     [`linux_tproxy_tcp`](https://github.com/plabayo/rama/blob/main/examples/linux_tproxy_tcp.rs)
//!     example (with companion setup / cleanup scripts in the same directory).
//!   - On macOS / iOS: platform-specific submodules of [`net`] bridge Apple
//!     [NetworkExtension](https://developer.apple.com/documentation/networkextension)
//!     flows into rama services and host โ†” extension IPC over
//!     [Apple XPC](https://developer.apple.com/documentation/xpc). Available behind
//!     the `net-apple-networkextension` and `net-apple-xpc` features (browse them
//!     under [`net`] in the docs built on an Apple vendor target. See the
//!     [`tproxy` example](https://github.com/plabayo/rama/tree/main/ffi/apple/examples/transparent_proxy)
//!     for an end-to-end setup including the system-extension scaffolding.
//!
//! ---
//!
//! ## Who is rama for
//!
//! - **Developers and teams** who want fine grained control over transport, TLS and HTTP
//!   while staying in safe Rust.
//! - **Organisations** that need a partner to:
//!   - maintain and evolve a proxy or network platform
//!   - build custom features on top of rama
//!   - get support and training for internal teams
//!
//! ---
//!
//! ## Getting started
//!
//! 1. Read the ["Why rama" chapter](https://ramaproxy.org/book/why_rama) for background.
//! 2. Run one of the examples in
//!    <https://github.com/plabayo/rama/tree/main/examples>.
//! 3. Use the rama book at <https://ramaproxy.org/book> and the Rust docs at
//!    <https://docs.rs/rama> or <https://ramaproxy.org/docs/rama> as references
//!    while building your own stack.
//!
//! You can also use the `rama` binary if you want to use some of the rama features from the command line
//! without writing your own Rust code. See <https://ramaproxy.org/book/deploy/rama-cli.html>.
//!
//! ---
//!
//! ## For organisations
//!
//! If your organisation relies on rama or plans to, the maintainers offer:
//!
//! - support and maintenance contracts
//! - feature development with higher priority or extended scope
//! - consulting and integration work around proxies, scraping and security
//! - training and mentoring for your internal teams
//!
//! To discuss options, contact `hello@plabayo.tech`.
//!
//! Enterprise sponsorships are available via GitHub Sponsors and help fund development,
//! maintenance and ecosystem work.
//!
//! ---
//!
//! ## Batteries included
//!
//! rama ships with batteries included for transports, HTTP, TLS, DNS, proxy protocols,
//! telemetry, fingerprinting and more. Some highlights:
//!
//! - transports: TCP, UDP, Unix domain sockets, connection pooling and middleware
//! - HTTP: HTTP 1 and 2 servers and clients, layers and middleware, metrics, tracing
//! - TLS: Rustls and BoringSSL support
//! - proxy protocols: HTTP connect, HTTPS connect, SOCKS5, HAProxy PROXY protocol
//! - fingerprinting and user agent emulation for distortion and anti bot use cases
//! - telemetry: tracing integration and OpenTelemetry metrics for HTTP and transport layers
//!
//! For a detailed and up to date overview see the feature table in the README and the
//! relevant chapters in the rama book.
//!
//! ---
//!
//! ## Proxies and proxy focused use cases
//!
//! The primary focus of rama is to help you build proxies and proxy like services:
//!
//! - reverse proxies
//! - TLS termination proxies
//! - HTTP and HTTPS proxies
//! - SOCKS5 proxies
//! - SNI based routing proxies
//! - MITM proxies
//! - distortion proxies with UA emulation and fingerprinting
//!
//! The proxy chapters in the book start at
//! <https://ramaproxy.org/book/proxies/intro.html>.
//!
//! Distortion support includes User Agent emulation for HTTP and TLS built on top of data
//! collected by [`rama-fp`](https://github.com/plabayo/rama/tree/main/rama-fp) and exposed
//! via <https://fp.ramaproxy.org>.
//!
//! ---
//!
//! ## Web services
//!
//! Even though proxies are the main focus, rama can also be used to build general purpose
//! web services. Typical use cases:
//!
//! - dynamic HTTP endpoints
//! - serving static files
//! - websockets and Server Sent Events (SSE)
//! - health and readiness endpoints for Kubernetes
//! - metrics and control plane services
//!
//! rama gives you:
//!
//! - async method trait based services and layers
//! - modular middleware to reuse across services and clients
//! - full control from transport through TLS to HTTP and web protocols
//!
//! Learn more in the web servers chapter of the book:
//! <https://ramaproxy.org/book/web_servers.html>.
//!
//! ### Datastar integration
//!
//! rama has built in support for [Datastar](https://data-star.dev) for reactive web
//! applications using SSE. See the examples at
//! <https://github.com/plabayo/rama/tree/main/examples> and the docs at:
//!
//! - <https://ramaproxy.org/docs/rama/http/sse/datastar/index.html>
//! - <https://ramaproxy.org/docs/rama/http/service/web/extract/datastar/index.html>
//! - <https://ramaproxy.org/docs/rama/http/service/web/response/struct.DatastarScript.html>
//!
//! ---
//!
//! ## Web clients
//!
//! A large part of rama is built on top of a service concept. A `Service` takes a `Request`
//! and produces a `Response` or `Error`. Services can be leaf services or middlewares that
//! wrap inner services.
//!
//! rama provides:
//!
//! - an `EasyHttpWebClient` for HTTP requests
//! - many HTTP layers to tune timeouts, retries, telemetry and more
//! - a high level `HttpClientExt` trait to build and send requests with a fluent API
//!
//! See the client example at
//! <https://github.com/plabayo/rama/tree/main/examples/http_high_level_client.rs> and the
//! docs at:
//!
//! - <https://ramaproxy.org/docs/rama/http/client/struct.EasyHttpWebClient.html>
//! - <https://ramaproxy.org/docs/rama/http/service/client/trait.HttpClientExt.html>
//!
//! ---
//!
//! ## Ecosystem
//!
//! 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`](https://crates.io/crates/rama): one crate to rule them all
//! - [`rama-error`](https://crates.io/crates/rama-error): error utilities for rama and its users
//! - [`rama-macros`](https://crates.io/crates/rama-macros): contains the procedural macros used by `rama`
//! - [`rama-utils`](https://crates.io/crates/rama-utils): utilities crate for rama
//! - [`rama-ws`](https://crates.io/crates/rama-ws): WebSocket (WS) support for rama
//! - [`rama-core`](https://crates.io/crates/rama-core): core crate containing the service and layer traits
//!   used by all other `rama` code, as well as some other _core_ utilities
//! - [`rama-crypto`](https://crates.io/crates/rama-crypto): rama crypto primitives and dependencies
//! - [`rama-net`](https://crates.io/crates/rama-net): rama network types and utilities
//! - [`rama-net-apple-networkextension`](https://crates.io/crates/rama-net-apple-networkextension): Apple Network Extension support for rama
//! - [`rama-net-apple-xpc`](https://crates.io/crates/rama-net-apple-xpc): Apple XPC support for rama
//! - [`rama-dns`](https://crates.io/crates/rama-dns): DNS support for rama
//! - [`rama-unix`](https://crates.io/crates/rama-unix): Unix (domain) socket support for rama
//! - [`rama-tcp`](https://crates.io/crates/rama-tcp): TCP support for rama
//! - [`rama-udp`](https://crates.io/crates/rama-udp): UDP support for rama
//! - [`rama-tls-acme`](https://crates.io/crates/rama-tls-acme): ACME support for rama
//! - [`rama-tls-boring`](https://crates.io/crates/rama-tls-boring): [Boring](https://github.com/plabayo/rama-boring) tls support for rama
//! - [`rama-tls-rustls`](https://crates.io/crates/rama-tls-rustls): [Rustls](https://github.com/rustls/rustls) support for rama
//! - [`rama-proxy`](https://crates.io/crates/rama-proxy): proxy types and utilities for rama
//! - [`rama-socks5`](https://crates.io/crates/rama-socks5): SOCKS5 support for rama
//! - [`rama-haproxy`](https://crates.io/crates/rama-haproxy): rama HAProxy support
//! - [`rama-ua`](https://crates.io/crates/rama-ua): User-Agent (UA) support for `rama`
//! - [`rama-http-types`](https://crates.io/crates/rama-http-types): http types and utilities
//! - [`rama-http-headers`](https://crates.io/crates/rama-http-headers): typed http headers
//! - [`rama-json`](https://crates.io/crates/rama-json): streaming JSON tokenizer, JSONPath selection, and rewriting utilities
//! - [`rama-grpc`](https://crates.io/crates/rama-grpc): Grpc support for rama
//! - [`rama-grpc-codegen`](https://crates.io/crates/rama-grpc-codegen): Grpc codegen support for rama
//! - [`rama-http`](https://crates.io/crates/rama-http): rama http services, layers and utilities
//! - [`rama-http-macros`](https://crates.io/crates/rama-http-macros): proc-macros powering the type-safe HTML templating in `rama-http::protocols::html`
//! - [`rama-http-backend`](https://crates.io/crates/rama-http-backend): default http backend for `rama`
//! - [`rama-http-core`](https://crates.io/crates/rama-http-core): http protocol implementation driving `rama-http-backend`
//! - [`rama-http-hyperium`](https://crates.io/crates/rama-http-hyperium): conversions between rama and the hyperium `http` crate (ecosystem interop)
//! - [`rama-tower`](https://crates.io/crates/rama-tower): provide [tower](https://github.com/tower-rs/tower) compatibility for `rama`
//!
//! `rama` crates that live in <https://github.com/plabayo/rama-boring> (forks of `cloudflare/boring`):
//!
//! - [`rama-boring`](https://crates.io/crates/rama-boring): BoringSSL bindings for rama
//! - [`rama-boring-sys`](https://crates.io/crates/rama-boring-sys): FFI bindings to BoringSSL for rama
//! - [`rama-boring-tokio`](https://crates.io/crates/rama-boring-tokio): an implementation of SSL streams for Tokio backed by BoringSSL in function of rama
//!
//! repositories in function of rama that aren't crates:
//!
//! - <https://github.com/plabayo/rama-boringssl>:
//!   Fork of [mirror of BoringSSL](https://github.com/plabayo/rama-boringssl)
//!   in function of [rama-boring](https://github.com/plabayo/rama-boring)
//! - <https://github.com/plabayo/homebrew-rama>: Homebrew formula for the rama Cli tool
//!
//! Repositories that we maintain and are re exported by the root `rama` crate:
//!
//! - <https://github.com/plabayo/tokio-graceful>: Graceful shutdown util for Rust projects using the Tokio Async runtime.
//!
//! Community crates that extend the ecosystem are encouraged. If you publish a community
//! crate, please prefix it with `rama-x` so it is easy to discover and clearly distinct
//! from the official crates in this repository.
//!
//! ---
//!
//! ## Safety and compatibility
//!
//! - rama crates avoid `unsafe` Rust as much as possible and use it only where necessary.
//! - Supply chain auditing is done with [`cargo vet`](https://github.com/mozilla/cargo-vet).
//! - Tier 1 platforms include macOS, Linux and Windows on modern architectures.
//! - The minimum supported Rust version (MSRV) is `1.96`.
//!
//! For details see the compatibility section in the README and the CI configuration in
//! the repository.
//!
//! ---
//!
//! ## License
//!
//! rama is free and open source software, dual licensed under MIT and Apache 2.0.
//!
//! You can use rama for commercial and non commercial purposes. If rama becomes an
//! important part of your stack, please consider supporting the project as a sponsor
//! or partner.
//!
//! ---
//!
//! ## Community and links
//!
//! - Official website: <https://ramaproxy.org>
//! - Rama Book index: <https://ramaproxy.org/book>
//! - Rust docs: <https://docs.rs/rama> (latest release) and <https://ramaproxy.org/docs/rama> (edge)
//! - Repository and issues: <https://github.com/plabayo/rama>
//! - Discord: <https://discord.gg/29EetaSYCD>
//! - FAQ: <https://ramaproxy.org/book/faq.html>
//! - Netstack FM podcast: <https://netstack.fm> (podcast about networking and Rust)
//!
//! If you are not sure where to start, read "Why rama" in the book, run a proxy example and then
//! iterate from there with the book and docs at hand.

#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/plabayo/rama/main/docs/img/old_logo.png"
)]
#![doc(html_logo_url = "https://raw.githubusercontent.com/plabayo/rama/main/docs/img/old_logo.png")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
#![cfg_attr(test, allow(clippy::float_cmp))]

#[doc(inline)]
pub use ::rama_core::{
    Layer, Service, bytes, combinators, conversion, error, error_sink, extensions, futures, geo,
    layer, matcher, service, username,
};

#[cfg(feature = "std")]
#[doc(inline)]
pub use ::rama_core::{ServiceInput, graceful, io, rt, stream};

#[cfg(feature = "std")]
#[doc(inline)]
pub use ::rama_json as json;

#[cfg(all(feature = "std", feature = "crypto"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "crypto"))))]
#[doc(inline)]
pub use ::rama_crypto as crypto;

#[cfg(all(target_family = "unix", feature = "unix"))]
#[cfg_attr(docsrs, doc(cfg(all(target_family = "unix", feature = "unix"))))]
#[doc(inline)]
pub use ::rama_unix as unix;

#[cfg(all(feature = "std", feature = "tcp"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "tcp"))))]
#[doc(inline)]
pub use ::rama_tcp as tcp;

#[cfg(all(feature = "std", feature = "udp"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "udp"))))]
#[doc(inline)]
pub use ::rama_udp as udp;

#[cfg(feature = "std")]
pub mod telemetry;

#[cfg(any(
    all(feature = "std", feature = "tls"),
    all(feature = "std", feature = "rustls"),
    all(feature = "std", feature = "boring"),
    all(feature = "std", feature = "acme")
))]
pub mod tls;

#[cfg(all(feature = "std", feature = "dns"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "dns"))))]
#[doc(inline)]
pub use ::rama_dns as dns;

#[cfg(feature = "net")]
pub mod net {
    #[cfg_attr(docsrs, doc(cfg(feature = "net")))]
    #[doc(inline)]
    pub use ::rama_net::*;

    #[cfg(any(
        all(doc, docsrs),
        all(
            target_vendor = "apple",
            any(feature = "net-apple-networkextension", feature = "net-apple-xpc")
        )
    ))]
    #[cfg_attr(docsrs, doc(cfg(target_vendor = "apple")))]
    pub mod apple {
        //! Apple (vendor) specific network modules

        #[cfg(feature = "net-apple-networkextension")]
        #[cfg_attr(docsrs, doc(cfg(feature = "net-apple-networkextension")))]
        #[doc(inline)]
        pub use ::rama_net_apple_networkextension as networkextension;

        #[cfg(feature = "net-apple-xpc")]
        #[cfg_attr(docsrs, doc(cfg(feature = "net-apple-xpc")))]
        #[doc(inline)]
        pub use ::rama_net_apple_xpc as xpc;
    }
}

#[cfg(all(feature = "std", feature = "http"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "http"))))]
pub mod http;

#[cfg(any(
    all(feature = "std", feature = "proxy"),
    all(feature = "std", feature = "haproxy"),
    all(feature = "std", feature = "socks5")
))]
pub mod proxy {
    //! rama proxy support

    #[cfg(feature = "proxy")]
    #[cfg_attr(docsrs, doc(cfg(feature = "proxy")))]
    #[doc(inline)]
    pub use ::rama_proxy::*;

    #[cfg(feature = "haproxy")]
    #[cfg_attr(docsrs, doc(cfg(feature = "haproxy")))]
    #[doc(inline)]
    pub use ::rama_haproxy as haproxy;

    #[cfg(feature = "socks5")]
    #[cfg_attr(docsrs, doc(cfg(feature = "socks5")))]
    #[doc(inline)]
    pub use ::rama_socks5 as socks5;
}

/// Application server gateway protocols (FastCGI, and similar).
#[cfg(all(feature = "std", feature = "fastcgi"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "fastcgi"))))]
pub mod gateway {
    #[cfg(feature = "fastcgi")]
    #[cfg_attr(docsrs, doc(cfg(feature = "fastcgi")))]
    #[doc(inline)]
    pub use ::rama_fastcgi as fastcgi;
}

#[cfg(all(feature = "std", feature = "ua"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "ua"))))]
#[doc(inline)]
pub use ::rama_ua as ua;

#[cfg(all(feature = "std", feature = "cli"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "std", feature = "cli"))))]
pub mod cli;

pub mod utils {
    //! utilities for rama

    #[doc(inline)]
    pub use ::rama_utils::*;

    #[cfg(feature = "tower")]
    #[cfg_attr(docsrs, doc(cfg(feature = "tower")))]
    #[doc(inline)]
    pub use ::rama_tower as tower;
}