### Copy Example Configuration File

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

This command copies an example configuration file to the local config directory.

```bash
cp /usr/share/doc/pushpin/examples/pushpin.conf ./config/
```

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

### Start Pushpin Service

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/INDEX.md

Start the Pushpin service using the specified configuration file.

```bash
pushpin --config config/pushpin.conf
```

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

### Simple HTTP Client Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

This snippet shows how to create a basic asynchronous HTTP client. It connects to a server, sends a GET request, and prints the response status and body. Ensure a server is running on 127.0.0.1:8000.

```rust
use pushpin::core::net::AsyncTcpStream;
use pushpin::core::http1::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut stream = AsyncTcpStream::connect("127.0.0.1:8000").await?;
    let mut client = ClientConnection::new();
    
    let headers = vec![
        Header { name: b"Host", value: b"127.0.0.1:8000" },
    ];
    
    client.send_request(&mut stream, b"GET", b"/", &headers).await?;
    
    let mut headers_buf = [Header { name: b"", value: b"" }; 100];
    let (status, response) = client.recv_response(&mut stream, &mut headers_buf).await?;
    
    println!("Status: {} {}", response.code, String::from_utf8_lossy(response.reason));
    println!("Body: {}", String::from_utf8_lossy(response.body));
    
    Ok(())
}
```

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

### Run Pushpin Single Process

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/11-service-architecture.md

Starts all Pushpin services (connmgr, proxy, handler) in a single process. Use this for simple setups.

```bash
pushpin
```

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

### GRIP Response Headers Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Example of an HTTP response from the backend to Pushpin, using GRIP headers to control connection behavior like streaming and channel subscription.

```http
HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: updates
Grip-Keep-Alive: 30; format=chunked
Content-Type: text/plain

Initial response body
```

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

### Example Grip-Message-Prefix Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

An example of setting the message prefix to 'msg:'. Messages published will be prepended with this string.

```http
Grip-Message-Prefix: msg:
```

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

### Install Build Tools

Source: https://github.com/fastly/pushpin/blob/main/packaging/debian/README.md

Installs essential tools for Debian packaging and Rust development.

```bash
apt install dpkg dpkg-dev devscripts vim rustc cargo
cargo install --locked cargo-deb@2.12.1  # compatible with older rustc in distro
```

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

### Prepare Distribution Files

Source: https://github.com/fastly/pushpin/blob/main/packaging/debian/README.md

Builds and installs Pushpin into the ./dist directory from a specified git tag.

```bash
./packaging/debian/prepare-dist.sh v1.41.0
```

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

### Install Pushpin Dependencies

Source: https://github.com/fastly/pushpin/blob/main/packaging/debian/README.md

Installs runtime dependencies required for Pushpin.

```bash
apt install zstd git pkg-config curl make g++ libssl-dev libzmq3-dev qt6-base-dev libboost-dev
```

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

### Pushpin with Custom Configuration File

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Specifies a custom configuration file to use for starting Pushpin.

```bash
pushpin --config /etc/pushpin/custom.conf
```

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

### Pushpin Publish Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Examples of publishing messages. The first publishes a simple string to the 'updates' channel. The second publishes a JSON string to the 'chat' channel with the websocket format.

```bash
pushpin-publish updates "Hello, subscribers!"
pushpin-publish chat '{"user": "alice", "msg": "hello"}' --format websocket
```

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

### GRIP Request Headers Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Example of an HTTP request received by the backend from Pushpin, including GRIP-specific headers like Grip-Pong.

```http
POST /handler HTTP/1.1
Host: backend.example.com
Content-Type: application/json
Grip-Pong: true        # WebSocket context pong

{"body": "request data"}
```

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

### HTTP Streaming: Client Request

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of an HTTP GET request from a client to initiate an HTTP stream.

```http
GET /stream HTTP/1.1
Host: example.com
```

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

### Example Grip-Keep-Alive Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

An example of setting a 30-second keep-alive timeout with the 'chunked' format for periodic messages.

```http
Grip-Keep-Alive: 30; format=chunked
```

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

### Init.d Script for Pushpin

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

A basic init.d script to start, stop, and restart the Pushpin service. It uses pkill to manage the process.

```bash
#!/bin/bash
# Start Pushpin on system boot

case "$1" in
  start) 
    /usr/bin/pushpin --config /etc/pushpin/pushpin.conf &
    ;;
  stop)
    pkill -f "/usr/bin/pushpin"
    ;;
  restart)
    pkill -f "/usr/bin/pushpin"
    sleep 1
    /usr/bin/pushpin --config /etc/pushpin/pushpin.conf &
    ;;
esac
```

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

### ZeroMQ Publish Message Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

An example of a message structure for publishing via ZeroMQ, encoded in TNetString format.

```json
{"channel": "updates", "formats": {"http-stream": {"content": "data"}}}
```

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

### Route Priority Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Demonstrates the order of route evaluation based on specificity, from exact paths to wildcards.

```routes
/api/v1/users http://users-service:8000
/api/v1 http://api-v1:8000
/api http://api:8000
* http://default:8000
```

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

### Basic Publish Request Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/06-publish-api.md

Demonstrates the structure of a basic HTTP POST request to the /publish endpoint, including the channel and content format.

```http
POST /publish HTTP/1.1
Host: localhost:5561
Content-Type: application/json

{
  "items": [
    {
      "channel": "channel-name",
      "formats": {
        "http-stream": { "content": "data to send" }
      }
    }
  ]
}
```

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

