update docs.

Author: Baker

README.md

@@ -39,7 +39,9 @@ A SMTP server that receives emails from any domain without authentication and fo
 ### Webhook Integration
 - 🔐 **HTTP Basic Auth**: Secure webhook authentication
 - 📨 **Rich Payload**: Complete email data including headers and attachments
-- 🔁 **Error Handling**: Robust webhook delivery with retry logic
+- 🔁 **Reliability Features**: Automatic retry with exponential backoff, rate limiting, and circuit breaker
+- 🛡️ **Fault Tolerance**: Circuit breaker pattern prevents cascading failures
+- ⚡ **Rate Limiting**: Configurable requests per second to protect downstream endpoints
 - ✂️ **Content Processing**: Parsed text and HTML content extraction
 
 ## Quick Start
@@ -116,6 +118,12 @@ Usage of ./inboundparse:
   -webhook string           Webhook URL for email payloads (required)
   -webhook-user string      Basic auth username for webhook (optional)
   -webhook-pass string      Basic auth password for webhook (optional)
+  -webhook-max-retries int  Maximum webhook retry attempts (default 3)
+  -webhook-retry-delay int  Initial webhook retry delay in seconds (default 1)
+  -webhook-max-retry-delay int Maximum webhook retry delay in seconds (default 30)
+  -webhook-retry-multiplier float Webhook retry delay multiplier (default 2.0)
+  -webhook-rate-limit int   Webhook requests per second rate limit (default 10)
+  -webhook-rate-burst int   Webhook rate limit burst capacity (default 20)
   -name string              SMTP server name (default "mx.inboundparse.com")
   -max-size int             Max message size bytes (default 10485760)
   -read-timeout int         Read timeout (seconds, default 30)
@@ -143,49 +151,50 @@ Usage of ./inboundparse:
 
 You can configure InboundParse using environment variables or command line flags:
 
-#### Core Configuration
-- `WEBHOOK_URL` - Webhook URL (required)
-- `WEBHOOK_USER` - Basic auth username for webhook
-- `WEBHOOK_PASS` - Basic auth password for webhook
-- `LISTEN_ADDR` - SMTP server listen address (default: "0.0.0.0:25")
-- `LISTEN_ADDR_TLS` - TLS server listen address (default: "0.0.0.0:587")
-- `SERVER_NAME` - SMTP server name (default: "mx.inboundparse.com")
-
-#### TLS Configuration
-- `CERT_FILE` - TLS certificate file path
-- `KEY_FILE` - TLS private key file path
-
-#### Feature Toggles
-- `ENABLE_SPF` - Enable SPF validation (default: true)
-- `ENABLE_DKIM` - Enable DKIM validation (default: true)
-- `ENABLE_DMARC` - Enable DMARC validation (default: true)
-- `VERBOSE` - Enable verbose logging (default: false)
-
-#### Logging Configuration
-- `LOG_LEVEL` - Log level (debug, info, warn, error) (default: "info")
-- `LOG_FORMAT` - Log format (json, console) (default: "json")
-- `LOG_OUTPUT` - Log output destination (default: "stdout")
-
-#### Metrics Configuration
-- `ENABLE_METRICS` - Enable Prometheus metrics collection (default: false)
-- `METRICS_ADDR` - Metrics server listen address (default: "0.0.0.0:9090")
-- `METRICS_API_KEY` - Metrics API key
-- `METRICS_USERNAME` - Metrics username
-- `METRICS_PASSWORD` - Metrics password
-
-#### Sentry Configuration
-- `ENABLE_SENTRY` - Enable Sentry error tracking (default: false)
-- `SENTRY_DSN` - Sentry DSN for error tracking
-- `SENTRY_ENV` - Sentry environment (default: "production")
-- `SENTRY_RELEASE` - Sentry release version
-
-#### Automatic Certificate Management
-- `ACME_SH_EMAIL` - Email for Let's Encrypt account registration
-- `MXDOMAIN` - Domain for SSL certificate (default: "mx.inboundparse.com")
-- `DNS_API` - DNS API provider (default: "dns_cf")
-- `CF_Token` - Cloudflare API token (required for dns_cf)
-- `CF_Zone_ID` - Cloudflare Zone ID (required for dns_cf)
+#### Core Environment Variables
 
