wtclaude
268449f2a6
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>
247 lines
11 KiB
JavaScript
247 lines
11 KiB
JavaScript
// module-uo's Team provider (docs/website/TEAMS.md §2.3, MODULE_API.md 1.6.0).
|
||
//
|
||
// The tests that matter here are the REFUSALS. 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 is read as an
|
||
// authoritative "there are none", and core makes destructive decisions from an
|
||
// authoritative answer. Every state where this module cannot honestly claim to
|
||
// know is asserted below, because each one is a plausible place for someone to
|
||
// later "simplify" the guard away and get a plausible-looking empty list.
|
||
process.env.DB_HOST = '127.0.0.1'
|
||
process.env.DB_PORT = '59999'
|
||
|
||
const { test, beforeEach, afterEach } = require('node:test')
|
||
const assert = require('node:assert/strict')
|
||
|
||
const core = require('../core')
|
||
|
||
// The provider reaches the database through core, which is initialised with a ctx
|
||
// in production. A minimal one is enough here — the db layer is stubbed anyway.
|
||
core.init({
|
||
db: { query: async () => [] },
|
||
log: () => ({ error() {}, warn() {}, info() {}, debug() {} }),
|
||
moduleId: 'uo',
|
||
})
|
||
|
||
const db = require('../model/teamProvider/teamProvider.db')
|
||
const uoLinkConfig = require('../model/uoLinkConfig/uoLinkConfig.model')
|
||
const uoLinkSocket = require('../utils/uoLinkSocket')
|
||
const provider = require('../model/teamProvider/teamProvider.model')
|
||
|
||
const saved = []
|
||
function patch(mod, name, fn) {
|
||
saved.push([mod, name, mod[name]])
|
||
mod[name] = fn
|
||
}
|
||
|
||
// The healthy default: configured, enabled, connected. Each test then breaks only
|
||
// the thing it is about.
|
||
function healthy() {
|
||
patch(uoLinkConfig, 'getSafe', async () => ({ baseUrl: 'http://127.0.0.1:7787', enabled: true }))
|
||
patch(uoLinkSocket, 'getState', () => ({ connected: true, running: true }))
|
||
}
|
||
|
||
const guild = (extra = {}) => ({
|
||
id: 1, name: 'The Silver Hand', abbr: 'TSH', alliance: null,
|
||
members: 2, online: 1, leader_serial: '0x1', leader_name: 'Aldric', leader_acct: 'aldric', ...extra,
|
||
})
|
||
|
||
const member = (extra = {}) => ({
|
||
serial: '0x1', name: 'Aldric', acct: 'aldric', web_id: null, is_player: 1,
|
||
linked_user_id: null, is_online: 0, ...extra,
|
||
})
|
||
|
||
beforeEach(healthy)
|
||
afterEach(() => {
|
||
while (saved.length) {
|
||
const [mod, name, fn] = saved.pop()
|
||
mod[name] = fn
|
||
}
|
||
})
|
||
|
||
// ── The refusals ───────────────────────────────────────────────────────────
|
||
|
||
test('no uo-link configured refuses, on all three methods', async () => {
|
||
patch(uoLinkConfig, 'getSafe', async () => ({ baseUrl: null, enabled: false }))
|
||
patch(db, 'listGuilds', async () => { throw new Error('must not be read') })
|
||
|
||
for (const answer of [await provider.getTeams(), await provider.getTeamMembers('1'), await provider.getTeamLeaders('1')]) {
|
||
assert.equal(answer.ok, false)
|
||
assert.match(answer.reason, /no uo-link configured/)
|
||
assert.equal(answer.teams, undefined)
|
||
assert.equal(answer.members, undefined)
|
||
}
|
||
})
|
||
|
||
test('a disabled integration refuses rather than reporting a frozen board', async () => {
|
||
patch(uoLinkConfig, 'getSafe', async () => ({ baseUrl: 'http://x', enabled: false }))
|
||
const answer = await provider.getTeams()
|
||
assert.equal(answer.ok, false)
|
||
assert.match(answer.reason, /disabled/)
|
||
})
|
||
|
||
test('a disconnected socket refuses, even though the board is still there', async () => {
|
||
// The tempting mistake, stated as a test: the board is durable and survives an
|
||
// outage, so serving it looks harmless. Core cannot tell a board five minutes
|
||
// stale from one five days stale, and it archives Teams and departs members
|
||
// from a complete answer.
|
||
patch(uoLinkSocket, 'getState', () => ({ connected: false, running: true }))
|
||
patch(db, 'listGuilds', async () => [guild()])
|
||
|
||
const answer = await provider.getTeams()
|
||
assert.equal(answer.ok, false)
|
||
assert.match(answer.reason, /not connected/)
|
||
assert.equal(answer.teams, undefined, 'a stale board must not arrive as authoritative')
|
||
})
|
||
|
||
test('a database error refuses instead of throwing at core', async () => {
|
||
patch(db, 'listGuilds', async () => { throw new Error('table gone') })
|
||
const answer = await provider.getTeams()
|
||
assert.equal(answer.ok, false)
|
||
assert.match(answer.reason, /table gone/)
|
||
})
|
||
|
||
test('a guild absent from the board refuses rather than reporting an empty roster', async () => {
|
||
patch(db, 'findGuild', async () => [])
|
||
const members = await provider.getTeamMembers('99')
|
||
assert.equal(members.ok, false)
|
||
assert.match(members.reason, /not on the board/)
|
||
|
||
const leaders = await provider.getTeamLeaders('99')
|
||
assert.equal(leaders.ok, false)
|
||
})
|
||
|
||
test('a roster that has not arrived yet refuses — the board count is what tells us', async () => {
|
||
// Protocol 4's roster arrives 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 no roster rows. Reporting that as an empty roster would
|
||
// depart every member.
|
||
patch(db, 'findGuild', async () => [guild({ members: 155 })])
|
||
patch(db, 'listGuildMembers', async () => [])
|
||
|
||
const answer = await provider.getTeamMembers('1')
|
||
assert.equal(answer.ok, false)
|
||
assert.match(answer.reason, /has not arrived yet/)
|
||
assert.match(answer.reason, /155/, 'the count is in the message, because it is the evidence')
|
||
})
|
||
|
||
test('a guild the board says is genuinely empty reports an empty roster', async () => {
|
||
// The other side of the same coin: when the board itself says zero, an empty
|
||
// roster is the truth and withholding it would freeze a disbanding guild's
|
||
// membership forever.
|
||
patch(db, 'findGuild', async () => [guild({ members: 0 })])
|
||
patch(db, 'listGuildMembers', async () => [])
|
||
|
||
const answer = await provider.getTeamMembers('1')
|
||
assert.equal(answer.ok, true)
|
||
assert.deepEqual(answer.members, [])
|
||
})
|
||
|
||
// ── The good answers ───────────────────────────────────────────────────────
|
||
|
||
test('a guild becomes a Team keyed on its persistent ServUO id', async () => {
|
||
// The id survives a rename, which is what lets core apply its rename rule
|
||
// instead of seeing an unrelated new guild.
|
||
patch(db, 'listGuilds', async () => [guild()])
|
||
const answer = await provider.getTeams()
|
||
|
||
assert.equal(answer.ok, true)
|
||
assert.equal(answer.complete, true)
|
||
assert.deepEqual(answer.teams, [
|
||
{ externalId: '1', name: 'The Silver Hand', abbr: 'TSH', meta: null },
|
||
])
|
||
})
|
||
|
||
test('an alliance rides along as opaque meta', async () => {
|
||
patch(db, 'listGuilds', async () => [guild({ alliance: 'The Concord' })])
|
||
const { teams } = await provider.getTeams()
|
||
assert.deepEqual(teams[0].meta, { alliance: 'The Concord' })
|
||
})
|
||
|
||
test('the external id is a string, so core never compares a number to one', async () => {
|
||
patch(db, 'listGuilds', async () => [guild({ id: 42 })])
|
||
const { teams } = await provider.getTeams()
|
||
assert.equal(teams[0].externalId, '42')
|
||
})
|
||
|
||
test('a roster maps to the member shape core expects', async () => {
|
||
patch(db, 'findGuild', async () => [guild()])
|
||
patch(db, 'listGuildMembers', async () => [
|
||
member({ serial: '0x1', name: 'Aldric', is_online: 1 }),
|
||
member({ serial: '0x2', name: 'Bree', acct: null, is_online: 0 }),
|
||
])
|
||
|
||
const { members } = await provider.getTeamMembers('1')
|
||
assert.equal(members.length, 2)
|
||
assert.equal(members[0].memberKey, '0x1')
|
||
assert.equal(members[0].displayName, 'Aldric')
|
||
assert.equal(members[0].online, true)
|
||
assert.equal(members[0].leader, true, 'matches the board’s leader_serial')
|
||
assert.equal(members[1].leader, false)
|
||
assert.equal(members[1].online, false)
|
||
})
|
||
|
||
test('rankLabel is null, honestly — the wire carries no guild rank', async () => {
|
||
// The roster member is the standard actor object (serial, name, player, acct?,
|
||
// webId?). Inventing a rank from the leader flag would be core displaying a
|
||
// label this module made up.
|
||
patch(db, 'findGuild', async () => [guild()])
|
||
patch(db, 'listGuildMembers', async () => [member()])
|
||
const { members } = await provider.getTeamMembers('1')
|
||
assert.equal(members[0].rankLabel, null)
|
||
})
|
||
|
||
test('a member with no account at all is fine and unlinked', async () => {
|
||
// §2.3 of the protocol spec: acct is genuinely optional — a PlayerMobile can
|
||
// have no Account, and the local test world contains such mobiles.
|
||
patch(db, 'findGuild', async () => [guild()])
|
||
patch(db, 'listGuildMembers', async () => [member({ acct: null, web_id: null, linked_user_id: null })])
|
||
const { members } = await provider.getTeamMembers('1')
|
||
assert.equal(members[0].userId, null)
|
||
})
|
||
|
||
test('userId comes from the roster’s web_id first, then the link table', async () => {
|
||
patch(db, 'findGuild', async () => [guild()])
|
||
patch(db, 'listGuildMembers', async () => [
|
||
member({ serial: '0xA', web_id: '7', linked_user_id: 99 }), // roster wins
|
||
member({ serial: '0xB', web_id: null, linked_user_id: 12 }), // fallback
|
||
member({ serial: '0xC', web_id: '0', linked_user_id: null }), // neither
|
||
])
|
||
const { members } = await provider.getTeamMembers('1')
|
||
assert.equal(members[0].userId, 7, 'what the shard itself asserted at roster time')
|
||
assert.equal(members[1].userId, 12, 'the fallback for a row that predates the link')
|
||
assert.equal(members[2].userId, null)
|
||
})
|
||
|
||
test('web_id arrives as a string from the wire and is coerced', async () => {
|
||
patch(db, 'findGuild', async () => [guild()])
|
||
patch(db, 'listGuildMembers', async () => [member({ web_id: '42' })])
|
||
const { members } = await provider.getTeamMembers('1')
|
||
assert.equal(members[0].userId, 42)
|
||
assert.equal(typeof members[0].userId, 'number')
|
||
})
|
||
|
||
test('leadership is the board’s single leader — one, and honestly one', async () => {
|
||
// TEAMS.md §2.5 expects multiple leaders (GuildRank.Rank >= 4) and core
|
||
// supports them, but Protocol 4 does not put rank on the wire. Raising this to
|
||
// the full set is a protocol change, not something this file can fix.
|
||
patch(db, 'findGuild', async () => [guild({ leader_serial: '0x1' })])
|
||
assert.deepEqual((await provider.getTeamLeaders('1')).leaders, ['0x1'])
|
||
})
|
||
|
||
test('a guild with no leader on the board reports none rather than guessing', async () => {
|
||
patch(db, 'findGuild', async () => [guild({ leader_serial: null })])
|
||
const answer = await provider.getTeamLeaders('1')
|
||
assert.equal(answer.ok, true)
|
||
assert.deepEqual(answer.leaders, [])
|
||
})
|
||
|
||
test('an empty board is an authoritative empty list — the shard really has no guilds', async () => {
|
||
// Distinct from every refusal above: the socket is connected and the board is
|
||
// readable, so "no guilds" is a fact. Core still quarantines it before acting.
|
||
patch(db, 'listGuilds', async () => [])
|
||
const answer = await provider.getTeams()
|
||
assert.equal(answer.ok, true)
|
||
assert.deepEqual(answer.teams, [])
|
||
})
|