### Pushpin Routes File Format

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Example of the routes file format. Each line defines a URL pattern and its corresponding backend specification.

```text
* backend.example.com
/api zhttpreq/tcp://api-backend:10000
/stream http://stream-backend:8000
```

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

### WebSocket: Backend Initial Request

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of the request a backend receives when a client attempts to upgrade to WebSocket.

```http
POST /ws HTTP/1.1
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: ...
Grip-Pong: true

(handshake data)
```

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

### Systemd Service Management Commands

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Commands to start and enable the Pushpin service managed by systemd.

```bash
sudo systemctl start pushpin
sudo systemctl enable pushpin
```

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

### Configure Pushpin Input Socket

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Configure the Pushpin handler to bind or connect to the input socket. This example shows the handler binding.

```ini
# Handler binds, connmgr connects
push_in_spec = tcp://0.0.0.0:5560
push_in_sub_connect = false
```

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

### Publish via ZeroMQ using Go

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Provides an example of publishing messages to Pushpin using ZeroMQ REQ socket in Go. Ensure the zmq4 library is imported.

```go
package main

import (
  "encoding/json"
  zmq "github.com/pebbe/zmq4"
)

func publish() {
  socket, _ := zmq.NewSocket(zmq.REQ)
  defer socket.Close()
  
  socket.Connect("tcp://localhost:5560")
  
  message := map[string]interface{}{
    "items": []map[string]interface{}{
      {
        "channel": "updates",
        "formats": map[string]interface{}{
          "http-stream": map[string]string{
            "content": "Hello from ZMQ",
          },
        },
      },
    },
  }
  
  data, _ := json.Marshal(message)
  socket.Send(string(data), 0)
  socket.Recv(0)
}
```

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

### Routes File Format Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

A plain text file with one route per line. Comments and blank lines are ignored.

```plaintext
# Comment line
pattern backend-spec

pattern2 backend-spec2
```

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

### WebSocket: Client Upgrade Request

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of a client's HTTP request to upgrade to a WebSocket connection.

```http
GET /ws HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...
```

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

### Run Executor

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Starts the main execution loop for the Executor.

```rust
pub fn run(&mut self) -> Result<(), Error>
```

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

### HTTP Streaming: Pushpin Transformation

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of how Pushpin transforms the backend response for HTTP streaming.

```http
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/plain

Initial data
```

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

### Simple HTTP Server Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

A basic HTTP server that listens for incoming TCP connections, accepts requests, and sends a 'Hello, World!' response. It utilizes Pushpushin's async networking and HTTP/1.1 components.

```rust
use pushpin::core::net::*;
use pushpin::core::http1::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = AsyncTcpListener::bind("127.0.0.1:8000").await?;
    
    loop {
        let (mut stream, addr) = listener.accept().await?;
        println!("Connection from {}", addr);
        
        tokio::spawn(async move {
            let mut server = ServerConnection::new();
            let mut headers_buf = [Header { name: b"", value: b"" }; 100];
            
            match server.recv_request(&mut stream, &mut headers_buf).await {
                Ok((RecvStatus::Done, request)) => {
                    let response_headers = vec![
                        Header { name: b"Content-Type", value: b"text/plain" },
                    ];
                    
                    let _ = server.send_response(
                        &mut stream,
                        200,
                        b"OK",
                        &response_headers,
                    ).await;
                    
                    let _ = server.send_body(
                        &mut stream,
                        &[b"Hello, World!"],
                        true,
                    ).await;
                }
                _ => {}
            }
        });
    }
}
```

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

### HTTP Streaming: Publish Data

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of publishing new data to an existing GRIP channel.

```http
POST /publish HTTP/1.1
Host: localhost:5561
Content-Type: application/json

{
  "items": [{
    "channel": "updates",
    "formats": {"http-stream": {"content": "new data\n"}}
  }]
}
```

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

### Get Version and Build Information

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Provides access to the project's version string and whether it's a debug build.

```rust
pub fn version() -> &'static str
pub fn is_debug_build() -> bool
```

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

### Python ZeroMQ Backend Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

A basic Python ZeroMQ backend that receives requests, prints details, and sends a response using tnetstring encoding.

```python
import zmq
import json
import tnetstring

context = zmq.Context()
socket = context.socket(zmq.REP)
socket.bind("tcp://127.0.0.1:10000")

while True:
  # Receive request
  msg = socket.recv()
  request = tnetstring.loads(msg)
  
  print(f"Method: {request['method']}")
  print(f"URI: {request['uri']}")
  print(f"Body: {request['body']}")
  
  # Send response
  response = {
    "id": request["id"],
    "code": 200,
    "reason": "OK",
    "headers": [
      ["Grip-Hold", "stream"],
      ["Grip-Channel", "updates"]
    ],
    "body": "response"
  }
  
  socket.send(tnetstring.dumps(response))
```

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

### WebSocket: Backend Acceptance

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of a backend accepting a WebSocket upgrade request.

```http
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Grip-Hold: stream
Grip-Channel: chat

(handshake response)
```

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

### GRIP Stream Mode Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Instructs Pushpin to hold the connection indefinitely for streaming data. The backend responds with Grip-Hold: stream and Grip-Channel headers. New data is injected via chunked encoding.

```http
HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: updates
Content-Type: text/plain

Initial content
```

