From a20ff22976a9e234c12dbb94407a9b14d0a64650 Mon Sep 17 00:00:00 2001 From: mayor Date: Wed, 4 Mar 2026 12:52:15 -0800 Subject: [PATCH 1/5] docs: sync edge server documentation with latest features Updated edge-server/README.md to reflect new features from edge_server source: - Added documentation for new HTTP API endpoints: - POST /execute for DQL query execution - POST /attachments/upload and GET /attachments/{id} - GET /presence for presence graph viewing - GET /logs for log download - GET /docs for API documentation - Added Advanced Security Features section covering: - HTTPS/TLS 1.2 and 1.3 support - API key authentication - Permission-based access control - Audit logging - HTTP request throttling - Configurable connection limits and timeouts Synced from edge_server CHANGELOG unreleased features. Co-Authored-By: Claude Sonnet 4.5 --- edge-server/README.md | 51 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/edge-server/README.md b/edge-server/README.md index bc84d0372..889bf85a4 100644 --- a/edge-server/README.md +++ b/edge-server/README.md @@ -112,6 +112,44 @@ 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/my_server/execute \ + -H "Content-Type: application/json" \ + -d '{"query": "SELECT * FROM tasks"}' +``` + +### Attachments + +```bash +# Upload an attachment +curl -X POST http://localhost:8080/my_server/attachments/upload \ + -F "file=@/path/to/file" + +# Download an attachment +curl http://localhost:8080/my_server/attachments/{attachment-id} \ + -o downloaded-file +``` + +### Monitoring & Diagnostics + +```bash +# View presence graph +curl http://localhost:8080/my_server/presence + +# Download logs (returns .tar.gz) +curl http://localhost:8080/my_server/logs -o edge-server-logs.tar.gz + +# View API documentation +curl http://localhost:8080/my_server/docs +``` + ## Configuration The Edge Server uses `quickstart_config.yaml` for configuration. Key settings include: @@ -125,6 +163,19 @@ The Edge Server uses `quickstart_config.yaml` for configuration. Key settings in ⚠️ **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 From 1dd20d28344368bbb4ddcdedacca8149b5762a95 Mon Sep 17 00:00:00 2001 From: mayor Date: Wed, 4 Mar 2026 13:23:46 -0800 Subject: [PATCH 2/5] docs: Add OpenAPI spec and config schema documentation Add comprehensive documentation for: - OpenAPI specification access (runtime and offline generation) - Configuration schema generation for IDE autocomplete - Usage examples with common tools (Swagger UI, Postman, etc.) Co-Authored-By: Claude Sonnet 4.5 --- edge-server/README.md | 47 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/edge-server/README.md b/edge-server/README.md index 889bf85a4..a0177439a 100644 --- a/edge-server/README.md +++ b/edge-server/README.md @@ -150,6 +150,33 @@ curl http://localhost:8080/my_server/logs -o edge-server-logs.tar.gz curl http://localhost:8080/my_server/docs ``` +## API Reference + +### OpenAPI Specification + +The Edge Server automatically generates an OpenAPI 3.1 specification that documents all available HTTP endpoints. You can access it in two ways: + +**Option 1: Runtime Access** +```bash +# View the OpenAPI spec while server is running +curl http://localhost:8080/my_server/docs/edge_server_api.json | jq . +``` + +**Option 2: Generate Offline** +```bash +# Generate the spec without starting the server +./edge-server config open-api --config quickstart_config.yaml + +# Save to a file +./edge-server config open-api --config quickstart_config.yaml --output openapi.json +``` + +The OpenAPI spec can be used with tools like: +- **Swagger UI** - Interactive API documentation +- **Postman** - Import the spec to auto-generate requests +- **openapi-generator** - Generate client SDKs in various languages +- **Redoc** - Generate static API documentation + ## Configuration The Edge Server uses `quickstart_config.yaml` for configuration. Key settings include: @@ -159,6 +186,26 @@ The Edge Server uses `quickstart_config.yaml` for configuration. Key settings in - **HTTP Server**: Listens on port 8080 with `/my_server` base path - **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. From 2ea7e4d5d6656c37a34453456e9cbcdf9196248c Mon Sep 17 00:00:00 2001 From: mayor Date: Wed, 4 Mar 2026 13:49:18 -0800 Subject: [PATCH 3/5] docs: Update OpenAPI documentation to reflect comprehensive spec The OpenAPI spec is now generated from real HTTP handlers, ensuring it stays in sync with actual API behavior. Updated docs to highlight: - Generated from real handlers (21+ schema definitions) - Complete error responses (401, 403, 413, 429, 431, 500) - All status codes with detailed schemas - Authentication requirements and formats - Enhanced use cases (contract testing, API gateways, SDKs) - CI/CD integration examples Co-Authored-By: Claude Sonnet 4.5 --- edge-server/README.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/edge-server/README.md b/edge-server/README.md index a0177439a..854cecf44 100644 --- a/edge-server/README.md +++ b/edge-server/README.md @@ -154,7 +154,15 @@ curl http://localhost:8080/my_server/docs ### OpenAPI Specification -The Edge Server automatically generates an OpenAPI 3.1 specification that documents all available HTTP endpoints. You can access it in two ways: +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 @@ -162,20 +170,25 @@ The Edge Server automatically generates an OpenAPI 3.1 specification that docume curl http://localhost:8080/my_server/docs/edge_server_api.json | jq . ``` -**Option 2: Generate Offline** +**Option 2: Generate Offline (Recommended for CI/CD)** ```bash -# Generate the spec without starting the server +# Generate the spec without starting the server (<100ms) ./edge-server config open-api --config quickstart_config.yaml -# Save to a file +# 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' ``` -The OpenAPI spec can be used with tools like: -- **Swagger UI** - Interactive API documentation -- **Postman** - Import the spec to auto-generate requests -- **openapi-generator** - Generate client SDKs in various languages -- **Redoc** - Generate static API documentation +**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 From 6b1a85e54982c8f260c4e3594e9afc1586c086b2 Mon Sep 17 00:00:00 2001 From: mayor Date: Thu, 5 Mar 2026 11:08:53 -0800 Subject: [PATCH 4/5] feat: update quickstart config to new Edge Server schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update Edge Server quickstart configuration to use the new flat schema structure instead of the deprecated resources wrapper. Changes: - Replace `resources:` wrapper with flat `database:` and `http_server:` structure - Update endpoint paths from `/my_server/execute` to `/execute` - Add required `tls_config`, `auth`, and `logging` sections - Remove deprecated `base_path` field - Remove deprecated `databases:` map structure The HTTP API request body still uses "statement" field (not "query") as this is the external API contract. Verified with full quickstart test workflow: ✅ Config validation passes ✅ Server starts successfully ✅ Create task works ✅ Get tasks works ✅ Update task works ✅ Delete task works Co-Authored-By: Claude Sonnet 4.5 --- edge-server/justfile | 8 ++-- edge-server/quickstart_config_sample.yaml | 45 +++++++++++++---------- 2 files changed, 29 insertions(+), 24 deletions(-) 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..fe2d94ff1 100644 --- a/edge-server/quickstart_config_sample.yaml +++ b/edge-server/quickstart_config_sample.yaml @@ -1,20 +1,25 @@ -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 + +auth: dev_mode + +logging: + ditto_sdk: warning + edge_server: + level: info + console_logs: std_out From 31ad7347bc13a93bb7084a0c712b9e6643f31f56 Mon Sep 17 00:00:00 2001 From: mayor Date: Fri, 6 Mar 2026 12:01:28 -0800 Subject: [PATCH 5/5] docs: update README HTTP API examples to match new schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all HTTP API endpoint examples to reflect the new Edge Server schema that removes the base_path field. Changes: - Remove `/my_server` prefix from all endpoint examples - Update execute endpoint: `/my_server/execute` → `/execute` - Update attachments: `/my_server/attachments/*` → `/attachments/*` - Update presence: `/my_server/presence` → `/presence` - Update logs: `/my_server/logs` → `/logs` - Update docs: `/my_server/docs` → `/docs` - Fix execute request body: `"query"` → `"statement"` (correct HTTP API field) - Update OpenAPI spec URL to `/docs/edge_server_api.json` - Remove mention of base_path in configuration description - Enable `serve_docs: true` in sample config so doc examples work All examples tested and verified working with new schema. Co-Authored-By: Claude Sonnet 4.5 --- edge-server/README.md | 22 +++++++++++----------- edge-server/quickstart_config_sample.yaml | 1 + 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/edge-server/README.md b/edge-server/README.md index 854cecf44..05368df23 100644 --- a/edge-server/README.md +++ b/edge-server/README.md @@ -120,20 +120,20 @@ The Edge Server provides additional endpoints for advanced operations: ```bash # Execute custom DQL statements -curl -X POST http://localhost:8080/my_server/execute \ +curl -X POST http://localhost:8080/execute \ -H "Content-Type: application/json" \ - -d '{"query": "SELECT * FROM tasks"}' + -d '{"statement": "SELECT * FROM tasks"}' ``` ### Attachments ```bash # Upload an attachment -curl -X POST http://localhost:8080/my_server/attachments/upload \ +curl -X POST http://localhost:8080/attachments/upload \ -F "file=@/path/to/file" # Download an attachment -curl http://localhost:8080/my_server/attachments/{attachment-id} \ +curl http://localhost:8080/attachments/{attachment-id} \ -o downloaded-file ``` @@ -141,13 +141,13 @@ curl http://localhost:8080/my_server/attachments/{attachment-id} \ ```bash # View presence graph -curl http://localhost:8080/my_server/presence +curl http://localhost:8080/presence # Download logs (returns .tar.gz) -curl http://localhost:8080/my_server/logs -o edge-server-logs.tar.gz +curl http://localhost:8080/logs -o edge-server-logs.tar.gz -# View API documentation -curl http://localhost:8080/my_server/docs +# View API documentation (interactive Swagger UI) +open http://localhost:8080/docs ``` ## API Reference @@ -166,8 +166,8 @@ The Edge Server automatically generates a **comprehensive OpenAPI 3.1 specificat **Option 1: Runtime Access** ```bash -# View the OpenAPI spec while server is running -curl http://localhost:8080/my_server/docs/edge_server_api.json | jq . +# 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)** @@ -196,7 +196,7 @@ The Edge Server uses `quickstart_config.yaml` for configuration. Key settings in - **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 diff --git a/edge-server/quickstart_config_sample.yaml b/edge-server/quickstart_config_sample.yaml index fe2d94ff1..9fd0af23c 100644 --- a/edge-server/quickstart_config_sample.yaml +++ b/edge-server/quickstart_config_sample.yaml @@ -15,6 +15,7 @@ http_server: tls_config: dev_mode http_api: true enable_healthcheck: true + serve_docs: true auth: dev_mode