### Dumbpipe Listen Command Sequence Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

Illustrates the user interaction and output for the 'dumbpipe listen' command, showing the initial setup and connection acceptance.

```bash
User:
$ dumbpipe listen

Output:
Listening. To connect, use:
dumbpipe connect endpoint_<full_id>

[Waiting for incoming connection...]

Remote User:
$ dumbpipe connect endpoint_<full_id>

Local:
[Connection accepted]
[forwarding stdin/stdout]
```

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

### Connect TCP Command Examples

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Examples demonstrating how to use the `connect-tcp` command to forward local TCP ports to remote endpoints. These examples cover listening on specific interfaces, all interfaces, and using custom ALPN or IP addresses.

```bash
dumbpipe connect-tcp --addr 127.0.0.1:3001 <ticket>
```

```bash
dumbpipe connect-tcp --addr 0.0.0.0:8080 <ticket>
```

```bash
dumbpipe connect-tcp --addr 127.0.0.1:5432 <ticket> --custom-alpn custom_protocol
```

```bash
dumbpipe connect-tcp --addr 0.0.0.0:9000 <ticket> --ipv4-addr 127.0.0.1:0
```

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

### Example: Forward to Docker daemon socket

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

This example demonstrates forwarding connections to the Docker daemon's Unix socket, typically located at /var/run/docker.sock.

```bash
# Forward to Docker daemon
dumbpipe listen-unix --socket-path /var/run/docker.sock
```

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

### Example: Web Server Not Listening on TCP Port

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Demonstrates a common scenario where a web server is not running on the expected TCP port, leading to a connection refused error. Ensure the server is started before attempting to connect.

```bash
# Web server not running on port 3000
dumbpipe listen-tcp --host localhost:3000
# error: connection refused

# Solution: Start the server first
npm run dev  # Assuming it starts on port 3000
# Then run dumbpipe again
```

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

### Development Setup (Maximum Debugging)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Use this setup for maximum debugging output during development. It sets a development secret key and enables trace-level logging.

```bash
export IROH_SECRET="dev_key_here"
export RUST_LOG=trace
dumbpipe listen-tcp --host localhost:3000 -vvv
```

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

### Rust forward_bidi Usage Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/internal_functions.md

Demonstrates how to use the forward_bidi function with standard input/output and noq streams.

```rust
use tokio::io::{stdin, stdout};
use noq::{RecvStream, SendStream};

async fn example(recv: RecvStream, send: SendStream) -> Result<()> {
    forward_bidi(stdin(), stdout(), recv, send).await
}
```

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

### Simple Pipe Data Flow Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/README.md

Illustrates a basic file transfer using `dumbpipe listen` and `dumbpipe connect`.

```text
User A:
$ cat file.bin | dumbpipe listen
# Prints: dumbpipe connect endpoint_...

User B:
$ dumbpipe connect endpoint_... > received.bin

Flow:
file.bin → stdin → [listen] → Endpoint → [Network] → Endpoint → [connect] → stdout → received.bin
```

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

### Dumbpipe Successful Connection Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Illustrates a successful Dumbpipe connection sequence, starting with listening and then connecting with a valid ticket. The command exits with code 0, indicating success.

```bash
$ dumbpipe listen &
$ dumbpipe connect <ticket>
# ... data flows ...
$ echo $?
```

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

### Dumbpipe Default Behavior Commands

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/README.md

Examples of default commands for listening and connecting, and for TCP port forwarding.

```bash
dumbpipe listen           # Listen with random port, random secret key
dumbpipe connect <ticket> # Connect with random secret key
dumbpipe listen-tcp --host localhost:3000  # Forward endpoint connections to port 3000
```

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

### TCP Port Forwarding Data Flow Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/README.md

Demonstrates forwarding a local TCP service using `dumbpipe listen-tcp` and `dumbpipe connect-tcp`.

```text
User A (has service on localhost:3000):
$ dumbpipe listen-tcp --host localhost:3000
# Prints: dumbpipe connect-tcp endpoint_...

User B (wants to access from localhost:3001):
$ dumbpipe connect-tcp --addr localhost:3001 endpoint_...

Flow:
TCP:3001 ← [connect-tcp] ← Endpoint ← [Network] ← Endpoint → [listen-tcp] → TCP:3000 (local service)
```

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

### Install Dumbpipe with Cargo

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Install the dumbpipe command-line tool using Cargo, Rust's package manager.

```bash
cargo install dumbpipe
```

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

### Share Shell: Client Side

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Connect to the dumbpipe listener and start tty-share, forwarding to the specified address.