```http
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/plain

Initial content
```

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

### Dockerfile for Pushpin

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

A Dockerfile to build a Pushpin image. It installs Pushpin, copies configuration, exposes the default port, and sets the command to run Pushpin.

```dockerfile
FROM debian:bookworm
RUN apt-get update && apt-get install -y pushpin
COPY pushpin.conf /etc/pushpin/
COPY routes /etc/pushpin/
EXPOSE 7999
CMD ["pushpin"]
```

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

### Run Pushpin Services Separately

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/11-service-architecture.md

Starts each Pushpin service (connmgr, proxy, handler) independently. Requires manual coordination of IPC sockets.

```bash
pushpin-connmgr &
pushpin-proxy &
pushpin-handler &
```

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

### Publish via ZeroMQ using Python

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Demonstrates how to publish messages to Pushpin using ZeroMQ REQ socket in Python. Ensure the zmq library is installed.

```python
import zmq
import json

context = zmq.Context()
socket = context.socket(zmq.REQ)
socket.connect("tcp://localhost:5560")

message = {
    "items": [
        {
            "channel": "updates",
            "formats": {
                "http-stream": {"content": "Hello from ZMQ"}
            }
        }
    ]
}

# Encode as JSON and send
socket.send_json(message)
response = socket.recv()
```

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

### GRIP Response Mode Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Holds the connection briefly for an immediate response but does not hold it long-term. The backend responds with Grip-Hold: response.

```http
HTTP/1.1 200 OK
Grip-Hold: response
Content-Type: application/json

{"status": "connected"}
```

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

### HTTP Request Proxying Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Demonstrates a standard HTTP request to a backend and how the backend perceives it after proxying. Includes common headers like Host, Content-Type, and X-Forwarded-*.

```http
POST /api/endpoint HTTP/1.1
Host: localhost:7999
Content-Type: application/json
X-Forwarded-For: 203.0.113.42
X-Forwarded-Protocol: https

{"request": "data"}
```

```http
POST /api/endpoint HTTP/1.1
Host: backend.example.com
Content-Type: application/json
X-Forwarded-For: 203.0.113.42
X-Forwarded-Protocol: https

{"request": "data"}
```

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

### Publish Request with Required Fields

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Example of a valid publish request JSON, highlighting required fields like 'channel' and 'formats'.

```json
{
  "items": [
    {
      "channel": "updates",      // Required
      "formats": {                // Required
        "http-stream": {
          "content": "data"
        }
      }
    }
  ]
}
```

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

### WebSocket-Over-HTTP Opening Request

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Example HTTP request headers for a WebSocket upgrade. Includes 'Upgrade: websocket' and 'Sec-WebSocket-Key' for the handshake.

```http
POST /ws HTTP/1.1
Upgrade: websocket
Upgrade: websocket
Sec-WebSocket-Key: ...
Grip-Pong: true

(handshake)
```

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

### Publishing to Connections via cURL

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/04-connmgr-api.md

Demonstrates how to publish messages to all subscribers using cURL. This example targets the Pushpin publish endpoint with JSON payload specifying the channel and content.

```bash
# Publish to all subscribers
curl -X POST http://localhost:5561/publish \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "channel": "updates", "formats": { "http-stream": { "content": "new data\n" } } } ] }'
```

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

### Invalid Route Specifications

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Examples of syntax errors in the routes file that will cause Pushpin to fail startup.

```routes
# ERROR: Missing backend spec
/api
```

```routes
# ERROR: Invalid backend URL
/api http://[invalid
```

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

### IPC Optimization for Handler Sockets

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

An example INI configuration demonstrating the use of IPC sockets for optimized handler service communication.

```ini
[handler]
push_in_spec = ipc:///tmp/pushpin-in
push_in_sub_specs = ipc:///tmp/pushpin-sub
stats_spec = ipc:///tmp/pushpin-stats
command_spec = ipc:///tmp/pushpin-cmd
```

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

### Publish Data using Django Library

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

This Python snippet demonstrates publishing data using the `django-grip` library. It requires the library to be installed and configured.

```python
# Django with django-grip
from django_grip import publish

publish('updates', HttpStreamFormat('new data\n'))
```

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

### http-stream Format Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/06-publish-api.md

Shows the structure for sending text or binary data, closing a connection, or specifying HTTP response details for the http-stream format.

```json
{
  "http-stream": {
    "content": "data",
    "content-bin": "base64data",
    "action": "send|close",
    "code": 200,
    "reason": "OK",
    "headers": [
      ["Header-Name", "header-value"]
    ]
  }
}
```

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

### HTTP Backend Examples

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Specifies HTTP or HTTPS backends. The request path is appended to the backend URL if no path is specified in the backend spec.

```plaintext
/api http://localhost:8000
/api https://api.example.com:443
/stream http://stream-backend.internal:9000/grip
```

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

### CustomConfig Initialization

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Shows how to create a new CustomConfig instance, attempting to load configuration from a specified file path.

```rust
impl CustomConfig {
    pub fn new(config_file: &str) -> Result<CustomConfig, ConfigError>
}
```

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

### Specify Routes File Path

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Use the `routesfile` key within the `[proxy]` section to specify the path to your Pushpin routes file. This example shows how to reference a file located in the library directory.

```ini
[proxy]
routesfile = {libdir}/routes.prod
```

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

### Processing a Held Connection

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/04-connmgr-api.md

