dandri/beacon-server
1
0 Fork 0
mirror of https://github.com/MeshCore-Beacon/beacon-server.git synced 2026-10-23 03:01:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document route cursorId and activity coverage fields

Browse Source
This commit is contained in:
MrAlders0n authored and MrAlders0n committed 2026-10-02 19:03:46 -04:00
1 parent ff8758b932
commit af20bebfe5
5 files changed
+155 -15
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+4 -2
View File
@@ -622,7 +622,7 @@ List `limit` values are clamped to 1–200.
| `GET` | `/packets/{packetHash}` | Get packet with all observations |
| `GET` | `/regions` | List all regions (summary) |
| `GET` | `/regions/{regionId}` | Get a single region with IATA list |
| `GET` | `/routes` | List known routes (`iata`, `hopCount`) |
| `GET` | `/routes` | List known routes (`iata`, `hopCount`, `cursor`+`cursorId`) |
| `GET` | `/routes/search` | Search routes by source and destination hash |
| `GET` | `/routes/cross` | Search for routes crossing IATA boundaries |
| `GET` | `/routes/{iata}/{pathKey}/observations` | Retained observations matching a saved route (see below) |
@@ -696,7 +696,9 @@ The existing observer `observationCount` remains a legacy cumulative presence
counter for compatibility, including status/neighbour events. It is not a
period packet total. Broker presence and packet-arrival timestamps are now
updated separately; this cannot reconstruct previously overwritten timestamps.
Hourly activity comes from the analytics rollups and includes unknown-type activity.
Hourly activity comes from the analytics rollups, plus raw rows for hours not yet rolled
(at most 24h back), and includes unknown-type activity. `rolledUntil` is the end of the newest
complete rollup hour and `rawFrom` the start of the raw tail; hours between them are uncovered.
### Saved-route evidence
docs/docs.go
+54 -4
View File
@@ -692,6 +692,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -799,8 +805,8 @@ const docTemplate = `{
}
}
},
"404": {
"description": "Not Found",
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
@@ -838,6 +844,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -875,6 +887,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1204,6 +1222,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1442,6 +1466,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1905,8 +1935,8 @@ const docTemplate = `{
}
}
},
"404": {
"description": "Not Found",
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
@@ -1950,6 +1980,12 @@ const docTemplate = `{
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1982,6 +2018,12 @@ const docTemplate = `{
"name": "cursor",
"in": "query"
},
{
"type": "integer",
"description": "id of the last item; with cursor, also returns later routes sharing that millisecond",
"name": "cursorId",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
@@ -4221,6 +4263,14 @@ const docTemplate = `{
"range": {
"type": "string"
},
"rawFrom": {
"description": "start of the raw tail, epoch ms",
"type": "integer"
},
"rolledUntil": {
"description": "Hourly only. Buckets before rolledUntil come from rollups and from rawFrom on from raw rows;\nwhen rawFrom is later, the hours between are uncovered, not quiet.",
"type": "integer"
},
"source": {
"description": "raw or hourly; missing records do not prove an outage",
"type": "string"
docs/historical-stats.md
+2 -1
View File
@@ -69,7 +69,8 @@ region or all IATAs.
- Packet, trace and route detail, the packet list, observer comparison, and observer
activity below one hour. Hourly observer activity reads raw rows for the hours after the
newest complete one (at most the last 3 hours), so the unrolled tail isn't shown as zero.
newest complete one (at most the last 24 hours, the raw holdback), so the unrolled tail isn't
shown as zero. `rolledUntil` and `rawFrom` in the response mark any hours still uncovered.
- Current memberships: scope observer and node counts, node types, clock drift, radio presets.
- `/traces` reads `trace_tags`, a per-tag summary kept at ingest, not a rollup. A new packet
adds its count, type and payload in the statement that stores it; hearings set the times.
docs/swagger.json
+54 -4
View File
@@ -690,6 +690,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -797,8 +803,8 @@
}
}
},
"404": {
"description": "Not Found",
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
@@ -836,6 +842,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -873,6 +885,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1202,6 +1220,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1440,6 +1464,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1903,8 +1933,8 @@
}
}
},
"404": {
"description": "Not Found",
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
@@ -1948,6 +1978,12 @@
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
@@ -1980,6 +2016,12 @@
"name": "cursor",
"in": "query"
},
{
"type": "integer",
"description": "id of the last item; with cursor, also returns later routes sharing that millisecond",
"name": "cursorId",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
@@ -4219,6 +4261,14 @@
"range": {
"type": "string"
},
"rawFrom": {
"description": "start of the raw tail, epoch ms",
"type": "integer"
},
"rolledUntil": {
"description": "Hourly only. Buckets before rolledUntil come from rollups and from rawFrom on from raw rows;\nwhen rawFrom is later, the hours between are uncovered, not quiet.",
"type": "integer"
},
"source": {
"description": "raw or hourly; missing records do not prove an outage",
"type": "string"
docs/swagger.yaml
+41 -4
View File
@@ -590,6 +590,14 @@ definitions:
$ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityRadio'
range:
type: string
rawFrom:
description: start of the raw tail, epoch ms
type: integer
rolledUntil:
description: |-
Hourly only. Buckets before rolledUntil come from rollups and from rawFrom on from raw rows;
when rawFrom is later, the hours between are uncovered, not quiet.
type: integer
source:
description: raw or hourly; missing records do not prove an outage
type: string
@@ -2083,6 +2091,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get channel detail
tags:
- Channels
@@ -2155,8 +2167,8 @@ paths:
items:
$ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA'
type: array
"404":
description: Not Found
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: List all IATA codes
@@ -2181,6 +2193,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get a single IATA code
tags:
- IATAs
@@ -2205,6 +2221,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get an IATA's GeoJSON border, if configured
tags:
- IATAs
@@ -2428,6 +2448,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get node detail
tags:
- Nodes
@@ -2587,6 +2611,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get observer detail
tags:
- Observers
@@ -2904,8 +2932,8 @@ paths:
items:
$ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary'
type: array
"404":
description: Not Found
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: List all regions
@@ -2934,6 +2962,10 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/internal_api_handlers.APIError'
summary: Get a single region
tags:
- Regions
@@ -2952,6 +2984,11 @@ paths:
in: query
name: cursor
type: integer
- description: id of the last item; with cursor, also returns later routes sharing
that millisecond
in: query
name: cursorId
type: integer
- description: Max results (default 50); must be positive, values above 200
are clamped
in: query