feat(api): support optional systemInfo in submissions
All checks were successful
Build and Publish Docker Image / deploy (push) Successful in 1m17s
All checks were successful
Build and Publish Docker Image / deploy (push) Successful in 1m17s
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.
This commit is contained in:
117
docs/submit-api.md
Normal file
117
docs/submit-api.md
Normal file
@@ -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`.
|
||||
306
docs/submit-schema.json
Normal file
306
docs/submit-schema.json
Normal file
@@ -0,0 +1,306 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://cpu-benchmarker.local/schemas/submit-schema.json",
|
||||
"title": "CPU Benchmark Submission",
|
||||
"description": "Request body for POST /api/submit. Older clients may omit systemInfo.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"submitter": {
|
||||
"type": "string",
|
||||
"description": "Human-readable device or user label."
|
||||
},
|
||||
"platform": {
|
||||
"type": "string",
|
||||
"enum": ["windows", "linux", "macos"],
|
||||
"description": "Normalized platform value."
|
||||
},
|
||||
"systemInfo": {
|
||||
"$ref": "#/$defs/systemInfo"
|
||||
},
|
||||
"benchmark": {
|
||||
"$ref": "#/$defs/benchmarkResult"
|
||||
},
|
||||
"result": {
|
||||
"$ref": "#/$defs/benchmarkResult"
|
||||
},
|
||||
"data": {
|
||||
"$ref": "#/$defs/benchmarkResult"
|
||||
},
|
||||
"config": {
|
||||
"$ref": "#/$defs/benchmarkConfig"
|
||||
},
|
||||
"cpuInfo": {
|
||||
"$ref": "#/$defs/cpuInfo"
|
||||
},
|
||||
"startedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"duration": {
|
||||
"type": "integer",
|
||||
"description": "Benchmark duration in nanoseconds."
|
||||
},
|
||||
"totalOps": {
|
||||
"type": "integer"
|
||||
},
|
||||
"mOpsPerSec": {
|
||||
"type": "number"
|
||||
},
|
||||
"score": {
|
||||
"type": "integer"
|
||||
},
|
||||
"coreResults": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/coreResult"
|
||||
}
|
||||
}
|
||||
},
|
||||
"anyOf": [
|
||||
{
|
||||
"required": ["benchmark"]
|
||||
},
|
||||
{
|
||||
"required": ["result"]
|
||||
},
|
||||
{
|
||||
"required": ["data"]
|
||||
},
|
||||
{
|
||||
"required": ["config", "cpuInfo", "startedAt", "duration", "totalOps", "mOpsPerSec", "score", "coreResults"]
|
||||
}
|
||||
],
|
||||
"$defs": {
|
||||
"benchmarkConfig": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"durationSecs": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"intensity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"coreFilter": {
|
||||
"type": "integer"
|
||||
},
|
||||
"multiCore": {
|
||||
"type": "boolean"
|
||||
}
|
||||
},
|
||||
"required": ["durationSecs", "intensity", "coreFilter", "multiCore"]
|
||||
},
|
||||
"cpuInfo": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"brandString": {
|
||||
"type": "string"
|
||||
},
|
||||
"vendorID": {
|
||||
"type": "string"
|
||||
},
|
||||
"physicalCores": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"logicalCores": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"baseClockMHz": {
|
||||
"type": "integer",
|
||||
"description": "Current server schema expects an integer MHz value."
|
||||
},
|
||||
"boostClockMHz": {
|
||||
"type": "integer"
|
||||
},
|
||||
"l1DataKB": {
|
||||
"type": "integer"
|
||||
},
|
||||
"l2KB": {
|
||||
"type": "integer"
|
||||
},
|
||||
"l3MB": {
|
||||
"type": "integer"
|
||||
},
|
||||
"isHybrid": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"has3DVCache": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"pCoreCount": {
|
||||
"type": "integer"
|
||||
},
|
||||
"eCoreCount": {
|
||||
"type": "integer"
|
||||
},
|
||||
"cores": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/cpuCoreDescriptor"
|
||||
}
|
||||
},
|
||||
"supportedFeatures": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["brandString", "physicalCores", "logicalCores"]
|
||||
},
|
||||
"cpuCoreDescriptor": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"LogicalID": {
|
||||
"type": "integer"
|
||||
},
|
||||
"PhysicalID": {
|
||||
"type": "integer"
|
||||
},
|
||||
"CoreID": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Type": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": ["LogicalID", "PhysicalID", "CoreID", "Type"]
|
||||
},
|
||||
"coreResult": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"logicalID": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"coreType": {
|
||||
"type": "string"
|
||||
},
|
||||
"mOpsPerSec": {
|
||||
"type": "number",
|
||||
"minimum": 0
|
||||
},
|
||||
"totalOps": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
}
|
||||
},
|
||||
"required": ["logicalID", "coreType", "mOpsPerSec", "totalOps"]
|
||||
},
|
||||
"benchmarkResult": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"config": {
|
||||
"$ref": "#/$defs/benchmarkConfig"
|
||||
},
|
||||
"cpuInfo": {
|
||||
"$ref": "#/$defs/cpuInfo"
|
||||
},
|
||||
"startedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"duration": {
|
||||
"type": "integer"
|
||||
},
|
||||
"totalOps": {
|
||||
"type": "integer"
|
||||
},
|
||||
"mOpsPerSec": {
|
||||
"type": "number"
|
||||
},
|
||||
"score": {
|
||||
"type": "integer"
|
||||
},
|
||||
"coreResults": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/coreResult"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["config", "cpuInfo", "startedAt", "duration", "totalOps", "mOpsPerSec", "score", "coreResults"]
|
||||
},
|
||||
"systemInfo": {
|
||||
"type": "object",
|
||||
"description": "Optional analytics and environment metadata. Clients may omit this entire object.",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"hostname": {
|
||||
"type": "string"
|
||||
},
|
||||
"osName": {
|
||||
"type": "string"
|
||||
},
|
||||
"osVersion": {
|
||||
"type": "string"
|
||||
},
|
||||
"distro": {
|
||||
"type": "string"
|
||||
},
|
||||
"kernelVersion": {
|
||||
"type": "string"
|
||||
},
|
||||
"kernelArch": {
|
||||
"type": "string"
|
||||
},
|
||||
"architecture": {
|
||||
"type": "string"
|
||||
},
|
||||
"locale": {
|
||||
"type": "string"
|
||||
},
|
||||
"timezone": {
|
||||
"type": "string"
|
||||
},
|
||||
"region": {
|
||||
"type": "string"
|
||||
},
|
||||
"country": {
|
||||
"type": "string"
|
||||
},
|
||||
"city": {
|
||||
"type": "string"
|
||||
},
|
||||
"isp": {
|
||||
"type": "string"
|
||||
},
|
||||
"sessionID": {
|
||||
"type": "string"
|
||||
},
|
||||
"userID": {
|
||||
"type": "string"
|
||||
},
|
||||
"clientVersion": {
|
||||
"type": "string"
|
||||
},
|
||||
"appVersion": {
|
||||
"type": "string"
|
||||
},
|
||||
"ipAddress": {
|
||||
"type": "string",
|
||||
"description": "May be supplied by the client, and may also be enriched by the server from the request."
|
||||
},
|
||||
"forwardedFor": {
|
||||
"type": "string"
|
||||
},
|
||||
"userAgent": {
|
||||
"type": "string"
|
||||
},
|
||||
"extra": {
|
||||
"type": "object",
|
||||
"description": "Free-form extension point for future analytics.",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user