feat(teams): answer core's Team provider from the guild board
A UO guild is a Team. This registers module-uo as the authoritative source of
them (MODULE_API 1.6.0, docs/website/TEAMS.md §2.3) and answers the three
questions core asks, from the board and the roster Protocol 4 put there.
`externalId` is the persistent ServUO `Guild.Id`, which survives a rename -- so
core sees "an id whose name changed" and applies its rename rule rather than an
unrelated new guild appearing beside the old one. That mapping is this module's
to make: only the game knows what identity survives what.
The most important code here is the refusal guard, and it is deliberately
conservative. Core's contract is that module unavailability becomes staleness and
never emptiness, and this module is the only thing that can honour it -- an empty
array from here reads as an authoritative "there are none", and core archives
Teams and departs members from an authoritative answer. Three states refuse: no
uo-link configured, the integration disabled, and the socket not connected.
**The third is the one worth arguing about.** The board is durable and survives an
outage, so serving it while disconnected looks harmless. It is not: core cannot
tell a board five minutes stale from one five days stale, and a complete answer
licenses destruction. There is a test named for that.
A fourth refusal has no equivalent anywhere else: a guild whose roster has not
arrived. Protocol 4's roster comes on its own frames, separately from the
`guild.update` that creates the board row, so there is a real window where a
155-member guild has zero roster rows. The board's own `members` count is the only
thing that distinguishes "the roster is late" from "this guild is empty", and it
is checked -- with the count in the refusal message, because it is the evidence.
The other side is tested too: when the board says zero, an empty roster is the
truth and withholding it would freeze a disbanding guild's membership forever.
Two limitations, both honest and both in the code as comments:
- **`rankLabel` is null.** The wire's roster member is the standard actor object
(`serial`, `name`, `player`, `acct?`, `webId?`) and carries no guild rank.
Inventing a label from the leader flag would be core displaying something this
module made up.
- **One leader, not several.** TEAMS.md §2.5 expects multiple leaders from
`GuildRank.Rank >= 4` and core supports them, but Protocol 4 does not put rank
on the wire, so the only leadership visible here is the board's single
`leader_serial`. Raising it to the full set is a protocol change, not
something this module can fix.
`online` comes from `shard_online` rather than the roster, which carries no
per-member presence and only a board-level count -- the same source the public
"who's online" surface already uses. `userId` prefers the roster's own `web_id`
(what the shard asserted at roster time) and falls back to the `shard_account_links`
join for a member whose row predates their link; resolving it here rather than in
core is the contract, since core reading `shard_account_links` would be core
naming a module's table.
`coreApi` stays `^1.3.0` -- 1.6.0 satisfies it, which is what makes the bump minor.
18 provider tests plus two on the entry point: that all three methods are
registered, and that registration performs no query. The second matters because
register() runs while core's app.js is still being required with the pool pointed
at a dead port, which both routeManifest.js and swagger.js depend on.
`fakeApi` gained `registerTeamProvider` with the same `once` rule core applies --
one provider per deployment, so a second registration has to fail here too rather
than passing a shape core rejects at load.
411 -> 413 tests, all passing.
Refs docs/website/TEAMS.md §2.3, Part 12 phase 2
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
66
server/model/teamProvider/teamProvider.db.js
Normal file
66
server/model/teamProvider/teamProvider.db.js
Normal file
@@ -0,0 +1,66 @@
|
||||
// SQL behind the Team provider — three questions core asks, answered from the
|
||||
// guild board and the roster Protocol 4 put there.
|
||||
//
|
||||
// Every statement reads only THIS module's tables. Core's Team tables are
|
||||
// core-internal (docs/website/TEAMS.md §10.3) and this module must never name
|
||||
// one, even though it is what fills them.
|
||||
|
||||
const core = require('../../core')
|
||||
|
||||
const query = (...args) => core.db.query(...args)
|
||||
|
||||
/**
|
||||
* The guild board — one row per guild the shard has told us about.
|
||||
*
|
||||
* `members`/`online` here are the COUNTS `guild.update` carries; the roster is a
|
||||
* separate table (Protocol 4). Both are read, because a count is what the shard
|
||||
* asserts and a roster is what it enumerated, and they can legitimately disagree
|
||||
* for the moment between a membership change and the sweep that reports it.
|
||||
*/
|
||||
const listGuilds = () =>
|
||||
query(
|
||||
`SELECT id, name, abbr, alliance, members, online, leader_serial, leader_name, leader_acct
|
||||
FROM shard_guilds ORDER BY name ASC`,
|
||||
)
|
||||
|
||||
const findGuild = (id) =>
|
||||
query(
|
||||
`SELECT id, name, abbr, alliance, members, online, leader_serial, leader_name, leader_acct
|
||||
FROM shard_guilds WHERE id = ? LIMIT 1`,
|
||||
[id],
|
||||
)
|
||||
|
||||
/**
|
||||
* One guild's roster, with the site link and live presence folded in.
|
||||
*
|
||||
* Two LEFT JOINs, both deliberate:
|
||||
*
|
||||
* - `shard_account_links` resolves `user_id` HERE rather than in core, because
|
||||
* this module owns that table and a core that read it would be core naming a
|
||||
* module's table by name (§2.3). It is also why a freshly linked account
|
||||
* appears as linked on the next reconcile rather than needing core to know
|
||||
* anything about linking.
|
||||
* - `shard_online` is how a member's `online` is answered at all. The roster
|
||||
* frame does not carry it — the wire's member is the standard actor object
|
||||
* (`serial`, `name`, `player`, `acct?`, `webId?`), and the board's `online` is
|
||||
* a count, not a set. Presence therefore comes from the online table, which
|
||||
* is the same source the public "who's online" surface already uses.
|
||||
*
|
||||
* `web_id` on the roster row is preferred over the link table when present: it is
|
||||
* what the shard itself asserted at roster time, and the join is the fallback for
|
||||
* a member whose row predates their link.
|
||||
*/
|
||||
const listGuildMembers = (guildId) =>
|
||||
query(
|
||||
`SELECT m.serial, m.name, m.acct, m.web_id, m.is_player,
|
||||
l.user_id AS linked_user_id,
|
||||
(o.serial IS NOT NULL) AS is_online
|
||||
FROM shard_guild_members m
|
||||
LEFT JOIN shard_account_links l ON l.account = m.acct
|
||||
LEFT JOIN shard_online o ON o.serial = m.serial
|
||||
WHERE m.guild_id = ?
|
||||
ORDER BY m.name ASC`,
|
||||
[guildId],
|
||||
)
|
||||
|
||||
module.exports = { listGuilds, findGuild, listGuildMembers }
|
||||
Reference in New Issue
Block a user