Rama

https://ramaproxy.org/book/
Admin
Rama is a modular network service and proxy framework for the Rust language, providing fine-grained,...
Tokens:23,851
Snippets:403
Trust Score:7.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run PHP-FPM Integration Examples

Source: https://ramaproxy.org/book/gateway/fastcgi.html

Commands to install necessary dependencies and execute the FastCGI PHP gateway and migration demos.

```bash
# install dependencies (Debian/Ubuntu)
apt-get install -y php-fpm jq curl

# run either or both
just example-fastcgi-php-gateway
just example-fastcgi-php-migration
just test-fastcgi-php           # both, sequentially
```

--------------------------------

### Install Rama CLI via Package Managers

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Install the binary using Homebrew on MacOS or Winget on Windows.

```bash
brew install plabayo/rama/rama
```

```bash
winget install Plabayo.Rama
```

--------------------------------

### Run FastCGI Reverse Proxy Example

Source: https://ramaproxy.org/book/gateway/fastcgi.html

Executes the self-contained reverse proxy example and verifies it with a curl request.

```bash
cargo run --example fastcgi_reverse_proxy --features=http-full,fastcgi
curl -v http://127.0.0.1:62053/hello?foo=bar
```

--------------------------------

### Install Rama CLI via Script

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Download and install the CLI using shell scripts with support for version pinning and pre-releases.

```bash
curl https://raw.githubusercontent.com/plabayo/rama/main/rama-cli/scripts/install.sh | bash
```

```bash
wget -qO- https://raw.githubusercontent.com/plabayo/rama/main/rama-cli/scripts/install.sh | bash
```

```bash
curl https://raw.githubusercontent.com/plabayo/rama/main/rama-cli/scripts/install.sh | bash -s -- --pre
curl https://raw.githubusercontent.com/plabayo/rama/main/rama-cli/scripts/install.sh | bash -s -- --version 0.3.0
```

--------------------------------

### Run XPC CA Exchange Example

Source: https://ramaproxy.org/book/xpc.html

Executes the CA exchange example, modeling a client requesting CA material over XPC request/reply.

```bash
cargo run --example xpc_ca_exchange --features=net-apple-xpc
```

--------------------------------

### Run XPC Echo Example

Source: https://ramaproxy.org/book/xpc.html

Executes the self-contained XPC echo example to demonstrate fire-and-forget, request-reply, and connection shutdown patterns.

```bash
cargo run --example xpc_echo --features=net-apple-xpc
```

--------------------------------

### Install Rama CLI via Cargo

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Install the CLI tool from source or using pre-built binaries via cargo binstall.

```bash
cargo install rama-cli@0.3.0
```

```bash
cargo binstall rama-cli@0.3.0
```

--------------------------------

### HTTP Chunked Transfer Example

Source: https://ramaproxy.org/book/http/declarative_partial_updates.html

A conceptual representation of how the server streams the HTML shell followed by individual fragment chunks.

```http

__
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked

  -- chunk 1: the shell with <?marker …> placeholders, flushed immediately
  -- chunk 2: <template for="ping">…</template>   (200ms later)
  -- chunk 3: <template for="herd">…</template>   (900ms later)
  -- chunk 4: <template for="recs">…</template>   (1500ms later)

```

--------------------------------

### HTTP/1.1 WebSocket Upgrade Request

Source: https://ramaproxy.org/book/http/ws.html

Initial GET request sent by a client to initiate a WebSocket upgrade over HTTP/1.1.

```http
GET / HTTP/1.1
Host: example.com
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
```

--------------------------------

### Example SSE frame

Source: https://ramaproxy.org/book/http/sse.html

A standard SSE message format containing an ID, event name, and JSON data payload.

```text

__
id: 42
event: update
data: {"status":"ok"}

```

--------------------------------

### Display Rama CLI help

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Access the help menu for the rama binary.

```bash
rama --help
```

--------------------------------

### Build and run Rama binary

Source: https://ramaproxy.org/book/deploy/overview.html

Standard commands to compile a release build and execute the resulting binary on a server or VM.

```bash
cargo build --release .
cargo run ./target/release/<my-binary>
```

--------------------------------

### Connect to php-fpm via TCP

Source: https://ramaproxy.org/book/gateway/fastcgi.html

Initializes a FastCGI HTTP client using a TCP connector configured for a php-fpm backend.

