init: Initial commit

.docs/usage.md

@@ -0,0 +1,176 @@
+# Usage
+
+## Running the Gateway
+
+### Local Development
+
+```bash
+cd app
+go run main.go
+```
+
+The gateway will start on the configured host and port (default: `0.0.0.0:8080`).
+
+### Docker
+
+```bash
+# Pull and run (builds locally if image not available)
+docker compose up -d
+
+# View logs
+docker compose logs -f gateway
+
+# Stop
+docker compose down
+```
+
+### Build from Source
+
+```bash
+cd app
+go build -o gateway main.go
+./gateway
+```
+
+## Health Check
+
+Check if the gateway is running:
+
+```bash
+curl http://localhost:8080/_/health
+```
+
+Response: `OK`
+
+## Making Requests
+
+After configuring routes in `gateway.yaml`, make requests to the gateway:
+
+```bash
+# Example: Request to a route configured at /api/v1/dev/*
+curl http://localhost:8080/api/v1/dev/users
+
+# With API key authentication
+curl -H "X-Api-Key: your-key-here" http://localhost:8080/api/v1/dev/data
+
+# With session authentication
+curl -H "Authorization: Bearer token" http://localhost:8080/api/v1/protected
+```
+
+## Route Examples
+
+### Strip Prefix Example
+
+**Configuration:**
+```yaml
+routes:
+  - id: "api"
+    path: "/api/v1/*"
+    strip_prefix:
+      enabled: true
+      prefix: "/api/v1"
+```
+
+**Request flow:**
+- Client requests: `/api/v1/users/123`
+- Gateway strips: `/api/v1`
+- Backend receives: `/users/123`
+
+### Authentication Example
+
+**Configuration:**
+```yaml
+security:
+  auth:
+    enabled: true
+    type: "api_key"
+    header: "X-Api-Key"
+```
+
+**Valid request:**
+```bash
+curl -H "X-Api-Key: secret123" http://localhost:8080/api/v1/data
+```
+
+**Invalid request (missing header):**
+```bash
+curl http://localhost:8080/api/v1/data
+# Returns: 401 Unauthorized
+```
+
+### WAF Method Filtering Example
+
+**Configuration:**
+```yaml
+security:
+  waf:
+    enabled: true
+    methods: ["GET", "POST"]
+```
+
+**Allowed:**
+```bash
+curl -X GET http://localhost:8080/api/v1/data
+curl -X POST http://localhost:8080/api/v1/data
+```
+
+**Blocked:**
+```bash
+curl -X DELETE http://localhost:8080/api/v1/data
+# Returns: 403 Forbidden
+```
+
+## Logging
+
+The gateway uses structured logging via `masterlog`. Logs include:
+
+- Request ID (if enabled)
+- Client IP (if real_ip enabled)
+- Request method and path
+- Response status
+
+**Example log output:**
+```json
+{
+  "level": "info",
+  "msg": "Registering route",
+  "path": "/api/v1/dev/*"
+}
+```
+
+## Troubleshooting
+
+### Gateway fails to start
+
+1. Check if port is already in use:
+```bash
+lsof -i :8080
+```
+
+2. Verify configuration file exists and is valid YAML
+
+3. Check logs for detailed error messages
+
+### 401 Unauthorized
+
+- Verify auth header is included
+- Check header name matches configuration
+- Verify path is not excluded from auth
+
+### 403 Forbidden
+
+- Check WAF method configuration
+- Verify HTTP method is allowed
+
+### Backend connection errors
+
+- Verify API target URL is correct
+- Check backend service is running
+- Verify network connectivity
+
+## Performance Considerations
+
+- The gateway uses Go's `httputil.ReverseProxy` for efficient proxying
+- Keep-alive connections are reused by default
+- Consider connection pooling for high-traffic scenarios
+- Monitor memory usage with high request volumes