```bash
dumbpipe connect-tcp --addr localhost:8000 <ticket> & 
tty-share http://localhost:8000/s/local/
```

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

### Install Dumbpipe with Homebrew

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Install the dumbpipe command-line tool using Homebrew package manager on macOS.

```bash
brew install dumbpipe
```

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

### Dumbpipe Connect Command Timing Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

Shows the user input and timing expectations for the 'dumbpipe connect' command, including connection latency and data forwarding.

```bash
User:
$ dumbpipe connect endpoint_<full_id>

Timing:
[Connecting...] (takes 0.1s - 2s depending on NAT)
[Waiting for stdin...]

Local stdin: echo hello | dumbpipe connect ...
Remote stdout receives: hello
```

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

### Production Setup (Minimal Output)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Configure Dumbpipe for production with minimal output, showing only errors and critical messages. It loads the secret key from a file.

```bash
IROH_SECRET=$(cat /secure/path/iroh.key) \
  dumbpipe listen-tcp --host localhost:3000
```

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

### Dumbpipe Verbose Log Output Examples

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Provides examples of log output when verbose logging is enabled in Dumbpipe. These logs show trace, debug, and info level messages during operation.

```text
2024-01-15 10:32:45.123 TRACE dumbpipe: copying to noq
2024-01-15 10:32:45.124 DEBUG dumbpipe: endpoint id is abc123def456...
2024-01-15 10:32:45.125 INFO  dumbpipe: got connection from xyz789...
2024-01-15 10:32:45.126 TRACE dumbpipe: reading handshake
```

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

### Share Shell: Server Side

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Run dumbpipe to listen for TCP connections and start tty-share on localhost.

```bash
dumbpipe listen-tcp --host localhost:8000 & 
tty-share
```

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

### Basic Dumbpipe Connection Pattern

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/README.md

Demonstrates the fundamental two-machine setup for Dumbpipe. Machine A listens and generates a ticket, which Machine B then uses to connect.

```bash
# Machine A: Listen and print ticket
dumbpipe listen
# Output: dumbpipe connect endpoint_abc123...

# Machine B: Connect using ticket
dumbpipe connect endpoint_abc123...
```

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

### Forward to a Zellij session

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Example of using `connect-unix` to forward traffic to a Zellij session. Ensure the directory for the socket exists before running.

```bash
# Forward to a Zellij session
mkdir -p /tmp/zj-remote/0.42.1
dumbpipe connect-unix --socket-path /tmp/zj-remote/0.42.1/remote-task-1234 <ticket>
```

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

### Listen with custom ALPN

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Start a listener with a custom Application-Layer Protocol Negotiation (ALPN) value, allowing for specific protocol identification.

```bash
dumbpipe listen --custom-alpn /iroh-bytes/2
```

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

### Usage Example for CommonArgs

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Demonstrates how to instantiate and use the CommonArgs struct, including setting network addresses and custom ALPN, and calling its helper methods.

```rust
let args = CommonArgs {
    ipv4_addr: Some("127.0.0.1:0".parse().unwrap()),
    ipv6_addr: None,
    custom_alpn: Some("utf8:/iroh-bytes/2".to_string()),
    verbose: 2,
};

let alpn = args.alpn()?;  // Returns /iroh-bytes/2 in bytes
assert!(args.is_custom_alpn());
```

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

### Example of Invalid Handshake and Solution

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Demonstrates an invalid handshake scenario due to mismatched ALPN settings and provides the correct configuration for both sides to match.

```bash
# Mismatch: listen with default ALPN, connect with custom ALPN
dumbpipe listen
dumbpipe connect <ticket> --custom-alpn utf8:/custom

# error: invalid handshake

# Solution: Both sides must match
dumbpipe listen --custom-alpn utf8:/custom
dumbpipe connect <ticket> --custom-alpn utf8:/custom
```

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

### Example: Forward to Zellij session socket

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Use this command to forward incoming connections to a Unix domain socket associated with a Zellij terminal session.

```bash
# Forward to a Zellij session socket
dumbpipe listen-unix --socket-path /tmp/zellij-0/0.42.2/remote-task-1234
```

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

### High-Throughput Data Transfer Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Demonstrates setting up a high-throughput data transfer. The sending side listens for data, and the receiving side connects and pipes the data through pv to measure throughput. Throughput is limited by network bandwidth.

```bash
# Sending side (minimize overhead)
$ dumbpipe listen < /dev/zero

# Receiving side (measure throughput)
$ dumbpipe connect endpoint_<ticket> | pv > /dev/null

# Example output:
# 123MB 0:00:05 [24.6MB/s]
```

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