+- `WEBHOOK_URL`           Webhook URL to receive email payloads (**required**)
+- `WEBHOOK_USER`          Basic auth username for the webhook (optional)
+- `WEBHOOK_PASS`          Basic auth password for the webhook (optional)
+
+#### Webhook Reliability Configuration
+
+- `WEBHOOK_MAX_RETRIES`      Maximum retry attempts (default: `3`)
+- `WEBHOOK_RETRY_DELAY`      Initial retry delay in seconds (default: `1`)
+- `WEBHOOK_MAX_RETRY_DELAY`  Maximum retry delay in seconds (default: `30`)
+- `WEBHOOK_RETRY_MULTIPLIER` Exponential backoff multiplier (default: `2.0`)
+- `WEBHOOK_RATE_LIMIT`       Requests per second rate limit (default: `10`)
+- `WEBHOOK_RATE_BURST`       Rate limit burst capacity (default: `20`)
+- `LISTEN_ADDR`           SMTP listen address (default: `0.0.0.0:25`)
+- `LISTEN_ADDR_TLS`       TLS listen address (default: `0.0.0.0:587`)
+- `SERVER_NAME`           SMTP service name for banner (default: `mx.inboundparse.com`)
+
+#### TLS Settings
+
+- `CERT_FILE`             Path to TLS certificate file (optional)
+- `KEY_FILE`              Path to TLS private key file (optional)
+
+#### Feature Flags
+
+- `ENABLE_SPF`            Enable SPF checking (`true`/`false`, default: `true`)
+- `ENABLE_DKIM`           Enable DKIM checking (`true`/`false`, default: `true`)
+- `ENABLE_DMARC`          Enable DMARC checking (`true`/`false`, default: `true`)
+- `VERBOSE`               Enable verbose (debug) logging (`true`/`false`, default: `false`)
+
+#### Metrics (Prometheus)
+
+- `ENABLE_METRICS`        Enable Prometheus metrics endpoint (`true`/`false`, default: `false`)
+- `METRICS_ADDR`          Metrics endpoint listen address (default: `0.0.0.0:9090`)
+- `METRICS_API_KEY`       Bearer token used for metrics endpoint authentication (optional)
+- `METRICS_USERNAME`      Username for metrics endpoint basic auth (optional)
+- `METRICS_PASSWORD`      Password for metrics endpoint basic auth (optional)
+
+#### Sentry Error Tracking
+
+- `ENABLE_SENTRY`         Enable Sentry error tracking (`true`/`false`, default: `false`)
+- `SENTRY_DSN`            Sentry DSN (project key, required if Sentry enabled)
+- `SENTRY_ENV`            Sentry environment name (default: `production`)
+- `SENTRY_RELEASE`        Sentry release version (optional)
 
 ## Webhook Payload
 
@@ -240,7 +249,7 @@ The service sends a JSON payload to your webhook with comprehensive email data:
 
 ## 🤝 Contributing
 
-Contributions of all kinds are welcome! See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for guidelines, and don’t hesitate to open issues, fork, or create PRs.
+Contributions of all kinds are welcome! See [CONTRIBUTE.md](./docs/CONTRIBUTE.md) for guidelines, and don’t hesitate to open issues, fork, or create PRs.
 
 ---
 

docs/CONTRIBUTE.md

@@ -34,7 +34,7 @@ We appreciate all kinds of contributions:
 
 ### 2. Set Up Your Environment
 
-- **Ensure you have Go >= 1.20 installed.**
+- **Ensure you have Go >= 1.24 installed.**
 - Install dependencies:
   ```bash
   make deps
@@ -44,6 +44,12 @@ We appreciate all kinds of contributions:
   make build
   ```
 
+**Key Dependencies:**
+- `github.com/failsafe-go/failsafe-go` - Webhook resilience patterns (retry, rate limiting, circuit breaker)
+- `github.com/rs/zerolog` - High-performance structured logging
+- `github.com/getsentry/sentry-go` - Error tracking and performance monitoring
+- `github.com/prometheus/client_golang` - Metrics collection
+
 ### 3. Run Tests
 
 - To run all tests:
@@ -62,14 +68,18 @@ We appreciate all kinds of contributions:
 - **Keep your branch up to date**:  
   Rebase or merge `upstream/main` regularly to minimize conflicts.
 
-- **Follow Go formatting**:  
-  Run `go fmt ./...` and `go vet ./...` before submitting.
+- **Format your code**:  
+  ```bash
+  make format
+  ```
 
 - **Lint your code**:  
   ```bash
   make lint
   ```
 
+_We also have `make fl` which does both._
+
 - **Include tests**:  
   Add or update tests for new features and bug fixes.
 
@@ -91,7 +101,7 @@ We appreciate all kinds of contributions:
 
 ## 📝 Code Style & Guidelines
 
-- Write clean, idiomatic Go (see `make lint`).
+- Write clean, idiomatic Go (see `make fl`).
 - Prefer clarity over cleverness.
 - Use descriptive variable and function names.
 - Keep functions short and focused.