Example of setting up headers for a held connection in Pushpin. This configures Pushpin to keep the connection open and subscribe to a specific channel.

```rust
// Backend response
let headers = vec![
    Header { name: b"Grip-Hold", value: b"stream" },
    Header { name: b"Grip-Channel", value: b"updates" },
];

// Pushpin will:
// 1. Send response to client
// 2. Keep connection open
// 3. Subscribe to "updates" channel
// 4. Inject published data as response body
```

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

### Spawn Services with Executor

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/11-service-architecture.md

Demonstrates how to use the executor framework to spawn multiple services and run them until shutdown. Ensure the executor and spawner are initialized before spawning.

```rust
let executor = Executor::new(capacity)?;
let spawner = executor.spawner();

// Spawn each service
spawner.spawn(connmgr_service);
spawner.spawn(proxy_service);
spawner.spawn(handler_service);

// Run until shutdown
executor.run()
```

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

### websocket Format Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/06-publish-api.md

Details the structure for sending text or binary messages, or closing a WebSocket connection with specific codes and reasons.

```json
{
  "websocket": {
    "content": "message text",
    "content-bin": "base64binary",
    "action": "send|close",
    "code": 1000,
    "reason": "normal"
  }
}
```

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

### ZeroMQ TCP Socket Specifications

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Provides examples of TCP socket connection strings for ZeroMQ, including local, all interfaces, and hostname-based connections.

```text
tcp://127.0.0.1:5560
tcp://0.0.0.0:5560     # Listen on all interfaces
tcp://hostname:5560
```

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

### Pushpin Log Level Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Configure Pushpin's log levels. This example sets the default log level to 'info' (2) and overrides it for the 'proxy' module to 'debug' (3) and the 'handler' module to 'warn' (1).

```bash
pushpin --loglevel "2,proxy:3,handler:1"
```

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

### ZeroMQ Backend (zhttpreq) Examples

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Specifies ZeroMQ backends using TCP or IPC sockets. The backend receives requests in ZeroMQ REQ/REP format, not HTTP.

```plaintext
/backend zhttpreq/tcp://127.0.0.1:10000
/stream zhttpreq/ipc:///tmp/backend.sock
```

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

### HTTP Streaming Response Headers

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Example HTTP headers for a streaming response. The 'Grip-Hold: stream' indicates a persistent stream, and 'Grip-Channel' specifies the channel for updates.

```http
HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: updates
Content-Type: text/plain
Transfer-Encoding: chunked

welcome
```

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

### WebSocket Context API in Backend Libraries (JavaScript Example)

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Provides essential methods for managing WebSocket connections within backend applications, such as checking connection status, accepting connections, subscribing to channels, receiving messages, closing connections, and publishing messages.

```javascript
// Check if opening
wsContext.isOpening()

// Accept connection
wsContext.accept()

// Subscribe to channel
wsContext.subscribe('channel-name')

// Check for received messages
wsContext.canRecv()

// Receive message
let msg = wsContext.recv()  // or null if no messages

// Close connection
wsContext.close()

// Send message (via publisher)
publisher.publish('channel-name', messageData)
```

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

### ZeroMQ IPC Socket Specifications

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Lists examples of IPC (Unix Domain Socket) connection strings for fast local ZeroMQ communication on Linux/Unix systems.

```text
ipc:///tmp/pushpin.sock
ipc://socket            # Relative path
ipc:///var/run/pushpin.sock
```

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

### Systemd Service Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Use this configuration file to manage Pushpin as a systemd service. It specifies dependencies, user, working directory, and the command to start the Pushpin process with a configuration file and log file.

```ini
[Unit]
Description=Pushpin Realtime Message Service
After=network.target

[Service]
Type=simple
User=pushpin
Group=pushpin
WorkingDirectory=/var/lib/pushpin
ExecStart=/usr/bin/pushpin --config /etc/pushpin/pushpin.conf --logfile /var/log/pushpin.log
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

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

### Get from SlabList

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Retrieves a reference to a value in the SlabList using its key.

```rust
pub fn get(&self, key: Key) -> Option<&T>
```

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

### Python ZeroMQ Backend Handler

Source: https://github.com/fastly/pushpin/blob/main/README.md

Example Python code to act as a ZeroMQ backend handler for Pushpin. It connects to Pushpin's ZeroMQ socket, receives requests, and sends back TNetString encoded responses to manage real-time streams.

```python
import zmq
import tnetstring

zmq_context = zmq.Context()
sock = zmq_context.socket(zmq.REP)
sock.connect('tcp://127.0.0.1:10000')

while True:
    req = tnetstring.loads(sock.recv()[1:])

    resp = {
        'id': req['id'],
        'code': 200,
        'reason': 'OK',
        'headers': [
            ['Grip-Hold', 'stream'],
            ['Grip-Channel', 'test'],
            ['Content-Type', 'text/plain']
        ],
        'body': 'welcome to the stream\n'
    }

    sock.send('T' + tnetstring.dumps(resp))
```

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

### GRIP Long-Poll Mode Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Holds the connection briefly and responds with queued data on the next poll. The backend responds with Grip-Hold: long-poll and Grip-Channel headers.

```http
HTTP/1.1 200 OK
Grip-Hold: long-poll
Grip-Channel: messages
Content-Type: application/json

[{"id": "msg1", "text": "hello"}]
```

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

### Executor::run

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Starts the main event loop of the Executor to process and run tasks.

```APIDOC
## Executor::run