### Forward Docker daemon

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Example of using `connect-unix` to forward traffic to a Docker daemon via a Unix socket.

```bash
# Forward Docker daemon
dumbpipe connect-unix --socket-path /tmp/docker.sock <ticket>
```

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

### Systemd Service Management Commands

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Commands to enable, start, and check the status of the dumbpipe systemd service.

```bash
$ sudo systemctl enable dumbpipe
$ sudo systemctl start dumbpipe
$ sudo systemctl status dumbpipe
```

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

### Example: Forward with custom endpoint port

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Configure the 'listen-unix' command to use a custom IP address and port for its listening endpoint, while still forwarding to a specified Unix socket.

```bash
# Custom endpoint port
dumbpipe listen-unix --socket-path /tmp/my.sock --ipv4-addr 127.0.0.1:9000
```

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

### Low-Latency Keepalive Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Illustrates how to establish low-latency connections for keepalive signals. The listening side runs in a loop, and the connecting side sends a 'ping' or connects with an empty input to measure round-trip time.

```bash
# Listening side
$ while true; do dumbpipe listen; done

# Connecting side
$ echo "ping" | dumbpipe connect endpoint_<ticket>
$ dumbpipe connect endpoint_<ticket> < /dev/null  # Measure round-trip time
```

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

### Firewall-Friendly Setup (Custom Ports)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Bind Dumbpipe to specific IPv4 and IPv6 ports for easier firewall configuration and port forwarding. This is useful for automated deployments.

```bash
dumbpipe listen \
  --ipv4-addr 203.0.113.45:9000 \
  --ipv6-addr [2001:db8::1]:9000
```

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

### Start Dumbpipe Listener (Ephemeral Secret)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Starts the dumbpipe listener using an ephemeral secret that is not saved.

```bash
dumbpipe listen
```

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

### TCP Listen Address Configuration

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Examples of configuring the network address for TCP listening commands. Supports specific IPv4, all interfaces, and hostnames.

```bash
# Specific IPv4
--addr 127.0.0.1:8080
```

```bash
# All interfaces
--addr 0.0.0.0:8080
```

```bash
# With hostname
--host localhost:3000
```

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

### Expose Local Dev Server to Remote Colleague

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

On the local machine, start a Dumbpipe listener for a local development server. On the remote machine, connect to the forwarded endpoint to access the local server.

```bash
$ npm run dev &
# Server running on http://localhost:3000

$ dumbpipe listen-tcp --host localhost:3000
Forwarding incoming requests to 'localhost:3000'.
To connect, use e.g.:
dumbpipe connect-tcp endpoint_<ticket>
```

```bash
$ dumbpipe connect-tcp --addr 127.0.0.1:3001 endpoint_<ticket>
# Listening on localhost:3001

# In browser:
# http://localhost:3001
```

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

### Socket Address Parsing Examples

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Demonstrates flexible input formats for socket addresses, including IPv4, IPv6, and hostnames. These are parsed using `std::net::ToSocketAddrs`.

```rust
127.0.0.1:8080
```

```rust
[::1]:8080
```

```rust
localhost:8080
```

```rust
example.com:443
```

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

### Attach Zellij to local socket

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Example of attaching Zellij to the local socket created by `dumbpipe connect-unix`. This command is run after the `connect-unix` command.

```bash
# Then attach Zellij to the local socket
ZELLIJ_SOCKET_DIR=/tmp/zj-remote zellij attach remote-task-1234
```

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

### Combine Listeners: Unix to TCP

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Example of forwarding a Unix socket connection from Machine A to a TCP port on Machine B using dumbpipe.

```bash
# Machine A: Listen on a Unix socket
dumbpipe listen-unix --socket-path /var/run/my-app.sock

# Machine B: Connect to it via a local TCP port
dumbpipe connect-tcp --addr 127.0.0.1:8080 <ticket>
```

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

### Kubernetes Pod Communication Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Enable communication between Kubernetes pods without using an ingress controller. One pod listens on TCP, and another connects to access the service.

```bash
# Pod A:
$ dumbpipe listen-tcp --host localhost:8080
```

```bash
# Pod B:
$ dumbpipe connect-tcp --addr 0.0.0.0:8080 endpoint_<ticket>
# Can now access pod-a service on localhost:8080
```

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

### Expose Remote Database to Local Tools

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

On the remote machine, start a Dumbpipe listener for the database port. On the local machine, connect to the forwarded endpoint and then use local tools to access the database.

