stackhawk/http-broker-client

Verified Publisher

By StackHawk

•Updated 8 months ago

A client to broker http requests to your network from StackHawk platform

Image

10K+

Overview Tags

stackhawk/http-broker-client repository overview

⁠HTTP Broker Client

A high-performance, fault-tolerant HTTP request relay client. The HTTP Broker Client connects to the StackHawk Platform and relays HTTP requests to target services with automatic reconnection, error handling, and client IP preservation.

⁠🚀 Quick Start

# Basic usage with required parameters
docker run -e CLIENT_ID=api-client -e URL_PREFIX=https://api.example.com stackhawk/http-broker-client

# With debug logging
docker run \
  -e CLIENT_ID=api-client \
  -e URL_PREFIX=https://api.example.com \
  -e LOG_LEVEL=debug \
  stackhawk/http-broker-client

# With broker authentication
docker run \
  -e CLIENT_ID=api-client \
  -e URL_PREFIX=https://api.example.com \
  -e BROKER_AUTH_KEY=your-secret-auth-key \
  stackhawk/http-broker-client

⁠🔧 Configuration

⁠Required Environment Variables

Variable	Description	Example
`CLIENT_ID`	Unique identifier for this client	`api-client`
`URL_PREFIX`	URL prefix for the target service	`https://api.example.com`

⁠Optional Environment Variables

Variable	Default	Description
`BROKER_AUTH_KEY`	-	Authentication key for broker server validation
`LOG_LEVEL`	`info`	Log level (error, warn, info, debug, trace)
`CERT_DIR`	-	Custom certificate directory path
`PROXY_PROTOCOL`	`false`	Enable PROXY protocol support
`PROXY_CLIENT_IP`	-	Client IP for PROXY protocol (auto-detected)

⁠📊 Features

🔗 Automatic Reconnection: Clients automatically reconnect with configurable retry logic
🛡️ Fault Tolerant: Robust error handling and graceful degradation
🔧 Easy Configuration: Environment variable support for all settings
📊 Observability: Comprehensive structured logging with tracing
🛑 Graceful Shutdown: Proper signal handling for clean shutdown
🔐 TLS Certificate Support: Custom certificate directory support
📍 PROXY Protocol: Client IP preservation for target services

⁠🏗️ Architecture

The HTTP Broker Client is part of the StackHawk Platform:

┌─────────────────┐                   ┌─────────────────┐    HTTP Requests    ┌─────────────────┐
│                 │◄──────────────────┤                 │◄────────────────────┤                 │
│   StackHawk     │                   │   HTTP Broker   │                     │   Target        │
│   Platform      │                   │   Client        │                     │   Service       │
│                 │                   │   (This Image)  │                     │                 │
│  • Request      │                   │                 │                     │  • GitHub       │
│    Routing      │                   │  • Auto         │                     │    Enterprise   │
│  • Load         │                   │    Reconnect    │                     │  • Your API     │
│    Balancing    │                   │  • Error        │                     │  • Web App      │
│                 │                   │    Handling     │                     │  • Service      │
└─────────────────┘                   │  • Request      │                     │                 │
                                      │    Relay        │                     │                 │
                                      └─────────────────┘                     └─────────────────┘

⁠🌐 Usage Examples

⁠Basic API Client

docker run \
  -e CLIENT_ID=api-client \
  -e URL_PREFIX=https://jsonplaceholder.typicode.com \
  stackhawk/http-broker-client

⁠Multiple Clients for Different Services

# API service client
docker run -d --name api-client \
  -e CLIENT_ID=api-client \
  -e URL_PREFIX=https://api.example.com \
  stackhawk/http-broker-client

# Web service client  
docker run -d --name web-client \
  -e CLIENT_ID=web-client \
  -e URL_PREFIX=https://web.example.com \
  stackhawk/http-broker-client

# Auth service client
docker run -d --name auth-client \
  -e CLIENT_ID=auth-client \
  -e URL_PREFIX=https://auth.example.com \
  stackhawk/http-broker-client

