### Start Relay and Demo

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Instructions to start the http-relay and its accompanying demo UI. Ensure the relay is started first, then install dependencies and run the demo.

```bash
# 1. Start the relay (from repo root)
cargo run

# 2. Start the demo (from this folder)
npm install
npm run dev
```

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

### Install http-relay CLI

Source: https://github.com/pubky/http-relay/blob/main/README.md

Install the http-relay command-line tool using Cargo. This is the primary method for quick setup and execution.

```bash
cargo install http-relay
```

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

### GET /link/{id}

Source: https://github.com/pubky/http-relay/blob/main/README.md

Legacy endpoint to retrieve a message. Blocks until the producer sends a message, with a default timeout of 10 minutes.

```APIDOC
## GET /link/{id}

### Description
Retrieve message, block until producer sends (10 min timeout)

### Method
GET

### Endpoint
/link/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the link.

### Response
#### Success Response (200 OK)
- Message retrieved.

#### Error Response (Timeout)
- Timeout occurred before producer sent the message.
```

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

### Use http-relay as a Rust Library

Source: https://github.com/pubky/http-relay/blob/main/README.md

Integrate http-relay into a Rust application using the HttpRelayBuilder. This example demonstrates setting a custom HTTP port and running the relay within a Tokio runtime.

```rust
use http_relay::HttpRelayBuilder;

#[tokio::main] async fn main() -> anyhow::Result<()> {
    let relay = HttpRelayBuilder::default()
        .http_port(15412)
        .run()
        .await?;

    println!("Running at {}", relay.local_link_url());

    tokio::signal::ctrl_c().await?;
    relay.shutdown().await
}
```

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

### GET /inbox/{id}/await

Source: https://github.com/pubky/http-relay/blob/main/README.md

Producer blocks until the consumer acknowledges the message in the specified inbox. It has a default timeout of 25 seconds.

```APIDOC
## GET /inbox/{id}/await

### Description
Producer blocks until consumer acknowledges the message.

### Method
GET

### Endpoint
/inbox/{id}/await

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the inbox.

### Request Example
```bash
curl http://localhost:8080/inbox/my-channel/await
```

### Response
#### Success Response (200 OK)
- Consumer ACKed the message

#### Error Response (408 Request Timeout)
- No ACK received within timeout (default 25s)
```

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

### GET /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/README.md

Consumer retrieves a message from the specified inbox. This endpoint supports long-polling and will wait up to 25 seconds for a message to become available.

```APIDOC
## GET /inbox/{id}

### Description
Consumer retrieves the stored message. If no message is available, waits up to 25 seconds (configurable) for one to arrive.

### Method
GET

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the inbox.

### Request Example
```bash
curl http://localhost:8080/inbox/my-channel
```

### Response
#### Success Response (200 OK)
- Returns message with original Content-Type

#### Error Response (408 Request Timeout)
- No message arrived within timeout (25s default)
```

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

### GET /inbox/{id}/ack

Source: https://github.com/pubky/http-relay/blob/main/README.md

Producer checks the acknowledgment status of a message in the specified inbox. Returns true if acknowledged, false otherwise.

```APIDOC
## GET /inbox/{id}/ack

### Description
Producer checks if message was acknowledged.

### Method
GET

### Endpoint
/inbox/{id}/ack

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the inbox.

### Request Example
```bash
curl http://localhost:8080/inbox/my-channel/ack
```

### Response
#### Success Response (200 OK)
- Body contains `true` (ACKed) or `false` (pending)

#### Error Response (404 Not Found)
- No message exists (not posted yet, or expired)
```

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

### GET /inbox/{id}/ack

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Checks the acknowledgment status for a message on a specific channel. This endpoint is intended for use by a message producer.

```APIDOC
## GET /inbox/{id}/ack

### Description
Checks the acknowledgment status for a message on a specific channel. This endpoint is intended for use by a message producer.

### Method
GET

### Endpoint
/inbox/{id}/ack

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the channel.

### Response
(Success and error response details are not specified in the source text.)
```

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