```rust
use rama::gateway::fastcgi::{FastCgiHttpClient, FastCgiTcpConnector};

// php-fpm at 127.0.0.1:9000, front controller at /var/www/index.php
let client = FastCgiHttpClient::new(FastCgiTcpConnector::php_fpm(
    "127.0.0.1:9000".parse()?,
    "/var/www/index.php",
));
```

--------------------------------

### Connect to php-fpm via Unix socket

Source: https://ramaproxy.org/book/gateway/fastcgi.html

Initializes a FastCGI HTTP client using a Unix socket connector for php-fpm, available on Unix-family targets.

```rust
use rama::gateway::fastcgi::{FastCgiHttpClient, FastCgiUnixConnector};

let client = FastCgiHttpClient::new(FastCgiUnixConnector::php_fpm(
    "/run/php/php8.3-fpm.sock",
    "/var/www/index.php",
));
```

--------------------------------

### Run Rama CLI via Docker

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Pull and execute the Rama CLI tool using a Docker container.

```bash
docker pull glendc/rama:latest
docker run --rm glendc/rama:latest example.com
```

--------------------------------

### Provision a Postgres database with Shuttle

Source: https://ramaproxy.org/book/deploy/shuttle.html

Uses the shuttle_shared_db macro to automatically provision a Postgres database and provide an authenticated connection pool.

```rust
#[shuttle_runtime::main]
async fn main(
    // Automatically provisions a Postgres database
    // and provides an authenticated connection pool
    #[shuttle_shared_db::Postgres] pool: sqlx::PgPool,
) -> Result<impl shuttle_rama::ShuttleService, shuttle_rama::ShuttleError> {
    // Application code
}
```

--------------------------------

### Service serve method signature

Source: https://ramaproxy.org/book/intro/state.html

The signature for the serve method in a Rama service, which handles requests and returns a future.

```rust
fn serve(
    &self,
    req: Request,
) -> impl Future<Output = Result<Self::Response, Self::Error>> + Send + '_;
```

--------------------------------

### Test HTTP Request with cURL

Source: https://ramaproxy.org/book/intro/user_agent.html

Use this command to inspect TLS and HTTP request information received by the echo service.

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

--------------------------------

### Interact with the Echo service

Source: https://ramaproxy.org/book/deploy/rama-cli.html

Use curl to send HTTP requests to the public echo service or connect via WebSockets using the rama binary.

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

```bash
rama wss://echo.ramaproxy.org
```

--------------------------------

### Representing Service and Layer in Pseudo Code

Source: https://ramaproxy.org/book/intro/terminology.html

A conceptual representation of how a compression layer wraps an inner service to process requests and responses.

```pseudo-code
__
struct Compression<Example>
    inner: Example

    serve(request):
        request = Compression::decompress(request)
        response = inner.serve(request)?
        return Ok(Compression::decompress(response))

struct Example
    serve(request):
        return "<p>Hello, World!</p>"

Compression::serve("HTTP GET /example")
```

--------------------------------

### Generate HTML responses with macros

Source: https://ramaproxy.org/book/web_servers.html

Use element-specific macros like html!, body!, and h1! to construct HTML. String content is automatically escaped unless wrapped in PreEscaped.

```rust
#![allow(unused)]
fn main() {
use rama::http::protocols::html::{body, h1, html, p};
use rama::http::service::web::response::IntoResponse;

async fn home(name: String) -> impl IntoResponse {
    html!(body!(
        h1!("Hello, ", name, "!"),
        p!("Welcome to ", strong_tag("rama")),
    ))
}

fn strong_tag(_: &str) -> &str { "" }
}
```

--------------------------------

### Add Rama dependency

Source: https://ramaproxy.org/book/crate.html

Use the cargo CLI to add the rama crate to your Rust project.

```bash
cargo add rama
```

--------------------------------

### Layer 3 Proxy Flow Diagram

Source: https://ramaproxy.org/book/proxies/network.html

A visual representation of the packet routing process from client to server through a Rama proxy.

```text
__
Layer 3 Proxy Flow (IP Forwarding)
----------------------------------

[ Client ] ────▶ [ L3 Proxy (rama) ] ────▶ [ Server ]
 (IP: 10.0.0.5)      (IP: 10.0.0.1)        (IP: 8.8.8.8)

1. Client sends IP packet to 8.8.8.8.
2. Network routing sends packet to 10.0.0.1 (Gateway).
3. Proxy (rama) captures packet via TUN/TPROXY.
4. Proxy creates NEW packet: Source=10.0.0.1, Dest=8.8.8.8.
5. Server sees request from Proxy IP.
```
Tokens:
Raw