⁠Production Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: http-broker-client
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: http-broker-client
  template:
    metadata:
      labels:
        app: http-broker-client
    spec:
      containers:
      - name: http-broker-client
        image: stackhawk/http-broker-client:latest
        env:
        - name: CLIENT_ID
          value: "production-api"
        - name: URL_PREFIX
          value: "https://api.production.com"
        - name: BROKER_AUTH_KEY
          valueFrom:
            secretKeyRef:
              name: broker-auth
              key: auth-key
        - name: LOG_LEVEL
          value: "warn"
        - name: PROXY_PROTOCOL
          value: "true"
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "256Mi"
            cpu: "200m"
        livenessProbe:
          exec:
            command:
            - /bin/sh
            - -c
            - "pgrep http-broker-client"
          initialDelaySeconds: 30
          periodSeconds: 30
---
apiVersion: v1
kind: Secret
metadata:
  name: broker-auth
  namespace: default
type: Opaque
data:
  auth-key: eW91ci1wcm9kdWN0aW9uLWF1dGgta2V5  # base64 encoded key

⁠Development with Debug Logging

docker run \
  -e CLIENT_ID=dev-client \
  -e URL_PREFIX=http://localhost:8080 \
  -e LOG_LEVEL=debug \
  --network host \
  stackhawk/http-broker-client

⁠Multiple Kubernetes Clients

Deploy multiple clients for different services:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-client
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api-client
  template:
    metadata:
      labels:
        app: api-client
    spec:
      containers:
      - name: http-broker-client
        image: stackhawk/http-broker-client:latest
        env:
        - name: CLIENT_ID
          value: "api-client"
        - name: URL_PREFIX
          value: "https://api.example.com"
        - name: BROKER_AUTH_KEY
          valueFrom:
            secretKeyRef:
              name: broker-auth
              key: auth-key
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "128Mi"
            cpu: "100m"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-client
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web-client
  template:
    metadata:
      labels:
        app: web-client
    spec:
      containers:
      - name: http-broker-client
        image: stackhawk/http-broker-client:latest
        env:
        - name: CLIENT_ID
          value: "web-client"
        - name: URL_PREFIX
          value: "https://web.example.com"
        - name: BROKER_AUTH_KEY
          valueFrom:
            secretKeyRef:
              name: broker-auth
              key: auth-key
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "128Mi"
            cpu: "100m"

⁠🔐 Custom Certificates

Mount custom certificates for enhanced security using Kubernetes ConfigMaps or Secrets:

# Create ConfigMap for certificates
apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-certs
data:
  ca-cert.pem: |
    -----BEGIN CERTIFICATE-----
    # Your custom CA certificate content here
    -----END CERTIFICATE-----
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-client
spec:
  replicas: 1
  selector:
    matchLabels:
      app: secure-client
  template:
    metadata:
      labels:
        app: secure-client
    spec:
      containers:
      - name: http-broker-client
        image: stackhawk/http-broker-client:latest
        env:
        - name: CLIENT_ID
          value: "secure-client"
        - name: URL_PREFIX
          value: "https://secure-api.example.com"
        - name: CERT_DIR
          value: "/app/certs"
        volumeMounts:
        - name: custom-certs
          mountPath: /app/certs
          readOnly: true
      volumes:
      - name: custom-certs
        configMap:
          name: custom-certs

Supported certificate formats: .pem, .crt, .cer, .cert

⁠🔐 Broker Authentication

The broker authentication key provides an additional layer of security for client-server connections. These keys are generated and provided by the StackHawk Platform. When configured on both the client and server, only clients with the correct key can establish connections.

# Client with broker authentication
docker run \
  -e CLIENT_ID=secure-client \
  -e URL_PREFIX=https://api.example.com \
  -e BROKER_AUTH_KEY=your-secret-auth-key \
  stackhawk/http-broker-client

