177 lines
3.0 KiB
Markdown
177 lines
3.0 KiB
Markdown
# 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
|