150 lines
4.0 KiB
Markdown
150 lines
4.0 KiB
Markdown
# 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
|
|
```
|