### GET /inbox/{id}/await

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Long-polls until a message on a specific channel is acknowledged. Returns a 408 status code on timeout. This endpoint is intended for use by a message producer.

```APIDOC
## GET /inbox/{id}/await

### Description
Long-polls until a message on a specific channel is acknowledged. Returns a 408 status code on timeout. This endpoint is intended for use by a message producer.

### Method
GET

### Endpoint
/inbox/{id}/await

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the channel.

### Response
#### Success Response (200)
(Response body details are not specified in the source text.)

#### Error Response (408)
(Error response details are not specified in the source text.)
```

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

### GET /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Long-polls for a message on a specific channel. Returns a 408 status code on timeout. This endpoint is intended for use by a message consumer.

```APIDOC
## GET /inbox/{id}

### Description
Long-polls for a message on a specific channel. Returns a 408 status code on timeout. This endpoint is intended for use by a message consumer.

### Method
GET

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the channel.

### Response
#### Success Response (200)
(Response body details are not specified in the source text.)

#### Error Response (408)
(Error response details are not specified in the source text.)
```

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

### Run http-relay CLI with Custom Configuration

Source: https://github.com/pubky/http-relay/blob/main/README.md

Launch the http-relay CLI with custom network bindings, timeouts, and verbosity levels. Allows fine-grained control over the relay's behavior.

```bash
# Custom configuration
http-relay --bind 0.0.0.0 --port 15412 --inbox-cache-ttl 300 --inbox-timeout 25 -vv
```

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

### Run http-relay CLI Binding to All Interfaces

Source: https://github.com/pubky/http-relay/blob/main/README.md

Configure the http-relay CLI to bind to all available network interfaces (0.0.0.0). Recommended for production or Docker environments.

```bash
# Bind to all interfaces (for production/Docker)
http-relay --bind 0.0.0.0
```

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

### Run http-relay CLI with Default Settings

Source: https://github.com/pubky/http-relay/blob/main/README.md

Execute the http-relay CLI with default settings, which binds to localhost on port 8080. Suitable for local development.

```bash
# Default: bind to 127.0.0.1:8080 (localhost only)
http-relay
```

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

### Configure Relay URL via Environment Variable

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Set the Relay URL using the NEXT_PUBLIC_RELAY_URL environment variable. This is useful for deploying the demo to different environments.

```bash
NEXT_PUBLIC_RELAY_URL=https://relay.example.com npm run dev
```

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

### Run Tests with Cargo

Source: https://github.com/pubky/http-relay/blob/main/README.md

Execute all tests for the project using the cargo test command.

```bash
cargo test
```

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

### Share Channels via URL

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Demonstrates how to share communication channels by including the channel ID in the URL query parameters. This allows friends to join the same channel by opening the provided link.

```http
http://localhost:3000?channel=my-channel
```

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

### Run with Debug Logging

Source: https://github.com/pubky/http-relay/blob/main/README.md

Execute the application with debug logging enabled by setting the RUST_LOG environment variable.

```bash
RUST_LOG=debug cargo run
```

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

### Tag and Push for Release

Source: https://github.com/pubky/http-relay/blob/main/RELEASING.md

After the version PR is merged, checkout the main branch, pull the latest changes, tag the commit with the release version, and push the tag to trigger the release workflow.

```bash
git checkout main
git pull origin main
git tag v0.7.0
git push origin v0.7.0
```

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

### Update Lockfile and Create Version PR

Source: https://github.com/pubky/http-relay/blob/main/RELEASING.md

After updating Cargo.toml, run 'cargo check' to update the lockfile. Then, create a new branch, stage changes, commit, and push to create a version PR.

```bash
cargo check
```

```bash
git checkout -b chore/v0.7.0
git add Cargo.toml Cargo.lock
git commit -m "release: v0.7.0"
git push origin chore/v0.7.0
```

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

### POST /link/{id}

Source: https://github.com/pubky/http-relay/blob/main/README.md

