Refresh Scheduler & Telemetry #68
Description
Epic 5: Licensing Infrastructure
User Story
As a server operator,
I want the license to be refreshed periodically and optional telemetry sent,
So that license upgrades are picked up automatically and usage data helps improve the product.
Acceptance Criteria
Given API key mode with refresh.enabled = true and refresh.interval = 24h
When the server is running
Then a scheduler fires every 24h, calling ApiKeyClient.fetchJwt(apiKey)
And on success, the in-memory JWT and disk cache are updated
Given static JWT mode with a refresh_url claim in the JWT
When the refresh scheduler fires
Then a POST is sent to the refresh_url with the current JWT as Authorization: Bearer
And the request body includes license_id, instance_id, version, uptime_hours, and optional telemetry
Given static JWT mode without a refresh_url claim
When the server runs
Then no refresh is attempted (fully offline mode)
Given the in-memory JWT expires in less than 48 hours
When the scheduler detects this
Then an immediate refresh is forced regardless of the regular schedule
Given a refresh failure (network error, 5xx)
When the scheduler detects the failure
Then a WARNING is logged and the current JWT continues to be used
And the next scheduled refresh proceeds normally
Given telemetry.enabled = true (default)
When a refresh request is sent
Then the request body includes telemetry: { queries_total, joins_total, mvs_active, clusters_connected }
Given telemetry.enabled = false
When a refresh request is sent
Then the telemetry field is omitted from the request body
And the refresh still includes instance_id and version (not telemetry)
Given first server startup
When no instance-id file exists at ~/.softclient4es/instance-id
Then a random UUID is generated and persisted to the file
And subsequent startups reuse the same instance ID
Dependencies
- Expiry Grace Period & Degradation (FR27)
Requirements
- FR29: Periodic license refresh (configurable, default 24h) with optional anonymized telemetry