initial commit

proxies/http/README.md

@@ -0,0 +1,149 @@
+# Hero HTTP Proxy
+
+HTTP proxy server for converting webhook requests to WebSocket JSON-RPC calls to the Hero WebSocket server.
+
+## Overview
+
+This proxy server acts as a bridge between HTTP webhook endpoints (like Stripe, iDenfy) and the Hero WebSocket server. It receives HTTP webhook requests, verifies signatures, and forwards them as JSON-RPC calls to the WebSocket server.
+
+## Features
+
+- **Webhook Support**: Built-in support for Stripe and iDenfy webhooks
+- **Signature Verification**: HMAC-SHA256 signature verification for security
+- **Extensible Design**: Easy to add new webhook providers
+- **WebSocket Connection Pooling**: Reuses WebSocket connections for efficiency
+- **Configurable**: JSON-based configuration with environment variable support
+- **Health Checks**: Built-in health check endpoint
+
+## Configuration
+
+The proxy can be configured via a JSON configuration file or environment variables:
+
+### Environment Variables
+- `STRIPE_WEBHOOK_SECRET`: Stripe webhook signing secret
+- `IDENFY_WEBHOOK_SECRET`: iDenfy webhook signing secret
+
+### Configuration File Example
+```json
+{
+  "webhooks": {
+    "stripe": {
+      "secret": "whsec_...",
+      "signature_header": "stripe-signature",
+      "verify_signature": true
+    },
+    "idenfy": {
+      "secret": "your_idenfy_secret",
+      "signature_header": "idenfy-signature",
+      "verify_signature": true
+    }
+  },
+  "websocket_timeout": 30,
+  "max_retries": 3
+}
+```
+
+## Usage
+
+### Basic Usage
+```bash
+cargo run -- --port 8080 --websocket-url ws://localhost:3030
+```
+
+### With Configuration File
+```bash
+cargo run -- --port 8080 --websocket-url ws://localhost:3030 --config config.json
+```
+
+### Command Line Options
+- `--port, -p`: HTTP server port (default: 8080)
+- `--websocket-url, -w`: WebSocket server URL (default: ws://localhost:3030)
+- `--config, -c`: Configuration file path (optional)
+
+## Endpoints
+
+### Webhook Endpoints
+- `POST /webhooks/stripe/{circle_pk}`: Stripe webhook handler
+- `POST /webhooks/idenfy/{circle_pk}`: iDenfy webhook handler
+
+### Health Check
+- `GET /health`: Health check endpoint
+
+## Adding New Webhook Providers
+
+To add a new webhook provider:
+
+1. **Add configuration** in `src/config.rs`:
+   ```rust
+   webhooks.insert("newprovider".to_string(), WebhookConfig {
+       secret: std::env::var("NEWPROVIDER_WEBHOOK_SECRET").unwrap_or_default(),
+       signature_header: "newprovider-signature".to_string(),
+       verify_signature: true,
+   });
+   ```
+
+2. **Add signature verification** in `src/webhook/signature.rs`:
+   ```rust
+   pub fn verify_newprovider_signature(
+       payload: &[u8],
+       signature_header: &str,
+       secret: &str,
+   ) -> Result<(), ProxyError> {
+       // Implementation specific to the provider
+   }
+   ```
+
+3. **Add handler** in `src/webhook/handlers.rs`:
+   ```rust
+   pub async fn handle_newprovider_webhook(
+       req: HttpRequest,
+       path: web::Path<String>,
+       body: Bytes,
+       data: web::Data<Arc<ProxyState>>,
+   ) -> ActixResult<HttpResponse> {
+       // Handler implementation
+   }
+   ```
+
+4. **Register route** in `src/main.rs`:
+   ```rust
+   .route("/newprovider/{circle_pk}", web::post().to(webhook::handlers::handle_newprovider_webhook))
+   ```
+
+## Architecture
+
+```
+HTTP Webhook → Signature Verification → JSON-RPC → WebSocket Server
+     ↓                    ↓                ↓              ↓
+  Stripe/iDenfy    HMAC-SHA256 Check    play method    Hero Server
+```
+
+The proxy maintains persistent WebSocket connections to the Hero server and forwards webhook events as `play` method calls with appropriate scripts (e.g., `stripe_webhook_received`, `idenfy_webhook_received`).
+
+## Dependencies
+
+- **actix-web**: HTTP server framework
+- **tokio-tungstenite**: WebSocket client
+- **heromodels**: Hero project models (local dependency)
+- **serde**: JSON serialization
+- **hmac/sha2**: Signature verification
+- **clap**: Command line argument parsing
+
+## Development
+
+```bash
+# Build
+cargo build
+
+# Run tests
+cargo test
+
+# Run with debug logging
+RUST_LOG=debug cargo run
+
+# Format code
+cargo fmt
+
+# Check for issues
+cargo clippy
+```