rkd: check the server API version before signing in #7

New issue

Closed

opened 2026-09-23 17:24:23 +02:00 by dozken · 0 comments

dozken commented

2026-09-23 17:24:23 +02:00

Owner

The RKD server now reports its API contract version on GET /api/health as {"status":"ok","api_version":N}. A server from before the contract answers a bare OK, which counts as version 0. The app declares the lowest version it needs, refuses store builds against an older server, and shows a "server needs an update" screen instead of failing request by request.

The plugin has the same exposure and no check. It is installed from the marketplace, not auto-updated, and the server it talks to (prod, dev or any address) can be older than it. It depends on /api/app-hosts/*, which older servers don't have, so today it fails with 404s on device sign-in and gives no reason.

Proposal: at startup (and in the status tool), GET <server>/api/health with no auth, parse it the same way the app does (bare OK = 0, JSON api_version integer, anything else = unknown), and compare against a MIN_SERVER_API_VERSION constant (1 today). Below the minimum: say so on stderr, in the instructions and in status ("this RKD server is older than the plugin needs; update the server or point the plugin at another one") and skip device sign-in. Unknown or unreachable: warn, don't block — same as checkClientVersion does for the Claude Code version.

Tests: bare OK, below, at and above the minimum, unknown body, network error. When the server later bumps API_VERSION for something the plugin uses, raise the plugin's minimum in the same release.

The RKD server now reports its API contract version on `GET /api/health` as `{"status":"ok","api_version":N}`. A server from before the contract answers a bare `OK`, which counts as version 0. The app declares the lowest version it needs, refuses store builds against an older server, and shows a "server needs an update" screen instead of failing request by request. The plugin has the same exposure and no check. It is installed from the marketplace, not auto-updated, and the server it talks to (`prod`, `dev` or any address) can be older than it. It depends on `/api/app-hosts/*`, which older servers don't have, so today it fails with 404s on device sign-in and gives no reason. Proposal: at startup (and in the `status` tool), GET `<server>/api/health` with no auth, parse it the same way the app does (bare `OK` = 0, JSON `api_version` integer, anything else = unknown), and compare against a `MIN_SERVER_API_VERSION` constant (1 today). Below the minimum: say so on stderr, in the instructions and in `status` ("this RKD server is older than the plugin needs; update the server or point the plugin at another one") and skip device sign-in. Unknown or unreachable: warn, don't block — same as `checkClientVersion` does for the Claude Code version. Tests: bare `OK`, below, at and above the minimum, unknown body, network error. When the server later bumps `API_VERSION` for something the plugin uses, raise the plugin's minimum in the same release.

dozken self-assigned this

2026-09-23 17:24:23 +02:00

dozken referenced this issue from a commit

2026-09-23 17:54:45 +02:00

feat(rkd): check the server's API version before signing in (#7)

dozken referenced this issue from a pull request that will close it,

2026-09-23 17:55:14 +02:00

feat(rkd): check the server API version before signing in #8

dozken closed this issue

2026-09-23 18:11:38 +02:00