```bash
$ dumbpipe listen-tcp --host localhost:5432
```

```bash
$ dumbpipe connect-tcp --addr 127.0.0.1:5432 endpoint_<ticket>

# In another terminal, connect to the forwarded database:
$ psql -h 127.0.0.1 -p 5432 -U postgres
```

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

### Example: Zellij Unix Socket Not Found

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Illustrates an error where a Zellij Unix socket is not found, typically because the Zellij session is not running or the path is incorrect. Ensure the Zellij session is active and use the correct socket path.

```bash
# Zellij socket doesn't exist
dumbpipe listen-unix --socket-path /tmp/zellij-0/0.42.2/remote-task-1234
# error: No such file or directory

# Solution: Ensure Zellij is running with that session name
zellij list-sessions
# Then use the correct path
```

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

### Listen on All Interfaces

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Configure Dumbpipe to listen on all available network interfaces for a high-availability setup, accepting connections from any source.

```bash
$ dumbpipe listen --ipv4-addr 0.0.0.0:0 --ipv6-addr [::]:0
```

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

### Listen in receive-only mode

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

This command starts a listener that only sends data and does not receive, useful for scenarios where you only need to transmit information.

```bash
dumbpipe listen --recv-only
```

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

### Piping Media Data

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Shows an example of piping media data from ffmpeg to a remote ffplay instance using dumbpipe. This illustrates a practical use case for bidirectional data streaming.

```bash
ffmpeg -f ... | dumbpipe connect "endpoint_......" | ffplay
```

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

### Rust Integration Tests

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

Example integration tests for the Dumbpipe CLI. These tests verify basic connection and listening functionalities, including custom ALPN scenarios.

```rust
#[test]
fn connect_listen_happy() { ... }
```

```rust
#[test]
fn connect_listen_custom_alpn_happy() { ... }
```

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

### Common Dumbpipe Debugging Output Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

This snippet shows typical log messages from a verbose Dumbpipe listener, including endpoint ID, connection details, and data forwarding status.

```text
2024-01-15 10:32:45.123 INFO dumbpipe: endpoint id is abc123def456xyz
2024-01-15 10:32:45.124 INFO dumbpipe: got connection from xyz789abc123
2024-01-15 10:32:45.125 TRACE dumbpipe: reading handshake
2024-01-15 10:32:45.126 TRACE dumbpipe: forwarding stdin/stdout

```

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

### Docker Container Streaming Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Stream data between Docker containers using Dumbpipe. One container acts as a producer listening to a file, and another connects to consume the stream.

```bash
# Container A (producer):
$ docker run -it producer-image bash
# Inside container:
$ dumbpipe listen < /data/stream.bin
```

```bash
# Container B (consumer):
$ docker run -it consumer-image bash
# Inside container:
$ dumbpipe connect endpoint_<ticket> | process-data
```

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

### Bind to a specific IPv4 port

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Use the --ipv4-addr flag to specify the IPv4 address and port for the endpoint to bind to. This example binds to a specific port on localhost.

```bash
dumbpipe listen --ipv4-addr 127.0.0.1:9000
```

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

### Handle Multiple Concurrent TCP Clients

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Start a Dumbpipe listener on the remote service. On the local machine, connect to the remote service, allowing multiple clients to connect to the local address and have their requests forwarded.

```bash
$ dumbpipe listen-tcp --host localhost:8080
```

```bash
$ dumbpipe connect-tcp --addr 0.0.0.0:8080 endpoint_<ticket> &

# Now multiple clients can connect to localhost:8080
curl http://localhost:8080/api/users   # Client 1
curl http://localhost:8080/api/posts   # Client 2
# Both requests are forwarded independently to the remote service
```

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

### Dumbpipe Command Failure Example

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Demonstrates a complete command failure sequence for Dumbpipe when an invalid endpoint ticket format is provided. The command exits with code 1, indicating failure.

```bash
$ dumbpipe connect "invalid_ticket_format"
error: invalid endpoint ticket format
$ echo $?
1
```

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

### Enable Maximum Verbosity for Dumbpipe Listen

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Run the Dumbpipe listener with `RUST_LOG=trace` and `-vvv` flags to get maximum logging detail for diagnosing connection issues. Output is redirected to both the console and a file for analysis.

```bash
$ RUST_LOG=trace dumbpipe listen -vvv 2>&1 | tee listen.log
```

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

### Configure Endpoint with N0 Preset

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

This snippet shows how to initialize an iroh endpoint using the N0 preset, which includes default relay servers, TLS, QUIC, and hole punching configurations. It requires a secret key and ALPNs.