### Description
Executes the main loop of the `Executor`, processing and running scheduled tasks until completion or termination.

### Method
`pub fn run(&mut self) -> Result<(), Error>`

### Return Value
- `Result<(), Error>` - `Ok(())` if the executor runs successfully, or an `Error` if any issues arise during execution.
```

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

### Configure Express.js for Pushpin

Source: https://github.com/fastly/pushpin/blob/main/README.md

Set up Express.js with ServeGrip middleware and configure the control URI and key for Pushpin.

```javascript
const express = require('express');
const { ServeGrip } = require('@fanoutio/serve-grip');

var app = express();

// Instantiate the middleware and register it with Express
const serveGrip = new ServeGrip({
    grip: { 'control_uri': 'http://localhost:5561', 'key': 'changeme' }
});
app.use(serveGrip);

// Instantiate the publisher to use from your code to publish messages
const publisher = serveGrip.getPublisher();

app.get('/hello', (req, res) => {
    res.send('hello world\n');
});
```

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

### Running Multiple Pushpin Instances

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Demonstrates how to run multiple Pushpin instances, each with a unique ID and port, allowing for distinct IPC sockets.

```bash
# Instance 0
pushpin --id 0 --port 7999

# Instance 1
pushpin --id 1 --port 8000

# Instance 2
pushpin --id 2 --port 8001
```

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

### WebSocket: Publish Response

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of publishing a WebSocket message response to a GRIP channel.

```http
POST /publish HTTP/1.1
Content-Type: application/json

{
  "items": [{
    "channel": "chat",
    "formats": {"websocket": {"content": "reply"}}
  }]
}
```

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

### TlsStream Structure

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/04-connmgr-api.md

Represents a TLS-wrapped connection. No specific setup is required beyond its instantiation.

```rust
pub struct TlsStream {
    // TLS-wrapped connection
}
```

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

### Initiate HTTP Streaming Connection

Source: https://github.com/fastly/pushpin/blob/main/README.md

Respond to a proxied request with `Grip-Hold: stream` and `Grip-Channel` headers to establish an HTTP streaming connection. Pushpin will then manage the stream.

```http
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
Grip-Hold: stream
Grip-Channel: test

welcome to the stream
```

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

### WebSocket: Backend Receives Client Message

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of how a backend receives a WebSocket message from a client.

```http
POST /ws HTTP/1.1
Grip-Pong: true
Content-Type: application/octet-stream

(binary frame: "hello")
```

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

### Publish Data using Go Library

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

This Go snippet illustrates publishing data using the `grip` library. It's a concise way to send HTTP stream content directly.

```go
// Go with grip library
grip.PublishHttpStream("updates", "new data\n")
```

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

### HTTP Streaming: Backend Response

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Example of a backend response that holds a stream using the Grip-Hold header.

```http
HTTP/1.1 200 OK
Grip-Hold: stream
Grip-Channel: updates
Content-Type: text/plain
Grip-Keep-Alive: 30

Initial data
```

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

### Specify Pushpin Configuration File

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Use this command to explicitly provide the path to the Pushpin configuration file.

```bash
pushpin --config /path/to/pushpin.conf
```

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

### Global and Service Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

This snippet shows the global configuration section, including include paths and runtime directories, along with runner-specific settings like ports and logging.

```ini
[global]
include = {libdir}/internal.conf
rundir = run
ipc_prefix = pushpin-
port_offset = 0
stats_connection_ttl = 120
stats_connection_send = true

[runner]
services = connmgr,proxy,handler
http_port = 7999
https_ports = 443
logdir = log
log_level = 2
client_buffer_size = 8192
client_maxconn = 50000
```

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

### Specify Configuration File Path

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Use the --config flag to explicitly provide the path to the pushpin configuration file.

```bash
pushpin --config /path/to/config
```

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

### http-long-poll Format Example

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/06-publish-api.md

Illustrates the structure for providing response content, status code, and headers for the http-long-poll format.

```json
{
  "http-long-poll": {
    "content": "data",
    "content-bin": "base64data",
    "code": 200,
    "reason": "OK",
    "headers": [
      ["Header-Name", "header-value"]
    ]
  }
}
```

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

### Publish Data using Express Library

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

This JavaScript snippet shows how to publish data using the `serve-grip` library with an Express application. Ensure the `publisher` object is correctly initialized.

```javascript
// Express with serve-grip
await publisher.publishFormats('updates', 
  new HttpStreamFormat('new data\n'));
```

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

### Wait for Socket Release

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

This command waits for approximately 60 seconds for TCP sockets in TIME_WAIT to be released before starting Pushpin.

```bash
# TCP sockets stay in TIME_WAIT for ~60 seconds
sleep 60 && pushpin
```

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

### Express.js WebSocket Endpoint Example

Source: https://github.com/fastly/pushpin/blob/main/README.md

An Express.js endpoint that handles WebSocket connections, accepting, subscribing, receiving, and publishing messages.

```javascript
const { WebSocketMessageFormat } = require( '@fanoutio/grip' );