@@ -106,13 +116,22 @@ We appreciate all kinds of contributions:
 | ------------------- | ------------------------------ |
 | `make deps`         | Install dependencies            |
 | `make build`        | Build binaries                  |
-| `make run`          | Run server (prod config)        |
 | `make run-dev`      | Run with development settings   |
-| `make lint`         | Run linter                      |
 | `make test`         | Run tests                       |
-| `make test-coverage`| Run tests with coverage report  |
+| `make coverage`     | Run tests with coverage report  |
+| `make format`       | Format code                     |
+| `make lint`         | Run linter and vulnerability scan |
+| `make vet`          | Vet the code                    |
+| `make fl`           | Format, lint, and vet code      |
+| `make check`        | Run deps, linters, and vulncheck |
+| `make clean`        | Clean build artifacts           |
 | `make up`           | Start dev stack (Docker)        |
 | `make down`         | Stop dev stack                  |
+| `make dev`          | Restart dev stack               |
+| `make status`       | Show service status             |
+| `make verify-deps`  | Verify dependency status        |
+| `make docker-build` | Build Docker image              |
+| `make ci`           | Run CI workflow                 |
 
 
 ---

docs/OBSERVABILITY.md

@@ -111,7 +111,99 @@ CaptureError(err, map[string]interface{}{
 - **Message processing errors**: Parse failures, read errors
 - **Server errors**: TLS certificate issues, startup failures
 
-## 3. Prometheus Metrics
+## 3. Webhook Reliability
+
+### Implementation
+
+- **Library**: failsafe-go (resilience patterns for Go)
+- **Features**:
+  - Automatic retry with exponential backoff
+  - Rate limiting with token bucket algorithm
+  - Circuit breaker pattern for fault tolerance
+  - Configurable retry and rate limit policies
+
+### Retry Logic
+
+Webhook requests automatically retry on failure with exponential backoff:
+
+- **Max Retries**: Configurable maximum retry attempts (default: 3)
+- **Initial Delay**: Starting delay between retries (default: 1 second)
+- **Max Delay**: Maximum delay cap (default: 30 seconds)
+- **Multiplier**: Exponential backoff multiplier (default: 2.0)
+
+Example retry sequence with defaults:
+- Attempt 1: Immediate
+- Attempt 2: 1 second delay
+- Attempt 3: 2 second delay
+- Attempt 4: 4 second delay
+
+### Rate Limiting
+
+Smooth rate limiting using token bucket algorithm:
+
+- **Rate Limit**: Requests per second (default: 10)
+- **Burst Capacity**: Burst allowance (default: 20)
+- **Algorithm**: Token bucket for smooth rate limiting
+
+### Circuit Breaker
+
+Automatic service degradation to prevent cascading failures:
+
+- **Failure Threshold**: 5 consecutive failures trigger circuit open
+- **Success Threshold**: 3 consecutive successes reset circuit
+- **States**: Closed (normal), Open (failing), Half-Open (testing)
+
+### Configuration
+
+```bash
+# Retry configuration
+WEBHOOK_MAX_RETRIES=5
+WEBHOOK_RETRY_DELAY=2
+WEBHOOK_MAX_RETRY_DELAY=60
+WEBHOOK_RETRY_MULTIPLIER=1.5
+
+# Rate limiting
+WEBHOOK_RATE_LIMIT=20
+WEBHOOK_RATE_BURST=50
+```
+
+Or via flags:
+
+```bash
+./inboundparse \
+  -webhook-max-retries=5 \
+  -webhook-retry-delay=2 \
+  -webhook-max-retry-delay=60 \
+  -webhook-retry-multiplier=1.5 \
+  -webhook-rate-limit=20 \
+  -webhook-rate-burst=50
+```
+
+### Use Cases
+
+**High Volume Processing:**
+```bash
+WEBHOOK_RATE_LIMIT=100
+WEBHOOK_RATE_BURST=200
+WEBHOOK_MAX_RETRIES=5
+```
+
+**Sensitive Downstream Services:**
+```bash
+WEBHOOK_RATE_LIMIT=5
+WEBHOOK_RATE_BURST=10
+WEBHOOK_MAX_RETRIES=10
+WEBHOOK_RETRY_DELAY=5
+```
+
+**Fast Recovery:**
+```bash
+WEBHOOK_MAX_RETRIES=3
+WEBHOOK_RETRY_DELAY=1
+WEBHOOK_RETRY_MULTIPLIER=1.2
+```
+
+## 4. Prometheus Metrics
 
 ### Implementation