```rust
let endpoint = Endpoint::builder(presets::N0)
    .secret_key(secret_key)
    .alpns(alpns)
    .bind()
    .await?
```

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

### Connect to an Endpoint

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Initiates a connection to a specified endpoint using its ticket. This is the basic usage for establishing a connection.

```bash
dumbpipe connect "endpoint_......"
```

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

### Connect with Custom ALPN

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Connects to an endpoint using a custom Application-Layer Protocol Negotiation (ALPN) string. This allows for specific protocol handling during connection setup.

```bash
dumbpipe connect "endpoint_......" --custom-alpn /iroh-bytes/2
```

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

### Stream Accept Error

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Indicates an error while accepting a bidirectional stream. This can be due to the remote side closing the connection unexpectedly or network issues during stream setup.

```text
error: error accepting stream
```

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

### ListenUnixArgs Structure (Unix Only)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Defines arguments for the `listen-unix` command on Unix-like systems. Requires a socket path and common arguments.

```rust
#[cfg(unix)]
#[derive(Parser, Debug)]
pub struct ListenUnixArgs {
    pub socket_path: PathBuf,
    #[clap(flatten)]
    pub common: CommonArgs,
}
```

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

### Handle Concurrent Connections with Timeout

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

This script starts a Dumbpipe listener in the background and automatically terminates it after a specified timeout to manage concurrent connections and prevent indefinite running.

```bash
#!/bin/bash
# listener_with_timeout.sh

TIMEOUT=300  # 5 minutes

# Run listen in background, kill after timeout
dumbpipe listen &
LISTEN_PID=$!

sleep $TIMEOUT
kill $LISTEN_PID 2>/dev/null

```

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

### Basic TCP Forwarding

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Use this command to forward incoming connections to a local development server.

```bash
dumbpipe listen-tcp --host localhost:3000
```

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

### ConnectUnixArgs Structure (Unix Only)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Defines arguments for the `connect-unix` command on Unix-like systems. Includes socket path, ticket, and common arguments.

```rust
#[cfg(unix)]
#[derive(Parser, Debug)]
pub struct ConnectUnixArgs {
    pub socket_path: PathBuf,
    pub ticket: EndpointTicket,
    #[clap(flatten)]
    pub common: CommonArgs,
}
```

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

### Forward Web Server: Listener

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Listen on a TCP port with dumbpipe and forward incoming requests to a local development web server.

```bash
dumbpipe listen-tcp --host localhost:3000
```

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

### Automated Network Backup with Dumbpipe (Receiver)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Set up a backup receiver script that listens for incoming data and saves it to a specified directory. This script is intended to run in the background, possibly via cron.

```bash
#!/bin/bash
# backup_receiver.sh

IROH_SECRET="saved_key_here"
OUTPUT_DIR="/backups"

export IROH_SECRET

dumbpipe listen --recv-only \
  | tar -xzf - -C "$OUTPUT_DIR"
  
# The script exits when the backup finishes
```

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

### Get or Create Secret Key

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/internal_functions.md

Retrieves a secret key from the IROH_SECRET environment variable or generates a new one. Use when an endpoint needs a persistent or newly generated secret key.

```rust
fn get_or_create_secret() -> Result<SecretKey>
```

```rust
let secret = get_or_create_secret()?;
println!("Endpoint ID: {}", secret.public());
```

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

### Accept Multiple TCP Connections Sequentially

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Use `listen-tcp` to allow a Dumbpipe server to accept multiple incoming TCP connections one after another. Each connection is handled independently.

```bash
$ dumbpipe listen-tcp --host localhost:9999
# Each incoming connection opens a new TCP connection to localhost:9999
```

```bash
$ nc localhost:9999 < file1.txt
```

```bash
$ nc localhost:9999 < file2.txt
```

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

### Enable both IPv4 and IPv6 listening

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Combine --ipv4-addr and --ipv6-addr flags to enable the endpoint to listen on both IPv4 and IPv6 interfaces simultaneously.

```bash
dumbpipe listen --ipv4-addr 127.0.0.1:9000 --ipv6-addr [::1]:9000
```

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

### Listen on specific IPv4/IPv6 addresses

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Configure the listener to bind to specific IPv4 and IPv6 addresses, enabling control over network interface usage.

```bash
dumbpipe listen --ipv4-addr 127.0.0.1:0 --ipv6-addr [::1]:0
```

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

### Automated Network Backup with Dumbpipe (Sender)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Create a backup sender script that archives specified data and streams it to a Dumbpipe endpoint using a provided ticket.

