RunicGateway/Module-Rust
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(rust): notifications and engagement (phase 10, protocol 7)

Browse Source 
Registers the engagement set R7 put in v1: thirteen triggers, four push
streams, three audiences, four bodies (two triggers, email and in-app)
and thirteen disabled rules in seven groups (PLAN.md §25, D59-D68).

The raid alert goes to everyone authorised on the tool cupboard, one
emit per linked person with ownerUserId, so the owner ceiling holds per
emit. It covers doors and walls (protocol 7), never names the raider,
alerts nobody when there is no cupboard, and carries ownerOnline so
"offline only" is the seeded rule's condition rather than code.

The fan-out runs off ingest before a frame is applied, since applying a
disband deletes the roster the notice is sent to. A replayed event is
told only while it is news: 15 minutes for broadcasts, 24 hours for
personal and staff events. Dedupe keys come from the event, not the
sidecar's row id. Server online/offline and a new kills leader are
in-memory transitions, never on first sight, and a tie is not a lead.
A login with no approval within a minute becomes a staff notice via a
query, so a restart loses nothing.

Also fixes a phase-4 gap (D68): the refresh now asks /health, so a game
that hung, or whose bridge was unloaded, while the sidecar stayed up no
longer reads as online. It stops naming players as online, and a stale
board no longer moves "last seen".

engagement-triggers.json is the committed freeze of all of it, checked
in CI with line endings normalised. The check was verified by breaking
it both ways.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
This commit is contained in:
claude
2026-09-23 06:06:08 -05:00
parent dc3c9689b4
commit 285db0baa7
22 changed files with 3256 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
server/boot.js
View File