app.post('/websocket', async (req, res) => {
    const { wsContext } = req.grip;

    // If this is a new connection, accept it and subscribe it to a channel
    if (wsContext.isOpening()) {
        wsContext.accept();
        wsContext.subscribe('all');
    }

    while (wsContext.canRecv()) {
        var message = wsContext.recv();

        // If return value is null then connection is closed
        if (message == null) {
            wsContext.close();
            break;
        }

        // broadcast the message to everyone connected
        await publisher.publishFormats('all', WebSocketMessageFormat(message));
    }

    res.end();
});
```

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

### Get Server Connection State

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Retrieves the current state of the server connection. This is useful for monitoring the connection's lifecycle.

```rust
pub fn state(&self) -> ServerState
```

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

### Proxy and Handler Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

This snippet details proxy settings such as routes files and signature keys, and handler configurations for push-in addresses and maximum body sizes.

```ini
[proxy]
routesfile = routes
sig_iss = pushpin
sig_key = CHANGE_ME_IN_PRODUCTION
accept_x_forwarded_protocol = false

[handler]
push_in_http_addr = 127.0.0.1
push_in_http_port = 5561
push_in_http_max_body_size = 1000000
stats_format = tnetstring
```

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

### Get Configuration File Path

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Function to determine the configuration file path, considering working directory and command-line arguments.

```rust
pub fn get_config_file(
    work_dir: &Path,
    arg_config: Option<PathBuf>,
) -> Result<PathBuf, Box<dyn Error>>
```

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

### Run Reactor Event Loop

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Starts and runs the reactor's event loop. Returns an error if the loop encounters an issue.

```rust
pub fn run(&self) -> Result<(), Error>
```

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

### Create Atomic Counter

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Creates a new atomic counter with a specified initial value. This is the starting point for using the Counter type.

```rust
pub fn new(initial: usize) -> Self
```

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

### Check Configuration File Permissions

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Verify that the configuration file is readable by the Pushpin user.

```bash
ls -la ./config/pushpin.conf
# Must be readable by pushpin user
```

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

### Create New Parse Scratch Buffer

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Initializes a new instance of the `ParseScratch` buffer. This is the starting point for managing parsing state.

```rust
pub fn new() -> Self
```

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

### Configure Default Certificate Path

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Update the Pushpin configuration to point to the correct certificate file path.

```ini
[runner]
default_cert = /etc/pushpin/certs/example.com.pem
```

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

### Check Route Syntax

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Verify the syntax of your route patterns and backend specifications. Ensure each pattern is followed by a valid backend specification.

```bash
# Valid format:
pattern backend-spec

# Invalid (missing backend):
/api
```

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

### HTTP Backend Socket Specification

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/04-connmgr-api.md

Specifies an HTTP or HTTPS backend endpoint using a URL format. Example: http://api.example.com:8000

```plaintext
http://host:port/path
https://host:port/path
```

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

### Configure Pushpin Runtime Directory

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Specify a writable directory for Pushpin's runtime files in the configuration.

```ini
[global]
rundir = /tmp/pushpin
```

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

### Publish via ZeroMQ using Node.js

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Shows how to publish messages to Pushpin using ZeroMQ REQ socket in Node.js. Requires the 'zeromq' package.

```javascript
const zmq = require('zeromq');

async function publish() {
  const socket = new zmq.Request();
  await socket.connect("tcp://localhost:5560");
  
  const message = {
    items: [{
      channel: "updates",
      formats: {
        "http-stream": { content: "Hello from ZMQ" }
      }
    }]
  };
  
  await socket.send(JSON.stringify(message));
  const response = await socket.receive();
  socket.close();
}

publish();
```

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

### Get Remaining Timeout Duration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Returns the amount of time left before the timeout expires. Useful for progress indicators or adaptive logic.

```rust
pub fn remaining(&self) -> Duration
```

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

### Basic INI Configuration Format

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Illustrates the fundamental INI file format used by Pushpin, with sections and key-value pairs.

```ini
[section]
key = value
```

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

### Health Check Pushpin Service

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Perform a simple HTTP GET request to the root path to verify if Pushpin is running and responsive.

```bash
curl -i http://localhost:7999/
```

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

### AsyncUnixStream Connect Method

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

Asynchronously connects to a Unix domain socket at the specified path. Returns a Result containing the new AsyncUnixStream or an io::Error.

```rust
pub async fn connect<P: AsRef<Path>>(path: P) -> Result<Self, io::Error>
```

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

### Publish Message with PHP

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/06-publish-api.md

This PHP snippet demonstrates how to publish a message to a channel using cURL. It formats the payload similarly to the Node.js example.

```php
<?php
function publish($channel, $content) {
  $payload = json_encode([
    'items' => [
      [
        'channel' => $channel,
        'formats' => [
          'http-stream' => ['content' => $content],
          'websocket' => ['content' => $content]
        ]
      ]
    ]
  ]);

  $ch = curl_init('http://localhost:5561/publish');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return true;
}

publish('updates', 'Hello, subscribers!');
?>
```

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

### Troubleshoot 'No Route Found' Error

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Use this command to view your Pushpin routes configuration. Ensure your request path matches a defined pattern.

```bash
cat /etc/pushpin/routes
```

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

### Counter Usage

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Shows how to initialize and increment a Counter.

```rust
let counter = Counter::new(0);
counter.add(5);
assert_eq!(counter.load(), 5);
```

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

### Default Configuration File Path

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Returns the default path for the configuration file.

```rust
pub fn default_config_file() -> PathBuf
```

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

### Async/Await for Non-Blocking I/O in ConnMgr

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/11-service-architecture.md

Demonstrates the use of Rust's async/await with `select!` for non-blocking I/O operations within the connection manager, handling requests, messages, and shutdown signals.

```rust
// Non-blocking I/O in connmgr
loop {
    select! {
        Some(request) = requests.recv() => handle_request(request),
        Some(message) = messages.recv() => deliver_message(message),
        _ = shutdown.notified() => break,
    }
}
```

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

### WebSocket-Over-HTTP Incoming Message

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Example HTTP request representing an incoming message from a WebSocket client. It uses POST with 'Grip-Pong: true' and 'Content-Type: application/octet-stream'.

```http
POST /ws HTTP/1.1
Grip-Pong: true
Content-Type: application/octet-stream