```bash
#!/bin/bash
# backup_sender.sh

TICKET="endpoint_from_receiver"

# Create and stream backup
tar -czf - /important/data | dumbpipe connect "$TICKET"
```

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

### Parse Socket Address with Error Context

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Example of parsing a string into a SocketAddr using Dumbpipe's Result type. It demonstrates adding context to potential parsing errors using the std_context method.

```rust
use n0_error::Result;

fn parse_addr(s: &str) -> Result<SocketAddr> {
    s.parse()
        .std_context("invalid socket address")
}
```

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

### Connect with Custom ALPN (UTF-8)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Connects using a ticket and specifies a custom ALPN as a UTF-8 string. The handshake is skipped entirely when a custom ALPN is provided.

```bash
dumbpipe connect <ticket> --custom-alpn utf8:/iroh-bytes/2
```

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

### Listen on all IPv6 interfaces with a dynamic port

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Configure the endpoint to listen on all available IPv6 network interfaces, allowing the OS to assign a random port by setting the port to 0.

```bash
dumbpipe listen --ipv6-addr [::]:0
```

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

### Define CLI Commands

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Enumerates all possible commands for the CLI, including variants for generating tickets, listening, and connecting over different protocols. Some commands are conditional on the operating system (Unix).

```rust
#[derive(Subcommand, Debug)]
pub enum Commands {
    GenerateTicket,
    Listen(ListenArgs),
    ListenTcp(ListenTcpArgs),
    Connect(ConnectArgs),
    ConnectTcp(ConnectTcpArgs),
    #[cfg(unix)]
    ListenUnix(ListenUnixArgs),
    #[cfg(unix)]
    ConnectUnix(ConnectUnixArgs),
}
```

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

### Task Spawning for Connections

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

Shows how Dumbpipe uses tokio tasks for handling multiple concurrent connections. Each connection is managed by a separate forward_bidi task.

```text
Main Task (accepts connections)
    ├─→ Task 1: forward_bidi (connection 1)
    │   ├─→ copy_to_noq
    │   ├─→ copy_from_noq
    │   └─→ ctrl_c handler
    ├─→ Task 2: forward_bidi (connection 2)
    │   └─ ...
    └─→ Task N: forward_bidi (connection N)
```

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

### Listen with IPv4 and IPv6

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Listens on both IPv4 and IPv6 interfaces with specified host and ports. Uses random free ports for IPv4.

```bash
dumbpipe listen-tcp --host localhost:3000 --ipv4-addr 127.0.0.1:0 --ipv6-addr [::1]:0
```

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

### Stream Video: Sender (Linux)

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Use ffmpeg to capture video from a Linux device and pipe it to dumbpipe for streaming.

```bash
ffmpeg -f v4l2 -i /dev/video0 -r 30 -preset ultrafast -vcodec libx264 -tune zerolatency -f mpegts - | dumbpipe listen
```

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

### Attach Local Zellij Client

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Attach a local Zellij client to a forwarded Unix socket session by setting the ZELLIJ_SOCKET_DIR environment variable.

```bash
# In a new terminal window/tab, set the socket directory and attach
ZELLIJ_SOCKET_DIR=/tmp/zj-remote zellij attach remote-task-1234
```

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

### Bidirectional Forwarding Pseudo-code

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

This pseudo-code demonstrates the core `forward_bidi` function, which sets up two concurrent data copy tasks and a control-c handler for graceful shutdown. It utilizes a shared `CancellationToken` to manage the lifecycle of both forwarding directions.

```rust
async fn forward_bidi(from1, to1, from2, to2) {
    let token = CancellationToken::new();
    let token2 = token.clone();
    let token3 = token.clone();
    
    let copy_in = spawn(copy_to_noq(from1, to2, token));
    let copy_out = spawn(copy_from_noq(from2, to1, token2));
    let ctrl_c = spawn(ctrl_c().then(|| token3.cancel()));
    
    // Wait for either direction to complete
    copy_out.await.anyerr()??.anyerr()?;
    copy_in.await.anyerr()??.anyerr()?;
}
```

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

### Quick Copy Between Machines

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Use this configuration to quickly copy files between two machines using Dumbpipe. Machine A listens and receives the file, while Machine B connects and sends the file.

```bash
# Machine A (server):
dumbpipe listen < file.bin

# Machine B (client):
dumbpipe connect <ticket> > file.bin
```

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

### Forward Web Server: Connector

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Connect to a dumbpipe ticket and listen on a local TCP port, forwarding connections to the remote endpoint.

