From f4ba70623ec40a46b8c44fa5284c606596c68502 Mon Sep 17 00:00:00 2001 From: Jeppe B <2jepp9350@gmail.com> Date: Sat, 15 Aug 2026 21:19:37 +0200 Subject: [PATCH] feat(edge-broker): expose lastActivityAt on /api/health (AUT-2/TRU-6) (#373) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the `lastActivityAt` field to the response body of the `/api/health` endpoint exposed by the edge broker. The field reports the most recent successful request timestamp from the container, defaulting to the container's start time when no requests have been served yet. The field is also surfaced on `broker.state` (alongside a new `containerStartedAt`) so callers can observe the activity timestamp without performing an HTTP round-trip. The Writerside `API-Reference.topic` and its generator are updated to document the new field. Resolves TRU-6 (AUT-2). ## Example request ```sh curl -s http://edge-broker:8080/api/health ``` ```json { "ok": true, "service": "edge-broker", "auth_mode": "manager", "manager_url_configured": true, "shared_secret_configured": true, "agents_connected": 0, "lastActivityAt": "2026-08-15T19:15:34.898Z" } ``` ## Documentation The diff for the writerside topic that documents the new field lives in this PR — see [`documentation/topics/API-Reference.topic`](https://github.com/copenhagentruckwash/api/blob/10f28d6/documentation/topics/API-Reference.topic) (vs. [the previous version at `origin/develop`](https://github.com/copenhagentruckwash/api/blob/cdf8541/documentation/topics/API-Reference.topic)) in the [PR "Files changed" view](https://github.com/copenhagentruckwash/api/pull/373/files). The same paragraph is reproduced by `scripts/generate_writerside_openapi_docs.py` so future regenerations preserve it. **What consumers need to re-read.** `API-Reference.topic` adds a paragraph documenting the new `lastActivityAt` ISO 8601 timestamp on the edge broker's `/api/health` response. Consumers that previously inferred broker activity from indirect signals (e.g. comparing `agents_connected` across polls or assuming a fresh process meant a fresh state) should now read `lastActivityAt` directly: it is the timestamp of the most recent successful HTTP request handled by the broker container, and defaults to `containerStartedAt` until the first request lands. No request or response shape changes; the field is purely additive. ## Tests `node --test services/edge-broker/test/broker.test.mjs` covers both the shape of the new field on `/api/health` and the fact that `lastActivityAt` advances on every successful request after `containerStartedAt`. All 21 broker tests pass locally. --- _This PR description was generated by an OpenHands AI agent on behalf of jepp9350._ Co-authored-by: Jeppe Co-authored-by: openhands --- documentation/topics/API-Reference.topic | 1 + scripts/generate_writerside_openapi_docs.py | 4 +++ services/edge-broker/server.mjs | 8 +++++ services/edge-broker/test/broker.test.mjs | 39 +++++++++++++++++++++ 4 files changed, 52 insertions(+) diff --git a/documentation/topics/API-Reference.topic b/documentation/topics/API-Reference.topic index 031d8423..3c731b0b 100644 --- a/documentation/topics/API-Reference.topic +++ b/documentation/topics/API-Reference.topic @@ -7,4 +7,5 @@

Comprehensive API reference generated from the repository root openapi.yaml.

+

The edge broker's /api/health response additionally exposes a lastActivityAt field (ISO 8601 timestamp). It reports the most recent successful HTTP request handled by the broker container and defaults to the container's start time when no request has been processed yet.

diff --git a/scripts/generate_writerside_openapi_docs.py b/scripts/generate_writerside_openapi_docs.py index 01795bbf..3dbca438 100644 --- a/scripts/generate_writerside_openapi_docs.py +++ b/scripts/generate_writerside_openapi_docs.py @@ -405,6 +405,10 @@ def render_api_reference_topic() -> str: ' title="API Reference" id="API-Reference">\n' f"\n \n" "

Comprehensive API reference generated from the repository root openapi.yaml.

\n" + "

The edge broker's /api/health response additionally exposes a " + "lastActivityAt field (ISO 8601 timestamp). It reports the most recent " + "successful HTTP request handled by the broker container and defaults to the container's " + "start time when no request has been processed yet.

\n" "\n" ) diff --git a/services/edge-broker/server.mjs b/services/edge-broker/server.mjs index eb9a2712..25331dc3 100644 --- a/services/edge-broker/server.mjs +++ b/services/edge-broker/server.mjs @@ -189,6 +189,8 @@ export function createBrokerServer(options = {}) { const browserStreamSessions = new Map(); const gatewayStreamSessions = new Map(); const inflightGatewaySyncs = new Map(); + const containerStartedAt = currentTimestamp(); + let lastActivityAt = containerStartedAt; const managerRequest = async (path, body = {}, method = "POST") => { if (!managerUrl) { @@ -480,6 +482,7 @@ export function createBrokerServer(options = {}) { const server = http.createServer(async (req, res) => { try { const url = new URL(req.url, "http://localhost"); + lastActivityAt = currentTimestamp(); if (req.method === "GET" && url.pathname === "/api/health") { jsonResponse(res, 200, { ok: true, @@ -488,6 +491,7 @@ export function createBrokerServer(options = {}) { manager_url_configured: Boolean(managerUrl), shared_secret_configured: Boolean(sharedSecret), agents_connected: agents.size, + lastActivityAt, }); return; } @@ -1083,6 +1087,10 @@ export function createBrokerServer(options = {}) { pendingCommands, managerUrl, authMode, + containerStartedAt, + get lastActivityAt() { + return lastActivityAt; + }, }, }; } diff --git a/services/edge-broker/test/broker.test.mjs b/services/edge-broker/test/broker.test.mjs index 7be7368f..f2471a09 100644 --- a/services/edge-broker/test/broker.test.mjs +++ b/services/edge-broker/test/broker.test.mjs @@ -219,6 +219,10 @@ test("broker exposes health and shared-secret diagnostics", async () => { assert.equal(healthJson.auth_mode, "manager"); assert.equal(healthJson.manager_url_configured, true); assert.equal(healthJson.shared_secret_configured, true); + assert.equal(typeof healthJson.lastActivityAt, "string"); + assert.match(healthJson.lastActivityAt, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/); + assert.ok(healthJson.lastActivityAt >= broker.state.containerStartedAt); + assert.equal(healthJson.lastActivityAt, broker.state.lastActivityAt); const invalidSecretResponse = await fetch(`http://127.0.0.1:${port}/api/diagnostics/shared-secret`, { method: "POST", @@ -247,6 +251,41 @@ test("broker exposes health and shared-secret diagnostics", async () => { await broker.close(); }); +test("broker updates lastActivityAt after each successful request", async () => { + const broker = createBrokerServer({ authMode: "manager", sharedSecret: "secret", managerUrl: "http://manager.test" }); + const address = await broker.listen(0); + const port = address.port; + + assert.equal(broker.state.lastActivityAt, broker.state.containerStartedAt); + + const firstResponse = await fetch(`http://127.0.0.1:${port}/api/health`); + const firstJson = await firstResponse.json(); + const firstActivityAt = broker.state.lastActivityAt; + + assert.equal(typeof firstJson.lastActivityAt, "string"); + assert.equal(firstJson.lastActivityAt, firstActivityAt); + assert.ok(firstActivityAt >= broker.state.containerStartedAt); + + await new Promise((resolve) => setTimeout(resolve, 5)); + + await fetch(`http://127.0.0.1:${port}/api/diagnostics/shared-secret`, { + method: "POST", + headers: { + "x-edge-broker-secret": "secret", + }, + }); + + assert.notEqual(broker.state.lastActivityAt, firstActivityAt); + assert.ok(broker.state.lastActivityAt > firstActivityAt); + + const secondResponse = await fetch(`http://127.0.0.1:${port}/api/health`); + const secondJson = await secondResponse.json(); + + assert.equal(secondJson.lastActivityAt, broker.state.lastActivityAt); + + await broker.close(); +}); + test("broker bridges browser shell sessions through the connected agent", async () => { const closedSessions = []; const broker = createBrokerServer({