# Using Kubernetes with secrets management
apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-client
spec:
  replicas: 1
  selector:
    matchLabels:
      app: secure-client
  template:
    metadata:
      labels:
        app: secure-client
    spec:
      containers:
      - name: http-broker-client
        image: stackhawk/http-broker-client:latest
        env:
        - name: CLIENT_ID
          value: "secure-client"
        - name: URL_PREFIX
          value: "https://api.example.com"
        - name: BROKER_AUTH_KEY
          valueFrom:
            secretKeyRef:
              name: broker-auth
              key: auth-key

Security Best Practices:

Broker authentication keys are generated and managed by the StackHawk Platform
Store keys securely using Kubernetes secrets or secure environment management systems
Rotate keys regularly in production environments
Never commit authentication keys to version control

⁠📍 PROXY Protocol Support

Enable PROXY protocol to preserve original client IP addresses:

docker run \
  -e CLIENT_ID=proxy-client \
  -e URL_PREFIX=https://api.example.com \
  -e PROXY_PROTOCOL=true \
  -e PROXY_CLIENT_IP=192.168.1.100 \
  stackhawk/http-broker-client

When enabled, the client adds these headers to target requests:

X-Forwarded-For: Original client IP
X-Real-IP: Original client IP
X-Forwarded-Proto: Protocol (http/https)
X-Forwarded-Port: Original client port

⁠🔍 Health Monitoring

Monitor client health through structured logs:

# View logs in real-time
docker logs -f <container-name>

# Filter for specific log levels
docker logs <container-name> 2>&1 | grep "ERROR\|WARN"

# Check connection status
docker logs <container-name> 2>&1 | grep "Connected to server\|Disconnected from server"

Key log events:

Connection establishment/failures
Request processing
Reconnection attempts
Error conditions

⁠🚀 Performance Tuning

# For high-throughput scenarios, ensure adequate resources
docker run \
  --memory=256m \
  --cpus=1.0 \
  -e CLIENT_ID=high-perf-client \
  -e URL_PREFIX=https://api.example.com \
  stackhawk/http-broker-client

⁠🛠️ Troubleshooting

⁠Enabling Debug Logging

For troubleshooting issues, increase the log level to get more detailed information:

# Enable debug logging for detailed information
docker run \
  -e CLIENT_ID=your-client-id \
  -e URL_PREFIX=https://your-api.com \
  -e LOG_LEVEL=debug \
  stackhawk/http-broker-client

# Enable trace logging for maximum detail
docker run \
  -e CLIENT_ID=your-client-id \
  -e URL_PREFIX=https://your-api.com \
  -e LOG_LEVEL=trace \
  stackhawk/http-broker-client

⁠What to Look for in Logs

Key log events that indicate different issues:

Connection Issues:

Look for "Connected to server" vs "Disconnected from server" messages
"Failed to connect" or "Connection refused" indicates server connectivity problems
Repeated reconnection attempts suggest network instability

Authentication Problems:

"Authentication failed" messages indicate incorrect or missing broker auth key
"Client validation failed" suggests the client_id is not authorized

Target Service Issues:

HTTP error codes (4xx, 5xx) in request processing logs
"Connection timeout" or "Request timeout" messages
"Failed to relay request" indicates problems reaching the target service

Configuration Problems:

"Invalid URL prefix" suggests malformed URL_PREFIX
Certificate-related errors indicate TLS/SSL issues

⁠🏷️ Tags and Versions

latest: Latest stable release
v0.1.17: Specific version
main: Latest development build

⁠📖 Additional Resources

Documentation: Contact StackHawk support for detailed documentation
Support: Contact StackHawk support for assistance

Built with ❤️ for maximum performance and reliability.

Tag summary

Recent tags

Content type

Image

Digest

sha256:10580ac9c…

Size

8.7 MB

Last updated

8 months ago

docker pull stackhawk/http-broker-client

This week's pulls

Pulls:

7,445

Last week

Learn more⁠