```bash
dumbpipe connect-tcp --addr 0.0.0.0:3001 <ticket>
```

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

### Centralized Log Streaming with Dumbpipe (Server)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Configure a central logging server to listen for TCP connections on a specific host and port, redirecting incoming logs to a file.

```bash
$ dumbpipe listen-tcp --host localhost:5140 > centralized-logs.txt
```

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

### Connect with Custom ALPN (Hex)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Connects using a ticket and specifies a custom ALPN as a hex string. The handshake is skipped entirely when a custom ALPN is provided.

```bash
dumbpipe connect <ticket> --custom-alpn "5468654f4348"
```

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

### Dumbpipe Listen-TCP Connection Model

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/architecture.md

Visualizes how multiple remote user TCP connections are handled by 'dumbpipe listen-tcp' and forwarded to a local TCP server.

```text
Remote User TCP Connection 1 ─┐
Remote User TCP Connection 2 ─┼─→ Dumbpipe listen-tcp ─→ TCP localhost:3000
Remote User TCP Connection 3 ─┘    (one forwarding task per TCP client)
```

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

### Stream Video: Sender (macOS)

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Use ffmpeg to capture video from a macOS device and pipe it to dumbpipe for streaming.

```bash
ffmpeg -f avfoundation -r 30 -i "0" -pix_fmt yuv420p -f mpegts - | dumbpipe listen
```

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

### ListenTcpArgs Structure

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Defines arguments for the `listen-tcp` command. Specifies the host and common arguments.

```rust
#[derive(Parser, Debug)]
pub struct ListenTcpArgs {
    #[clap(long)]
    pub host: String,
    #[clap(flatten)]
    pub common: CommonArgs,
}
```

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

### ConnectArgs Structure

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Defines arguments for the `connect` command. Includes ticket, receive-only flag, and common arguments.

```rust
#[derive(Parser, Debug)]
pub struct ConnectArgs {
    pub ticket: EndpointTicket,
    pub recv_only: bool,
    #[clap(flatten)]
    pub common: CommonArgs,
}
```

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

### Stream Video: Sender Side (Linux)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Stream video from a Linux device using ffmpeg to dumbpipe. Requires ffmpeg and a video device.

```bash
$ ffmpeg -f v4l2 -i /dev/video0 -r 30 -preset ultrafast \
  -vcodec libx264 -tune zerolatency -f mpegts - | dumbpipe listen
Listening. To connect, use:
dumbpipe connect endpoint_<ticket>
```

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

### Video Streaming

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Set up Dumbpipe for video streaming between two machines. The source machine pipes its video output to Dumbpipe's listen command, and the receiver machine connects and pipes the received data to a player.

```bash
# Source machine:
ffmpeg -f ... | dumbpipe listen

# Receiver machine:
dumbpipe connect <ticket> | ffplay
```

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

### Accept Connection Error Logging

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

This warning is logged when an error occurs in the accept loop on the listening side. The listener continues to accept connections despite this warning.

```text
warning: error accepting connection: ...
```

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

### Listen with Provided Secret Key

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Listens using a specific secret key provided via the IROH_SECRET environment variable. If not set, a random key is generated.

```bash
IROH_SECRET="your_32_byte_hex_key_here" dumbpipe listen
```

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

### Listen on Localhost Only

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Set up Dumbpipe to accept connections only from the local machine. This is ideal for testing purposes before exposing the service to the network.

```bash
$ dumbpipe listen --ipv4-addr 127.0.0.1:0 --ipv6-addr [::1]:0
```

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

### Custom ALPN with TCP listening

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Configure a TCP listener to use a custom ALPN string, allowing for specific protocol negotiation over TCP connections.

```bash
dumbpipe listen-tcp --host localhost:3000 --custom-alpn utf8:my-protocol
```

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

### Using EndpointTicket for Connections

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/crate_exports.md

Demonstrates how to parse an EndpointTicket from a string and retrieve its underlying endpoint address. This ticket encapsulates connection metadata for establishing dumbpipe connections.

```rust
use std::str::FromStr;
use dumbpipe::EndpointTicket;

// Parse a ticket from a string
let ticket_str = "endpoint_id_string_here";
let ticket = EndpointTicket::from_str(ticket_str).unwrap();

// Get the underlying endpoint address
let addr = ticket.endpoint_addr();

```

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

### Test Dumbpipe Relay Fallback with Verbose Logging

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Use `dumbpipe listen -vv` to observe warnings about failing to connect to the home relay. This indicates a potential issue with relay connectivity, though the tool will continue to operate.

