diff --git a/edge-server/README.md b/edge-server/README.md index bc84d0372..05368df23 100644 --- a/edge-server/README.md +++ b/edge-server/README.md @@ -112,19 +112,130 @@ just update-task false just delete-task ``` +## Additional HTTP API Endpoints + +The Edge Server provides additional endpoints for advanced operations: + +### Execute DQL Queries + +```bash +# Execute custom DQL statements +curl -X POST http://localhost:8080/execute \ + -H "Content-Type: application/json" \ + -d '{"statement": "SELECT * FROM tasks"}' +``` + +### Attachments + +```bash +# Upload an attachment +curl -X POST http://localhost:8080/attachments/upload \ + -F "file=@/path/to/file" + +# Download an attachment +curl http://localhost:8080/attachments/{attachment-id} \ + -o downloaded-file +``` + +### Monitoring & Diagnostics + +```bash +# View presence graph +curl http://localhost:8080/presence + +# Download logs (returns .tar.gz) +curl http://localhost:8080/logs -o edge-server-logs.tar.gz + +# View API documentation (interactive Swagger UI) +open http://localhost:8080/docs +``` + +## API Reference + +### OpenAPI Specification + +The Edge Server automatically generates a **comprehensive OpenAPI 3.1 specification** that documents all HTTP endpoints with complete request/response schemas, authentication, and error handling. The spec is generated directly from the actual HTTP handlers, ensuring it stays in sync with the server's behavior. + +**What's included in the spec:** +- Complete request and response schemas for all endpoints +- All HTTP status codes (200, 401, 403, 413, 429, 431, 500, etc.) +- Authentication requirements (Bearer token format) +- Error response formats with detailed descriptions +- Type-safe schemas for all data structures (21+ schema definitions) +- Request/response examples + +**Option 1: Runtime Access** +```bash +# View the OpenAPI spec while server is running (requires serve_docs: true in config) +curl http://localhost:8080/docs/edge_server_api.json | jq . +``` + +**Option 2: Generate Offline (Recommended for CI/CD)** +```bash +# Generate the spec without starting the server (<100ms) +./edge-server config open-api --config quickstart_config.yaml + +# Save to a file for use with external tools +./edge-server config open-api --config quickstart_config.yaml --output openapi.json + +# Pipe to tools for analysis +./edge-server config open-api --config quickstart_config.yaml | jq '.paths | keys' +``` + +**Use cases for the OpenAPI spec:** +- **Swagger UI / ReDoc** - Interactive API documentation with try-it-out features +- **Postman / Insomnia** - Import spec to auto-generate HTTP request collections +- **openapi-generator** - Generate type-safe client SDKs (TypeScript, Python, Go, Rust, etc.) +- **Contract testing** - Validate API responses match the spec (Pact, Dredd) +- **API Gateway integration** - Import into Kong, AWS API Gateway, or similar +- **Documentation sites** - Generate static docs with complete API reference + ## Configuration The Edge Server uses `quickstart_config.yaml` for configuration. Key settings include: - **Ditto Database**: Configured with app ID and device name - **Authentication**: Uses playground provider (development only) -- **HTTP Server**: Listens on port 8080 with `/my_server` base path +- **HTTP Server**: Listens on port 8080 with REST API and healthcheck endpoints - **Subscription**: Monitors all tasks in the database +### Configuration Schema + +You can view the full configuration schema to understand all available options: + +```bash +# View schema in JSON format +./edge-server config schema json + +# View schema in YAML format +./edge-server config schema yaml + +# Save to a file for IDE autocomplete +./edge-server config schema json > edge-server-config-schema.json +``` + +**Tip**: Many IDEs support YAML schema validation. Add this comment at the top of your config file: +```yaml +# yaml-language-server: $schema=./edge-server-config-schema.json +``` + ### Important Security Note ⚠️ **Development Only**: This quickstart uses playground authentication which is **NOT** secure or suitable for production. For production deployments, configure proper authentication using "Online with Authentication" identity. +### Advanced Security Features + +For production deployments, Edge Server supports: + +- **HTTPS/TLS**: TLS 1.2 and TLS 1.3 support for encrypted communications +- **API Key Authentication**: Generate and manage API keys for client authentication +- **Permission-Based Access Control**: Configure operation-based permissions for fine-grained access control +- **Audit Logging**: Track and retrieve access logs for security compliance +- **HTTP Request Throttling**: Configure rate limiting on a per-endpoint basis +- **Configurable Limits**: Set TCP connection limits, backlog limits, request timeouts, and keepalive settings + +See the [Edge Server documentation](https://docs.ditto.live/edge-server) for configuration details. + ## Troubleshooting ### Server won't start diff --git a/edge-server/justfile b/edge-server/justfile index 687b6c892..0c2bea761 100644 --- a/edge-server/justfile +++ b/edge-server/justfile @@ -32,7 +32,7 @@ create-task *title: --header "Content-Type: application/json" \ --data @- \ --fail-with-body \ - http://127.0.0.1:8080/my_server/execute \ + http://127.0.0.1:8080/execute \ | jq . # Gets all non-deleted tasks @@ -42,7 +42,7 @@ get-tasks: --header "Content-Type: application/json" \ --data @requests/get.json \ --fail-with-body \ - http://127.0.0.1:8080/my_server/execute \ + http://127.0.0.1:8080/execute \ | jq . # Updates a task's completion status @@ -54,7 +54,7 @@ update-task id done="false": --request POST \ --header "Content-Type: application/json" \ --data @- \ - http://127.0.0.1:8080/my_server/execute \ + http://127.0.0.1:8080/execute \ | jq . # Soft deletes a task @@ -65,7 +65,7 @@ delete-task id: --request POST \ --header "Content-Type: application/json" \ --data @- \ - http://127.0.0.1:8080/my_server/execute \ + http://127.0.0.1:8080/execute \ | jq . alias download-bin := z-download-binary diff --git a/edge-server/quickstart_config_sample.yaml b/edge-server/quickstart_config_sample.yaml index 080ef379c..9fd0af23c 100644 --- a/edge-server/quickstart_config_sample.yaml +++ b/edge-server/quickstart_config_sample.yaml @@ -1,20 +1,26 @@ -resources: - my_ditto_db: - resource_type: DittoDatabase - db_id: "YOUR_DB_ID_HERE" - device_name: "your-device-name" - subscriptions: - - "SELECT * FROM tasks" - auth: - server: - access_token: "YOUR_ACCESS_TOKEN" - auth_url: "https://YOUR-AUTH-URL.cloud.dittolive.app" - provider: "__playgroundProvider" - my_http_server: - resource_type: HttpServer - listen_addr: "0.0.0.0:8080" - databases: - my_db: - db_id: "YOUR_DB_ID_HERE" - base_path: my_server - http_api: true +database: + db_id: "YOUR_DB_ID_HERE" + device_name: "your-device-name" + subscriptions: + - "SELECT * FROM tasks" + auth: + server: + access_token: "YOUR_ACCESS_TOKEN" + auth_url: "https://YOUR-AUTH-URL.cloud.dittolive.app" + provider: "__playgroundProvider" + enable_cloud_sync: false + +http_server: + listen_addr: "0.0.0.0:8080" + tls_config: dev_mode + http_api: true + enable_healthcheck: true + serve_docs: true + +auth: dev_mode + +logging: + ditto_sdk: warning + edge_server: + level: info + console_logs: std_out