fix(uo-link): pin protocol 4, the version this build actually speaks
All checks were successful
PR Checks / client-build (pull_request) Successful in 24s
PR Checks / server-tests (pull_request) Successful in 28s
PR Checks / frozen-manifest (pull_request) Successful in 40s

The protocol-4 cutover moved `link`'s PROTOCOL_VERSION, the overlay's
`overlay.toml` and this module's ingest — `guild.roster` and `guild.leave`
landed with the Teams cutover — but left both of this module's pin sites at 3.

A fresh install therefore came up speaking 3 to a protocol-4 sidecar, and a
sidecar answers a stale client with `409 protocol version mismatch` rather than
mis-parsing it. The failure is total and silent: every REST read fails, the WS
closes on ws.hello, and the operator sees an empty marketplace, an empty guild
board and no shard status, with the cause only in the server log. It cleared
only when an admin edited the number by hand in Admin → Shard.

Found while standing up a demo deployment for the marketing site's screenshots.

- `DEFAULT_PROTOCOL` → 4 (the constant used before an admin has saved anything)
- the `uo_link_config.protocol` column default → 4, at both declaration sites
- a protocol-4 one-shot mirroring the protocol-3 one, guarded by its own marker
  so an operator who deliberately pins an older sidecar stays pinned, and
  written `protocol < 4` so an install that never took the protocol-3 migration
  is carried the whole way rather than one step
- three regression tests: the column default, the marker ordering, and the
  `< 4` predicate

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-24 19:17:51 -05:00
parent 6fca1cebf4
commit 7f7d4578ce
3 changed files with 94 additions and 3 deletions

View File

@@ -47,7 +47,7 @@ CREATE TABLE IF NOT EXISTS uo_link_config (
base_url VARCHAR(255) NULL,
ws_url VARCHAR(255) NULL,
auth_token_enc TEXT NULL,
protocol INT NOT NULL DEFAULT 3,
protocol INT NOT NULL DEFAULT 4,
enabled TINYINT(1) NOT NULL DEFAULT 0,
status VARCHAR(20) NOT NULL DEFAULT 'disconnected',
status_detail VARCHAR(500) NULL,
@@ -675,6 +675,35 @@ UPDATE uo_link_config SET protocol = 3
-- not cut over yet.
INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_3_migrated', '1');
-- Protocol 4 cutover: the same migration one step later, and the one this module
-- OWED and did not pay.
--
-- The protocol-4 work shipped across three repos — `link`'s PROTOCOL_VERSION, the
-- overlay's `overlay.toml`, and this module's `guild.roster` / `guild.leave` ingest —
-- but the pinned version stayed at 3 on both of its declaration sites here. A fresh
-- install therefore came up speaking 3 to a sidecar speaking 4, and a sidecar answers
-- a stale client with `409 protocol version mismatch` rather than mis-parsing it. The
-- symptom is total: every REST read fails and the WS closes on ws.hello, so a new
-- deployment shows an empty marketplace, an empty guild board and no shard status,
-- with the cause visible only in the server log. Found while standing up a demo
-- deployment for the marketing site's screenshots.
--
-- Same shape as the block above, for the same reasons: MODIFY fixes the column
-- default for databases created before the bump, and the UPDATE is one-shot against
-- its own marker so that an operator who deliberately pins an older sidecar in
-- Admin → Shard stays pinned. `protocol < 4` and not `= 3`, so an install that
-- somehow never took the protocol-3 migration is carried the whole way rather than
-- one step.
ALTER TABLE uo_link_config MODIFY COLUMN protocol INT NOT NULL DEFAULT 4;
UPDATE uo_link_config SET protocol = 4
WHERE id = 1 AND protocol < 4
AND NOT EXISTS (SELECT 1 FROM settings WHERE `key` = 'uo_link_protocol_4_migrated');
-- The marker is written HERE, in this module's fragment, for the reason spelled out
-- above: core's schema is replayed in full BEFORE any module fragment, so a marker
-- left in core would already exist when this UPDATE read it and the one-shot could
-- never fire.
INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_4_migrated', '1');
-- ── Settings rows this module owns ─────────────────────────────────────────
--
-- Both keys predate the module system and both name a game concept, so core