@@ -21,10 +21,11 @@
// letting that fail the boot would make installing the module before installing
// the bridge impossible.
//
// ── Three timers, and they answer three different questions ───────────────
// ── Four timers, and they answer four different questions ─────────────────
//
// refresh (30s) what is each server, and who is on it — the BOARDS
// ingest (5s) what has happened since we last looked — the CURSOR
// sweep (1m) which login attempts were never let in (PLAN.md §25)
// prune (1h) forgetting the detail we promised not to keep for ever
//
// The boards poll and the ingest are deliberately separate rather than one loop
@@ -42,6 +43,7 @@
const core = require('./core')
const db = require('./model/servers/servers.db')
const engagement = require('./engagement/emit')
const eventsDb = require('./model/events/events.db')
const ingest = require('./ingest')
const permSync = require('./permSync')
@@ -53,10 +55,12 @@ const log = core.logger('boot')
let refreshTimer = null
let ingestTimer = null
let pruneTimer = null
let sweepTimer = null
const REFRESH_MS = 30 * 1000
const INGEST_MS = 5 * 1000
const PRUNE_MS = 60 * 60 * 1000
const SWEEP_MS = 60 * 1000
/**
* How long this module keeps raw events.
@@ -94,7 +98,15 @@ async function refreshOne(server) {
// One call for both boards. `/server` would answer the same question about
// the server itself, but presence would then be a second round trip to the
// same process for a fact it already had in hand.
const board = await sidecar.boards(server)
//
// **And one for `/health`, because the boards cannot say whether the game is
// there NOW** (D68, PLAN.md §25.1). The sidecar keeps its last `server.hello`
// after the plugin disconnects — that is what lets a page render a server
// that is off — so a game that hung, or whose bridge was unloaded, while the
// sidecar stayed up read as online here from phase 4 until phase 10. Only
// `/health`'s `plugin_connected` answers the question, and the two are asked
// together so they describe the same moment.
const [board, health] = await Promise.all([sidecar.boards(server), sidecar.health(server)])
// Three outcomes, and collapsing any two of them loses something an operator
// needs:
@@ -113,6 +125,7 @@ async function refreshOne(server) {
// server said, which is exactly what the pages exist to render while it is
// off.
await db.markUnreachable(server.id, false)
engagement.serverObserved(server, false)
return
}
@@ -125,20 +138,34 @@ async function refreshOne(server) {
// reach is worse than an empty one, because it looks current.
await db.markUnreachable(server.id, true)
await ingest.applyBoards(server.id, {})
engagement.serverObserved(server, false)
return
}
await ingest.applyBoards(server.id, boards)
// Unknown is not connected. A `/health` that did not answer while `/boards`
// did is odd enough to be worth a line, and reporting the server up on the
// strength of a board the game may have left behind hours ago is the defect
// this call exists to remove.
const connected = Boolean(health.ok && health.data && health.data.plugin_connected === true)
if (!health.ok) log.warn('the sidecar answered /boards but not /health', { server: server.id })
// The presence board is the plugin's last word too. While the game is not
// connected it names people as online who may have left hours ago, which is
// both wrong and — under §23's rule — a claim about named people nobody made.
await ingest.applyBoards(
server.id,
connected ? boards : { ...boards, 'players.online': { players: [] } },
)
await db.putState({
serverId: server.id,
reachable: true,
// A stored `server.hello` means the game connected; whether it is connected
// NOW is a different question, and `/health` is what answers it. The board
// alone cannot say, which is why `online` is not simply `true` here — it is
// decided by freshness in the model, from `updated_at`.
online: true,
players: Number(frame.players) || 0,
// The plugin is connected NOW (D68). A stored `server.hello` only says it
// connected once; the model still applies its own freshness on top.
online: connected,
// A board the game left behind is a description, not a sighting.
seen: connected,
players: connected ? Number(frame.players) || 0 : 0,
maxPlayers: Number(frame.maxPlayers) || 0,
hostname: frame.hostname || null,
level: frame.level || null,
@@ -150,6 +177,9 @@ async function refreshOne(server) {
protocol: frame.protocol === undefined ? null : Number(frame.protocol),
raw: frame,
})
// After the write, so a transition announced is one a page already shows.
engagement.serverObserved(server, connected)
} catch (err) {
// A failure here is one server's, and it must not reach `Promise.allSettled`
// as a rejection that hides which one. Log with the id and carry on.
@@ -189,6 +219,26 @@ async function prune() {
}
}
/**
* Login attempts that were never approved (D64, PLAN.md §25).
*
* On its own minute timer rather than the prune's hour: an attempt waits a
* minute for its approval, and a staff alert an hour late is not an alert. A
* query over stored rows, so it needs nothing kept in memory and a restart loses
* nothing; the dedupe key makes a second pass over the same attempt a no-op.
*/
async function sweep() {
let rows
try {
rows = await servers.listForPolling()
} catch (err) {
log.warn('could not read the server list', { error: err.message })
return
}
const sent = await engagement.sweepLoginDenied(rows)
if (sent > 0) log.info('unapproved logins reported', { attempts: sent })
}
async function onBoot() {
await refresh()
// The permission mirror owns its own loop and its own cadence (see
@@ -199,10 +249,11 @@ async function onBoot() {
refreshTimer = setInterval(refresh, REFRESH_MS)
ingestTimer = setInterval(ingestAll, INGEST_MS)
pruneTimer = setInterval(prune, PRUNE_MS)
sweepTimer = setInterval(sweep, SWEEP_MS)
// Node keeps the process alive for a pending timer. Core's own intervals are
// unref'd for exactly this reason: a module that forgets turns `Ctrl-C` into a
// thirty-second wait, and on a host it turns a `systemctl stop` into a SIGKILL.
for (const timer of [refreshTimer, ingestTimer, pruneTimer]) {
for (const timer of [refreshTimer, ingestTimer, pruneTimer, sweepTimer]) {
if (timer && typeof timer.unref === 'function') timer.unref()
}
@@ -220,13 +271,14 @@ async function onBoot() {
async function onShutdown() {
permSync.stop()
for (const timer of [refreshTimer, ingestTimer, pruneTimer]) {
for (const timer of [refreshTimer, ingestTimer, pruneTimer, sweepTimer]) {
if (timer) clearInterval(timer)
}
refreshTimer = null
ingestTimer = null
pruneTimer = null
sweepTimer = null
log.info('shut down')
}