(binary: "hello")
```

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

### Configure Multiple ZeroMQ Publishers

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Configure the handler to listen to multiple ZeroMQ publishers by providing a comma-separated list of addresses.

```ini
push_in_sub_specs = tcp://127.0.0.1:5562,ipc:///tmp/pushpin-sub
```

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

### ClientConnection::new

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Creates a new instance of the client connection handler.

```APIDOC
## ClientConnection::new

### Description
Creates a new client connection handler.

### Method
`new`

### Returns
`Self` - A new ClientConnection instance.
```

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

### Enable ZeroMQ SUB Socket for Handler

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Configure the handler to enable a ZeroMQ SUB socket for receiving subscription announcements. Set 'push_in_sub_connect' to false if the handler should bind.

```ini
[handler]
push_in_sub_specs = tcp://127.0.0.1:5562
push_in_sub_connect = false   # Handler binds
```

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

### AsyncUnixStream::connect

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

Establishes a non-blocking Unix domain socket connection to a specified path.

```APIDOC
## AsyncUnixStream::connect

### Description
Connect to a Unix domain socket at the specified path asynchronously.

### Method
`async fn connect<P: AsRef<Path>>(path: P) -> Result<Self, io::Error>`

### Parameters
#### Path Parameters
- **path** (P: AsRef<Path>) - Required - The path to the Unix domain socket.
```

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

### Run Pushpin with Elevated Permissions

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/08-cli-reference.md

Execute the pushpin command with sudo if permission denied errors occur, indicating a need for root privileges.

```bash
sudo pushpin
```

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

### Get Parsed Request from Scratch Buffer

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Retrieves the currently parsed `Request` object from the `ParseScratch` buffer. This method allows access to the parsed request data.

```rust
pub fn get(&self) -> Request<'_, '_>
```

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

### Rust HTTP/1.1 Server Connection

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

Sets up an HTTP/1.1 server to listen for incoming connections on a given address. It accepts connections, receives requests, and sends responses.

```rust
let listener = AsyncTcpListener::bind(addr).await?;

loop {
    let (stream, addr) = listener.accept().await?;
    
    let mut server = http1::ServerConnection::new();
    let (status, request) = server.recv_request(&mut stream, &mut headers).await?;
    
    server.send_response(&mut stream, 200, b"OK", &headers).await?;
}
```

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

### Pushpin ZeroMQ Backend Connection

Source: https://github.com/fastly/pushpin/blob/main/README.md

Configure Pushpin to bind a ZeroMQ REQ-compatible socket for backend handlers. This setup is used when a full web server is not required.

```text
* zhttpreq/tcp://127.0.0.1:10000
```

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

### TlsAcceptor::new

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/04-connmgr-api.md

Creates a new TLS acceptor. Requires the path to the certificate file.

```rust
pub fn new(cert_path: &str) -> Result<Self, Error>
```

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

### Monitor Pushpin Process

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Use standard system utilities to monitor the Pushpin process. This includes checking running processes and their resource utilization.

```bash
ps aux | grep pushpin
```

```bash
top -p $(pgrep pushpin)
```

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

### Get Remaining Unparsed Bytes

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Returns a slice of any unparsed data that remains in the `ParseScratch` buffer. Useful for handling partial reads or data that spans multiple operations.

```rust
pub fn remaining_bytes(&self) -> &[u8]
```

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

### Subscribe to Channels with a Prefix using Grip-Channel-Prefix

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/07-grip-protocol.md

Use the Grip-Channel-Prefix header to subscribe to all channels that match a given prefix. This is useful for dynamic channel subscriptions.

```http
Grip-Channel-Prefix: user/
```

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

### Security: Input Validation for Channel Names

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Validate all input, especially channel names, to prevent security vulnerabilities. This example checks if the channel name is a string and within a reasonable length limit.

```python
@app.route('/handler', methods=['POST'])
def handler():
    data = request.json
    
    # Validate channel name
    if not isinstance(data.get('channel'), str) or len(data['channel']) > 255:
        return 'Invalid channel', 400
    
    set_hold_stream(request, data['channel'])
    return Response('OK')
```

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

### Manual Test Stream and Publish

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Demonstrates manual testing of the stream and message publishing using curl. The first command tests the stream endpoint, and the second publishes a message to the 'updates' channel.

```bash
# Test stream
curl -i http://localhost:8000/stream

# In another terminal, publish
curl -X POST http://localhost:5561/publish \
  -d '{"items": [{"channel": "updates", "formats": {"http-stream": {"content": "test\n"}}}]}'