```bash
$ dumbpipe listen -vv 2>&1
```

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

### Common Debugging Commands for Network Services

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/errors.md

Lists common system commands used for debugging network-related issues, such as checking port usage, socket existence, TCP connectivity, and testing listening services.

```bash
# Check if a port is in use
netstat -tuln | grep :8080
ss -tuln | grep :8080  # newer systems

# Check if a Unix socket exists
ls -la /tmp/my.sock

# Test TCP connectivity
nc -zv localhost 3000

# Test listening
dumbpipe listen --ipv4-addr 127.0.0.1:9000 -vvv
```

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

### listen-tcp Command

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/api-reference/cli_commands.md

Listens on an endpoint and forwards incoming connections to a specified TCP socket. This command is useful for exposing local services to the network.

```APIDOC
## Command: listen-tcp

Listens on an endpoint and forwards incoming connections to a TCP socket.

### Arguments

#### Path Parameters

- **--host** (string) - Required - TCP address to forward incoming connections to. Format: `host:port` (e.g., `localhost:3000`, `127.0.0.1:8080`). Must be parseable as a socket address.

#### Common Arguments

- **(common args)** - See CommonArgs below

### Behavior

1. Parses the host string into socket addresses.
2. Generates or loads a secret key.
3. Creates an iroh endpoint.
4. Prints a ticket to stderr.
5. Waits for incoming endpoint connections.
6. For each incoming stream:
   - Reads and validates the handshake (unless custom ALPN).
   - Opens a new TCP connection to the specified host.
   - Forwards data bidirectionally.
   - Cleans up when the connection closes.

### Output to stderr

```
Forwarding incoming requests to '<host>'.
To connect, use e.g.:
dumbpipe connect-tcp <ticket>
```

### Exit Codes

- 0: Normal shutdown (Ctrl+C or endpoint closed)
- 1: Error (details printed to stderr)

### Error Handling

- If the initial TCP address parsing fails, prints error and exits immediately.
- If binding the endpoint fails, prints error and exits.
- If an individual connection fails (TCP connect, stream accept, etc.), logs warning but continues accepting.

### Usage Examples

```bash
# Forward to a local development server
dumbpipe listen-tcp --host localhost:3000

# Forward to a remote service
dumbpipe listen-tcp --host example.com:8080

# Forward to localhost on a different port
dumbpipe listen-tcp --host 127.0.0.1:5432

# With specific endpoint port
dumbpipe listen-tcp --host localhost:3000 --ipv4-addr 0.0.0.0:9000

# Enable verbose logging
dumbpipe listen-tcp --host localhost:3000 -vv
```
```

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

### Forwarding a Web Server

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/configuration.md

Configure Dumbpipe to forward a web server running on one machine to another. Machine A listens on a specific host and port, and Machine B connects to a local port that is then forwarded.

```bash
# Machine A (has the web server on port 3000):
dumbpipe listen-tcp --host localhost:3000

# Machine B (forward local port 3001 to remote server):
dumbpipe connect-tcp --addr 127.0.0.1:3001 <ticket>
# Browser: http://localhost:3001
```

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

### Run Automated Backup Scripts

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Execute the receiver script in the background and then run the sender script to perform the backup. A short delay is included to ensure the receiver is ready.

```bash
$ ./backup_receiver.sh &
$ sleep 2
$ ./backup_sender.sh
```

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

### Continuous Log Streaming with Dumbpipe (Client)

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/usage_examples.md

Configure remote servers to stream their application logs to a central logging server using Dumbpipe. Logs are appended to the central server's file.

```bash
# Append logs to central server via dumbpipe
$ tail -f /var/log/application.log | \
  dumbpipe connect endpoint_<ticket> &
```

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

### ConnectTcpArgs Structure

Source: https://github.com/n0-computer/dumbpipe/blob/main/_autodocs/types.md

Defines arguments for the `connect-tcp` command. Specifies the local address, ticket, and common arguments.

```rust
#[derive(Parser, Debug)]
pub struct ConnectTcpArgs {
    pub addr: String,
    pub ticket: EndpointTicket,
    #[clap(flatten)]
    pub common: CommonArgs,
}
```

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

### Connect to iroh-blobs using a custom ALPN

Source: https://github.com/n0-computer/dumbpipe/blob/main/README.md

Use the --custom-alpn flag to specify the protocol identifier when connecting to an iroh service.

```bash
echo request1.bin | dumbpipe connect <ticket> --custom-alpn utf8:/iroh-bytes/2 > response1.bin
```