Legacy endpoint to send a message. Blocks until the consumer retrieves it, with a default timeout of 10 minutes.

```APIDOC
## POST /link/{id}

### Description
Send message, block until consumer retrieves (10 min timeout)

### Method
POST

### Endpoint
/link/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the link.

### Response
#### Success Response (200 OK)
- Message sent and retrieved by consumer.

#### Error Response (Timeout)
- Timeout occurred before consumer retrieved the message.
```

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

### Troubleshooting CI Build Failures

Source: https://github.com/pubky/http-relay/blob/main/RELEASING.md

If a CI build fails, delete the existing tag locally and remotely, fix the issue, commit, and then re-tag and push the new tag.

```bash
git tag -d v0.7.0
git push origin :refs/tags/v0.7.0
# fix the issue, commit, push
git tag v0.7.0
git push origin v0.7.0
```

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

### Configure Relay URL via Query Parameter

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Alternatively, the Relay URL can be specified directly in the URL using the 'relay' query parameter. This is useful for quick testing or temporary overrides.

```http
http://localhost:3000?relay=https://relay.example.com
```

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

### Store Message with cURL

Source: https://github.com/pubky/http-relay/blob/main/README.md

Use this command to store a message in an inbox. The server responds immediately upon successful storage. New messages overwrite existing ones.

```bash
curl -X POST http://localhost:8080/inbox/my-channel \
  -H "Content-Type: application/json" \
  -d '{"hello": "world"}'
```

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

### Consumer: Retrieve and ACK (JavaScript)

Source: https://github.com/pubky/http-relay/blob/main/README.md

Implement this pattern to receive messages from the relay and acknowledge their successful processing. It handles message retrieval, processing, and acknowledgment with retry logic for network issues.

```javascript
async function consumeFromRelay(channelId) {
  // Long-poll until message is available (waits up to 25s per call)
  while (true) {
    try {
      const response = await fetch(`http://relay.example.com/inbox/${channelId}`);

      if (response.status === 200) {
        const data = await response.text();

        // ACK the message (critical - producer is waiting for this)
        // Retry ACK on network error - message won't be re-delivered after success
        while (true) {
          try {
            await fetch(`http://relay.example.com/inbox/${channelId}`, {
              method: 'DELETE',
            });
            break;
          } catch (error) {
            await new Promise(resolve => setTimeout(resolve, 1000));
            continue;
          }
        }

        return data;
      }

      if (response.status === 408) {
        continue; // Timeout - no message yet, retry
      }

      throw new Error(`Unexpected status: ${response.status}`);
    } catch (error) {
      // Network error (app backgrounded, connection dropped, etc.)
      // Wait briefly then retry - message is still safe on the relay
      await new Promise(resolve => setTimeout(resolve, 1000));
      continue;
    }
  }
}
```

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

### Producer: Store and Wait for ACK (JavaScript)

Source: https://github.com/pubky/http-relay/blob/main/README.md

Use this pattern to send messages to the relay and ensure they are received and processed by a consumer. It includes logic for retrying on network errors and waiting for consumer acknowledgment.

```javascript
async function produceToRelay(channelId, data) {
  // Store the message (returns immediately)
  while (true) {
    try {
      const storeResponse = await fetch(`http://relay.example.com/inbox/${channelId}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });

      if (storeResponse.status === 200) break;
      throw new Error(`Failed to store: ${storeResponse.status}`);
    } catch (error) {
      // Network error - retry after brief delay
      await new Promise(resolve => setTimeout(resolve, 1000));
      continue;
    }
  }

  // Wait for consumer to ACK (blocks up to 25s per call)
  while (true) {
    try {
      const awaitResponse = await fetch(
        `http://relay.example.com/inbox/${channelId}/await`
      );

      if (awaitResponse.status === 200) {
        return; // Consumer ACKed - delivery confirmed
      }

      if (awaitResponse.status === 408) {
        continue; // Timeout - keep waiting
      }

      throw new Error(`Unexpected status: ${awaitResponse.status}`);
    } catch (error) {
      // Network error - retry after brief delay
      await new Promise(resolve => setTimeout(resolve, 1000));
      continue;
    }
  }
}
```

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

### Add http-relay as a Cargo Dependency

Source: https://github.com/pubky/http-relay/blob/main/README.md

Include http-relay as a dependency in your Rust project's Cargo.toml file. Specify the desired version.

```toml
[dependencies]
http-relay = "0.6"
```

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

### Retrieve Message with cURL (Long-Poll)

Source: https://github.com/pubky/http-relay/blob/main/README.md

Consumer retrieves a message from the inbox. This command will wait up to 25 seconds for a message if none is immediately available.

```bash
curl http://localhost:8080/inbox/my-channel
```

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

### POST /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/README.md

Producer stores a message in the specified inbox. The request returns immediately after the message is stored. If a message already exists for the given ID, it will be overwritten.

```APIDOC
## POST /inbox/{id}