```

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

### Pushpin CLI Arguments

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/02-configuration.md

Basic usage of the Pushpin CLI. Use this to override configuration file settings.

```bash
pushpin [OPTIONS]
```

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

### Unit Test for Stream Handler

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Tests the stream handler functionality by creating an app instance and making a GET request to the /stream endpoint. Verifies the response status code and specific headers.

```python
def test_stream_handler():
    app = create_app()
    client = app.test_client()
    
    response = client.get('/stream')
    
    assert response.status_code == 200
    assert 'Grip-Hold' in response.headers
    assert response.headers['Grip-Channel'] == 'updates'
```

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

### ZeroMQ Backend Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/14-backend-integration.md

Configure Pushpin to use a ZeroMQ REQ/REP socket server as the backend. The routes file specifies the ZeroMQ endpoint.

```ini
# routes file
* zhttpreq/tcp://127.0.0.1:10000
```

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

### Configure Django Settings for Pushpin

Source: https://github.com/fastly/pushpin/blob/main/README.md

Configure Django settings to use Pushpin's middleware and specify the control URI for Pushpin proxies.

```python
MIDDLEWARE_CLASSES = (
    'django_grip.GripMiddleware',
    ...
)

GRIP_PROXIES = [{'control_uri': 'http://localhost:5561'}]
```

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

### Check and Set Socket Directory Permissions

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Verify and adjust permissions for the /tmp directory if Pushpin cannot create sockets.

```bash
ls -la /tmp/
chmod 755 /tmp/
```

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

### Enable Module-Specific Logging

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Configure specific log levels for different Pushpin modules like connmgr, proxy, and handler. This allows for granular debugging.

```bash
pushpin --loglevel "connmgr:3,proxy:2,handler:3"
```

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

### Pushpin Vertical Scaling Configuration

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/11-service-architecture.md

Shows INI-style configuration parameters for vertical scaling, including tuning connection limits, buffer sizes, message rates, and high-water marks for a single instance.

```ini
[runner]
client_maxconn = 100000          # Increase connection limit
client_buffer_size = 16384        # Tune buffer size

[handler]
message_rate = 10000             # Increase throughput
message_hwm = 100000             # Larger queue
```

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

### Build Pushpin Image with Docker CLI

Source: https://github.com/fastly/pushpin/blob/main/docker/README.md

Builds the Pushpin Docker image using the docker CLI, allowing manual specification of source and image versions.

```sh
docker build --build-arg VERSION={SOURCE_VERSION} -t fanout/pushpin:{IMAGE_VERSION} .
```

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

### Run Pushpin Container with Custom Configuration

Source: https://github.com/fastly/pushpin/blob/main/docker/README.md

Runs a Pushpin container with a custom configuration volume mounted. This allows you to provide your own Pushpin configuration files to the container.

```sh
docker run \
  -d \
  -p 7999:7999 \
  -p 5560-5563:5560-5563 \
  -v $(pwd)/config:/etc/pushpin/ \
  --rm \
  --name pushpin \
  fanout/pushpin
```

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

### Create Debian Package

Source: https://github.com/fastly/pushpin/blob/main/packaging/debian/README.md

Generates a Debian package (.deb) file. Specify the distribution revision. This command outputs to ./target/debian. Repeat for each target distribution.

```bash
cargo deb --no-build --deb-revision 1~noble1
```

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

### ZeroMQ Backend with HTTP Fallback

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Configures a primary backend using ZeroMQ and a fallback HTTP backend for requests that do not match the primary route.

```routes
/handler zhttpreq/tcp://127.0.0.1:10000
* http://fallback:8000
```

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

### Set Certificate File Permissions

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Ensure the certificate file has appropriate read permissions for the Pushpin process.

```bash
chmod 644 /path/to/cert.pem
```

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

### ServerConnection::new

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/03-http-protocol.md

Creates a new instance of the ServerConnection handler.

```APIDOC
## ServerConnection::new

### Description
Creates a new server connection handler.

### Method
Rust function call

### Parameters
None

### Response
- `Self`: A new ServerConnection handler instance.
```

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

### Build Pushpin Image with Docker Compose

Source: https://github.com/fastly/pushpin/blob/main/docker/README.md

Builds the Pushpin Docker image using docker-compose. This is the easiest way to build the image as it automatically picks up source and image versions from compose.yaml.

```sh
docker-compose build
```

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

### Verify Certificate File Existence

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/12-errors-and-troubleshooting.md

Check if the certificate file exists and has the correct permissions using the `ls` command.

```bash
ls -la /path/to/cert.pem
```

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

### Route with Authentication Credentials

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/10-routes-file.md

Backend specifications can include credentials, though this is not recommended. Use environment variables or configuration files for better security.

```routes
/secure http://user:pass@backend:8000
```

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

### Create FileWatcher

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/05-core-types.md

Initializes a FileWatcher to monitor a specific file path. Returns an error if the path is invalid or inaccessible.

```rust
pub fn new(path: &Path) -> Result<Self, Error>
```

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

### ZeroMQ Backend Configuration in Routes

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/13-zeromq-integration.md

Configure Pushpin routes to direct traffic to ZeroMQ backends using TCP or IPC protocols.

```routes
/handler zhttpreq/tcp://127.0.0.1:10000
/stream zhttpreq/ipc:///tmp/backend.sock
```

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

### Accept Incoming Connection

Source: https://github.com/fastly/pushpin/blob/main/_autodocs/09-async-io.md

Asynchronously accepts an incoming network connection on a listener.

```rust
pub async fn accept(&self) -> Result<(NetStream, SocketAddr), io::Error>
```