feat(api): support optional systemInfo in submissions

Extend the submission contract to accept a `systemInfo` object and persist it with each submission, including deep-copy support for `extra` metadata. Also update client-facing docs and HTTP examples (JSON and multipart) and document that the schema is available at `GET /api/schema`, so clients can reliably implement the updated payload format.feat(api): support optional systemInfo in submissions Extend the submission contract to accept a `systemInfo` object and persist it with each submission, including deep-copy support for `extra` metadata. Also update client-facing docs and HTTP examples (JSON and multipart) and document that the schema is available at `GET /api/schema`, so clients can reliably implement the updated payload format.
2026-04-17 13:57:55 +03:00
parent d2be2276ec
commit 03b4b55927
8 changed files with 630 additions and 23 deletions
--- a/docs/submit-api.md
+++ b/docs/submit-api.md
@@ -0,0 +1,117 @@
+# Submission API
+
+Use `POST /api/submit` to send benchmark results to the server.
+
+## Endpoint
+
+- Method: `POST`
+- URL: `/api/submit`
+- Content-Types:
+  - `application/json`
+  - `multipart/form-data`
+
+## Schema
+
+- Import URL: `/api/schema`
+- Source file in repo: `docs/submit-schema.json`
+
+## JSON format
+
+Clients can send either:
+
+1. An envelope with `submitter`, `platform`, optional `systemInfo`, and nested `benchmark`
+2. A flat benchmark payload with optional `submitter`, `platform`, and optional `systemInfo`
+
+Example envelope:
+
+```json
+{
+  "submitter": "AMD Bazzite",
+  "platform": "linux",
+  "systemInfo": {
+    "hostname": "bench-rig-01",
+    "osName": "Bazzite",
+    "osVersion": "41",
+    "distro": "Fedora Atomic",
+    "kernelVersion": "6.14.2-300.fc41.x86_64",
+    "kernelArch": "x86_64",
+    "architecture": "amd64",
+    "locale": "en-US",
+    "timezone": "Europe/Bucharest",
+    "country": "Romania",
+    "city": "Bucharest",
+    "clientVersion": "1.4.0",
+    "appVersion": "desktop-1.4.0",
+    "sessionID": "session-123",
+    "userID": "anonymous-user",
+    "extra": {
+      "gpuDriver": "Mesa 25.0.3",
+      "desktopEnvironment": "KDE Plasma"
+    }
+  },
+  "benchmark": {
+    "config": {
+      "durationSecs": 10,
+      "intensity": 1,
+      "coreFilter": 0,
+      "multiCore": true
+    },
+    "cpuInfo": {
+      "brandString": "AMD Ryzen 9 9950X3D 16-Core Processor",
+      "vendorID": "AuthenticAMD",
+      "physicalCores": 16,
+      "logicalCores": 32,
+      "baseClockMHz": 5756,
+      "boostClockMHz": 0,
+      "l1DataKB": 48,
+      "l2KB": 1024,
+      "l3MB": 32,
+      "isHybrid": false,
+      "has3DVCache": true,
+      "supportedFeatures": ["SSE4.2", "AVX", "AVX2"]
+    },
+    "startedAt": "2026-04-17T13:20:09.170770511+03:00",
+    "duration": 10003356676,
+    "totalOps": 543678267392,
+    "mOpsPerSec": 54349.58334499758,
+    "score": 5434958,
+    "coreResults": [
+      {
+        "logicalID": 0,
+        "coreType": "Standard",
+        "mOpsPerSec": 1642.986525056302,
+        "totalOps": 16435380224
+      }
+    ]
+  }
+}
+```
+
+## Multipart format
+
+Multipart requests may include:
+
+- `submitter`: text field
+- `platform`: text field
+- `systemInfo`: JSON text field
+- `benchmark`, `file`, or `benchmarkFile`: benchmark JSON file field
+
+Example `systemInfo` field value:
+
+```json
+{
+  "osName": "Windows",
+  "osVersion": "11 24H2",
+  "kernelVersion": "10.0.26100",
+  "architecture": "amd64",
+  "locale": "en-US",
+  "timezone": "America/New_York"
+}
+```
+
+## Notes
+
+- `systemInfo` is optional. Older clients do not need to send it.
+- The server may enrich stored analytics with request metadata such as `ipAddress`, `forwardedFor`, `userAgent`, and `locale`.
+- `baseClockMHz` and related CPU clock fields currently expect integer MHz values.
+- Full JSON Schema is available in [submit-schema.json](./submit-schema.json) and is served by `GET /api/schema`.