### Description
Producer stores a message. Returns immediately without waiting for a consumer. New value overrides the old value if it already exists.

### Method
POST

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the inbox.

#### Request Body
- **(object)** - Required - The message payload to store.

### Request Example
```bash
curl -X POST http://localhost:8080/inbox/my-channel \
  -H "Content-Type: application/json" \
  -d '{"hello": "world"}'
```

### Response
#### Success Response (200 OK)
- Message stored successfully

#### Error Response (503 Service Unavailable)
- Server at capacity
```

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

### Wait for Message ACK with cURL

Source: https://github.com/pubky/http-relay/blob/main/README.md

Producer blocks execution until the consumer acknowledges the message. The default timeout is 25 seconds.

```bash
curl http://localhost:8080/inbox/my-channel/await
```

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

### Update Version in Cargo.toml

Source: https://github.com/pubky/http-relay/blob/main/RELEASING.md

Modify the version field in Cargo.toml to reflect the new release version. Ensure this is done on the most recent main branch.

```toml
[package]
version = "0.7.0"  # bump appropriately
```

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

### Check Message ACK Status with cURL

Source: https://github.com/pubky/http-relay/blob/main/README.md

Producer checks if a message has been acknowledged by the consumer. The response body will be 'true' if acknowledged, or 'false' if pending.

```bash
curl http://localhost:8080/inbox/my-channel/ack
```

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

### POST /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Stores a message in the inbox for a specific channel ID. This endpoint is intended for use by a message producer.

```APIDOC
## POST /inbox/{id}

### Description
Stores a message in the inbox for a specific channel ID. This endpoint is intended for use by a message producer.

### Method
POST

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the channel.

### Request Body
(The request body format is not specified in the source text.)

### Response
(Success and error response details are not specified in the source text.)
```

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

### DELETE /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/README.md

Consumer acknowledges successful receipt of a message from the specified inbox. This action clears the message from storage.

```APIDOC
## DELETE /inbox/{id}

### Description
Consumer acknowledges successful receipt. Clears the message from storage.

### Method
DELETE

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the inbox.

### Request Example
```bash
curl -X DELETE http://localhost:8080/inbox/my-channel
```

### Response
#### Success Response (200 OK)
- Message acknowledged and cleared
```

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

### Acknowledge Message Delivery with cURL

Source: https://github.com/pubky/http-relay/blob/main/README.md

Consumer acknowledges successful receipt of a message by deleting it from the inbox. This action clears the message from storage.

```bash
curl -X DELETE http://localhost:8080/inbox/my-channel
```

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

### DELETE /inbox/{id}

Source: https://github.com/pubky/http-relay/blob/main/demo/README.md

Acknowledges the receipt of a message on a specific channel. This endpoint is intended for use by a message consumer after receiving a message.

```APIDOC
## DELETE /inbox/{id}

### Description
Acknowledges the receipt of a message on a specific channel. This endpoint is intended for use by a message consumer after receiving a message.

### Method
DELETE

### Endpoint
/inbox/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the channel.

### Response
(Success and error response details are not specified in the source text.)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.