From 2b09677e96f25844e5d62c7451cb93fc86d9017c Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Tue, 17 Nov 2026 04:49:12 -0300 Subject: [PATCH] feat: log seeder shutdown timings for deploy measurement The seeder's JSON log now carries an absolute `at` on `ws` and `ready`, and a `stopped` event at shutdown with drainMs, closeMs (or fatal: true after a self-close) and stopListeningAt (only with --ws-port). One production deploy then gives the close time and the time the WebSocket port was dark, which decides whether the standby handoff is needed. No behaviour change: shutdown order and exit codes are unchanged. --- README.md | 2 +- apps/cli/lib/commands/seed.js | 21 ++++++- apps/cli/test/seed-shutdown-timing.test.js | 58 +++++++++++++++++++ docs/changelog/feat-seeder-shutdown-timing.md | 3 + docs/protocol.md | 6 +- .../feat-seeder-shutdown-timing.md | 22 +++++++ packages/core/lib/seeder.js | 2 +- 7 files changed, 107 insertions(+), 7 deletions(-) create mode 100644 apps/cli/test/seed-shutdown-timing.test.js create mode 100644 docs/changelog/feat-seeder-shutdown-timing.md create mode 100644 docs/verification/feat-seeder-shutdown-timing.md diff --git a/README.md b/README.md index 606f2a20..354dd41b 100644 --- a/README.md +++ b/README.md @@ -1052,7 +1052,7 @@ Registros: `journalctl -u varanda-seeder -f`. `seed list` e `seed drop`: `system Provisória até o parecer jurídico sobre registros de acesso (issue #38). -- **Formato.** Uma linha por evento na saída padrão. No serviço, `--json`: JSON Lines com os eventos `health`, `ws`, `ready`, `peer`, `admitted`, `rejected`, `have`, `peer-dropped`, `warning` e `fatal` (o mais frequente é `have`, a cada crescimento de um diário). Erros vão para a saída de erro como `erro: `. A linha não traz data e hora: o journal e o Docker carimbam cada uma. +- **Formato.** Uma linha por evento na saída padrão. No serviço, `--json`: JSON Lines com os eventos `health`, `ws`, `ready`, `peer`, `admitted`, `rejected`, `have`, `peer-dropped`, `warning`, `fatal` e `stopped` (o mais frequente é `have`, a cada crescimento de um diário). Erros vão para a saída de erro como `erro: `. A linha não traz data e hora (o journal e o Docker carimbam cada uma), exceto o instante `at` de `ws` e `ready` e o `stopListeningAt` de `stopped`, em ms desde 1970, que medem uma implantação. - **O que entra.** Chaves públicas de diários (64 hex), com tamanho ou motivo de recusa; a chave Noise dos pares (`peer`, `peer-dropped`); o tópico da associação (`ready`). São pseudônimos, e contam como dado pessoal quando alguém consegue ligá-los a uma pessoa. - **O que nunca entra.** Endereço IP ou porta de par (a entrada WebSocket nunca registra o endereço do cliente), conteúdo de publicação ou de perfil, certificados, chaves secretas e as requisições ao endpoint de saúde. - **Estatísticas de uso (serviço de conta).** O serviço de conta acrescenta só `{ event: 'usage', reason }`, com `reason` igual a `ligada`, `desligada`, `invalido` ou `falhou`. A linha não traz e-mail, chave, @nome nem endereço. diff --git a/apps/cli/lib/commands/seed.js b/apps/cli/lib/commands/seed.js index 6f20abbf..75060b71 100644 --- a/apps/cli/lib/commands/seed.js +++ b/apps/cli/lib/commands/seed.js @@ -130,8 +130,9 @@ async function runSeeder (flags) { // Handlers go in BEFORE start(): a signal during startup (DHT join) must not // take Node's default terminate path; the seeder is closed once start settles. let onSignal + let stopStartedAt = 0 const stopped = new Promise((resolve) => { - onSignal = () => resolve() + onSignal = () => { if (stopStartedAt === 0) stopStartedAt = Date.now(); resolve() } process.once('SIGINT', onSignal) process.once('SIGTERM', onSignal) }) @@ -147,7 +148,7 @@ async function runSeeder (flags) { } if (flags.wsPort !== null) { ws = await listenWs(flags, seeder) - log({ event: 'ws', host: ws.host, port: ws.port }) + log({ event: 'ws', host: ws.host, port: ws.port, at: Date.now() }) } await seeder.start() } catch (err) { @@ -162,6 +163,11 @@ async function runSeeder (flags) { // A fatal purge failure closes the seeder by itself. await Promise.race([stopped, seeder.closed]) } finally { + // Drain start: the signal. When the seeder closed itself (fatal), its + // store is already closed here, so closeMs would measure nothing: it is + // left out and `fatal: true` is logged instead. + const selfClosed = stopStartedAt === 0 + if (selfClosed) stopStartedAt = Date.now() process.off('SIGINT', onSignal) process.off('SIGTERM', onSignal) if (relay) relay.close() @@ -169,8 +175,19 @@ async function runSeeder (flags) { // 1006): they get 1012 'reiniciando' instead. Adds at most about 1 s. // drain() also stops listening, so a redial during seeder.close() is // refused (Caddy retries it for up to 5 s) rather than answered 503. + // stopListeningAt: drain() stops listening first, so this is its epoch ms + // to within the call; with the next process's ws `at` it gives the dark + // port time across a deploy. + const stopListeningAt = Date.now() if (ws) await ws.drain() + const drainedAt = Date.now() await seeder.close() + const timing = { event: 'stopped', drainMs: drainedAt - stopStartedAt } + if (selfClosed) timing.fatal = true + else timing.closeMs = Date.now() - stopStartedAt + // Only when a WebSocket listener actually stopped. + if (ws) timing.stopListeningAt = stopListeningAt + log(timing) if (health) await health.close() if (ws) await ws.close() } diff --git a/apps/cli/test/seed-shutdown-timing.test.js b/apps/cli/test/seed-shutdown-timing.test.js new file mode 100644 index 00000000..b464b716 --- /dev/null +++ b/apps/cli/test/seed-shutdown-timing.test.js @@ -0,0 +1,58 @@ +// `seed --json` logs the timings of one deploy: `ready` and `ws` carry an +// absolute `at`, and a SIGTERM ends with a `stopped` event holding drainMs, +// closeMs and stopListeningAt, so one production deploy gives the close time +// and (with the next process's `ws.at`) the time the port was dark. +const test = require('brittle') +const fs = require('node:fs') +const path = require('node:path') +const { spawn } = require('node:child_process') +const b4a = require('b4a') +const { testnet, tmpDir, until, bootstrapFlags } = require('./helpers/net') +const { Seeder } = require('@varanda/core/lib/seeder') +const { createSeederCert, generateAssociationKeyPair } = require('@varanda/core/lib/cert') + +const BIN = path.join(__dirname, '..', 'bin', 'varanda.js') + +const env = {} +for (const [k, v] of Object.entries(process.env)) if (!k.startsWith('VARANDA_')) env[k] = v + +function prepareSeederDir (t) { + const kp = generateAssociationKeyPair() + const assoc = b4a.toString(kp.publicKey, 'hex') + const dataDir = tmpDir(t, 'varanda-seed-') + Seeder.ensureConfig(dataDir, assoc) + const { publicKey } = Seeder.createKey(dataDir) + const certFile = path.join(tmpDir(t, 'varanda-sc-'), 'seeder-cert.json') + fs.writeFileSync(certFile, JSON.stringify(createSeederCert({ seeder: publicKey }, kp))) + Seeder.addCert(dataDir, certFile, assoc) + return dataDir +} + +test('seed: ws and ready carry at; SIGTERM logs stopped with drainMs, closeMs, stopListeningAt', async (t) => { + t.timeout(120000) + const { bootstrap } = await testnet(t) + const child = spawn(process.execPath, [BIN, 'seed', '--json', '--data', prepareSeederDir(t), '--ws-port', '0', ...bootstrapFlags(bootstrap)], { env }) + let stdout = '' + child.stdout.on('data', (d) => { stdout += d }) + child.stderr.on('data', () => {}) + const exited = new Promise((resolve) => child.on('close', resolve)) + t.teardown(() => child.kill('SIGKILL'), { force: true }) + const events = () => stdout.split('\n').filter(Boolean).map((l) => JSON.parse(l)) + const event = (name) => until(() => events().find((e) => e.event === name), { name: 'evento ' + name, timeoutMs: 30000 }) + + const ws = await event('ws') + const ready = await event('ready') + const before = Date.now() + t.ok(Number.isSafeInteger(ws.at) && ws.at <= before && ws.at > before - 120000, 'ws.at is a plausible epoch ms') + t.ok(Number.isSafeInteger(ready.at) && ready.at >= ws.at && ready.at <= before, 'ready.at is a plausible epoch ms, after ws.at') + + child.kill('SIGTERM') + t.is(await exited, 0, 'seed exits 0') + const stopped = events().find((e) => e.event === 'stopped') + t.ok(stopped, 'stopped event logged') + if (!stopped) return + t.ok(Number.isSafeInteger(stopped.drainMs) && stopped.drainMs >= 0, 'drainMs >= 0') + t.ok(Number.isSafeInteger(stopped.closeMs) && stopped.closeMs >= stopped.drainMs, 'closeMs >= drainMs') + t.ok(Number.isSafeInteger(stopped.stopListeningAt) && stopped.stopListeningAt >= before && stopped.stopListeningAt <= Date.now(), 'stopListeningAt is a plausible epoch ms after the signal was sent') + t.alike(Object.keys(stopped).sort(), ['closeMs', 'drainMs', 'event', 'stopListeningAt'], 'no other fields') +}) diff --git a/docs/changelog/feat-seeder-shutdown-timing.md b/docs/changelog/feat-seeder-shutdown-timing.md new file mode 100644 index 00000000..e18751dc --- /dev/null +++ b/docs/changelog/feat-seeder-shutdown-timing.md @@ -0,0 +1,3 @@ +### Alterado + +- O semeador passa a registrar, no log JSON, o instante absoluto (`at`, em ms desde 1970) nos eventos `ws` e `ready` e, ao desligar, o evento `stopped` com `drainMs`, `closeMs` e `stopListeningAt`, para medir numa implantação real o tempo de fechamento e o tempo em que a porta ficou sem escuta; nenhum comportamento muda (PR `feat/seeder-shutdown-timing`). Verificação em `docs/verification/feat-seeder-shutdown-timing.md`. diff --git a/docs/protocol.md b/docs/protocol.md index d96dc2e3..cf48cd70 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1238,7 +1238,7 @@ Lock before state (security fix cycle 2): `start()` takes the data-dir lock (ope 3. For each admitted key: `core = await openReplica(store, key)`; if `core.fork !== 0` -> startup drop with reason `'fork'`; else if `core.contiguousLength === 0` -> startup drop with reason `'no-cert'`; else if `core.length > maxLogBlocks || core.byteLength > maxLogBytes` -> startup drop with reason `'quota'` (review item 5: the quota is part of the startup gate, so an over-quota stored log, e.g. after a restart with a lowered limit, is purged BEFORE step 4 and its topic is never joined nor served); else LOCAL gate -> pass: keep; fail: startup drop with that reason. Startup drop (R6.1 order) = log `{ event: 'rejected', key, reason }`, for a blocked key the blobs its moments name (section 13, "Conjunto de blobs"), `await purgeReplica(store, key)` FIRST, then remove the key from `admitted`, then `await persist()`. If any purge throws, the key stays in the map and in the file and `start()` throws `Error('falha ao limpar diário rejeitado: ' + key8)` after closing the stores (fail closed). 3b. For each listed media core K (section 5 "Seeder media admission"), once the diaries are settled: its binding must be usable and its diary a step-3 survivor (else `unbound`); then `openMediaReplica`; `fork !== 0` -> `fork`; `contiguousLength === 0` -> `no-header`; over `MAX_MEDIA_BLOCKS` / `MAX_MEDIA_BYTES` -> `quota`; else the LOCAL media gate (`header-invalid` / `wrong-diary`). A pass beyond `maxMedia` survivors is purged with the event `{ event: 'warning', key, reason: 'media-full' }`; a failure logs `{ event: 'media-rejected', key, diary, reason }`. Both are purged FIRST, then removed from the `media` map, then `persist()`; a purge throw makes `start()` throw `Error('falha ao limpar mídia rejeitada: ' + key8)`. 4. For every surviving key: `watchFork`, live download, `watchContiguous`; every surviving media core is served the same way (step 5 joins its discovery key). A runtime `drop` that happens here (no swarm yet) skips the `swarm.leave` (`drop` is safe before the swarm exists). -5. `createSwarm({ bootstrap, keyPair, host })`; external streams are accepted from here (`Seeder#accepting()` turns true: every core is re-gated and prepared and the swarm exists; `acceptStream` refuses before it, and after `close()` begins), before the DHT join and the flush, as swarm peers already are; until `ready`, discovery answers stale and the index group and topic pages say indexing or incomplete, as DHT peers already saw during the flush; a failure from here on goes through `close()`, which closes the external streams accepted meanwhile; `done = store.findingPeers()`; join `topicFor(association)` + every surviving `discoveryKey` with `joinAndFlush` in try/finally `done()`; log `{ event: 'ready', topic, admitted, phases, cores }`: `phases` = `{ configMs, storeMs, stateMs, diariesMs, mediaMs, groupsMs, prepareMs, swarmMs, flushMs, totalMs, acceptingMs }` (non-negative integer milliseconds between the step boundaries of `start()`, `totalMs` from the start to the end of the flush; `acceptingMs` from the start to the point where external WebSocket streams are accepted, see below: it overlaps the other phases and is not part of `totalMs`) and `cores` = `{ diaries, media, groups }`, each `{ kept, dropped }` (the survivors of the re-gate step and the number it dropped; a diary admitted or dropped while the swarm flushes is not counted). No wire change. +5. `createSwarm({ bootstrap, keyPair, host })`; external streams are accepted from here (`Seeder#accepting()` turns true: every core is re-gated and prepared and the swarm exists; `acceptStream` refuses before it, and after `close()` begins), before the DHT join and the flush, as swarm peers already are; until `ready`, discovery answers stale and the index group and topic pages say indexing or incomplete, as DHT peers already saw during the flush; a failure from here on goes through `close()`, which closes the external streams accepted meanwhile; `done = store.findingPeers()`; join `topicFor(association)` + every surviving `discoveryKey` with `joinAndFlush` in try/finally `done()`; log `{ event: 'ready', topic, admitted, phases, cores, at }` (`at` = epoch ms when it is logged; the CLI's `ws` event carries the same `at` when the WebSocket listener is up, and its shutdown logs `{ event: 'stopped', drainMs, closeMs, stopListeningAt }`: `drainMs` and `closeMs` are the milliseconds from the signal to the end of the WebSocket drain and to the store closed, `stopListeningAt` the epoch ms just before the drain stops listening, present only with `--ws-port`; after a fatal self-close the store is already closed, so `closeMs` is left out and `fatal: true` is logged; the old process's `stopListeningAt` against the new process's `ws.at` gives the time the port was dark, by wall clock across two processes): `phases` = `{ configMs, storeMs, stateMs, diariesMs, mediaMs, groupsMs, prepareMs, swarmMs, flushMs, totalMs, acceptingMs }` (non-negative integer milliseconds between the step boundaries of `start()`, `totalMs` from the start to the end of the flush; `acceptingMs` from the start to the point where external WebSocket streams are accepted, see below: it overlaps the other phases and is not part of `totalMs`) and `cores` = `{ diaries, media, groups }`, each `{ kept, dropped }` (the survivors of the re-gate step and the number it dropped; a diary admitted or dropped while the swarm flushes is not counted). No wire change. The swarm uses the loaded `seeder-key.json` pair, so `socket.remotePublicKey` seen by members equals `cert.seeder`. Every seeder `hello` carries `seeder-cert.json` as `cert`. @@ -1579,7 +1579,7 @@ After `run()` resolves or throws, `apps/cli/bin/varanda.js` sets `process.exitCo - `sync [--once] [--timeout-ms n]` -> stdout lines `sync ready`, `peer member `, `peer seeder ` (verified) or `peer seeder não verificado`, `admitted `, `rejected `, `withdrawn `, `have `, `downloaded `, then `sync done` or `sync failed: `; with `--json` one `{ event, ... }` object per line and the SyncResult last (including `{ event: 'peer', role, peerKey, verified }`, `{ event: 'withdrawn', key, peerKey, reason }` and `{ event: 'skipped', key, reason }` events). Exit 0 iff `ok`. - `seed key` -> `{ publicKey }`, stdout `chave do semeador: `; creates `seeder-key.json` when missing, otherwise idempotent (same key). Never prints the secret key. - `seed cert add --cert-file ` -> `{ seeder }`, stdout `certificado do semeador gravado`; parses the file, requires `seeder-key.json` (error `chave do semeador não encontrada (use seed key)`), checks `seederCertForKey(cert, ownNoiseHex, trustRoot)` (error `certificado do semeador inválido ()`), writes `seeder-cert.json`; USAGE `informe --cert-file ` when missing. -- `seed` (run) `[--health-port ] [--health-host ] [--ws-port ] [--ws-host ]` -> loads both files before any network activity: missing key -> `Error('chave do semeador não encontrada (use seed key)')`; missing cert -> `Error('certificado do semeador não encontrado (use seed cert add)')`; cert failing `seederCertForKey(cert, ownNoiseHex, trustRoot)` -> `Error('certificado do semeador inválido ()')` (all exit 1). With `--health-port`, the health endpoint (below) listens BEFORE `start()`, so a busy port fails with `erro: porta em uso` (exit 1) before the data dir or the network is touched (any other listen error: `erro: não foi possível abrir o endpoint de saúde ()`). With `--ws-port`, the WebSocket entry (below) listens right after the health endpoint and also before `start()`: busy port `erro: porta em uso`, other errors `erro: não foi possível abrir o websocket ()`. Stdout lines `health http://:` (only with `--health-port`, first), `ws ws://:/seeder` (only with `--ws-port`, after `health`), `seed ready`, `peer `, `admitted `, `rejected `, `have `; `--json`, one per line: `{ event: 'health', host, port }` | `{ event: 'ws', host, port }` | `{ event: 'ready', topic, admitted }` | `{ event: 'peer', role, peerKey }` (unchanged: seeders do not verify members) | `{ event: 'admitted', key, length }` | `{ event: 'rejected', key, reason }` | `{ event: 'have', key, length }` | `{ event: 'fatal', key, reason: 'purge-failed' }` (section 5) | `{ event: 'media-admitted', key, diary, length }` (human `media admitted `) | `{ event: 'media-rejected', key, diary, reason }` (human `media rejected `; reasons `timeout`, `no-peers`, `media-full`, `header-invalid`, `wrong-diary`, `quota`, `admission-failed`, `unbound`, `fork`, `no-header`) | `{ event: 'warning', key, reason: 'media-full' }` (section 5 "Seeder media admission"). Runs until SIGINT/SIGTERM, then closes the seeder (section 5 "Seeder shutdown") and then the health and WebSocket endpoints, and exits 0 (1 after a fatal purge failure). +- `seed` (run) `[--health-port ] [--health-host ] [--ws-port ] [--ws-host ]` -> loads both files before any network activity: missing key -> `Error('chave do semeador não encontrada (use seed key)')`; missing cert -> `Error('certificado do semeador não encontrado (use seed cert add)')`; cert failing `seederCertForKey(cert, ownNoiseHex, trustRoot)` -> `Error('certificado do semeador inválido ()')` (all exit 1). With `--health-port`, the health endpoint (below) listens BEFORE `start()`, so a busy port fails with `erro: porta em uso` (exit 1) before the data dir or the network is touched (any other listen error: `erro: não foi possível abrir o endpoint de saúde ()`). With `--ws-port`, the WebSocket entry (below) listens right after the health endpoint and also before `start()`: busy port `erro: porta em uso`, other errors `erro: não foi possível abrir o websocket ()`. Stdout lines `health http://:` (only with `--health-port`, first), `ws ws://:/seeder` (only with `--ws-port`, after `health`), `seed ready`, `peer `, `admitted `, `rejected `, `have `, and `stopped` at shutdown; `--json`, one per line: `{ event: 'health', host, port }` | `{ event: 'ws', host, port, at }` | `{ event: 'ready', topic, admitted, phases, cores, at }` | `{ event: 'stopped', drainMs, closeMs?, fatal?, stopListeningAt? }` (section 5 step 5) | `{ event: 'peer', role, peerKey }` (unchanged: seeders do not verify members) | `{ event: 'admitted', key, length }` | `{ event: 'rejected', key, reason }` | `{ event: 'have', key, length }` | `{ event: 'fatal', key, reason: 'purge-failed' }` (section 5) | `{ event: 'media-admitted', key, diary, length }` (human `media admitted `) | `{ event: 'media-rejected', key, diary, reason }` (human `media rejected `; reasons `timeout`, `no-peers`, `media-full`, `header-invalid`, `wrong-diary`, `quota`, `admission-failed`, `unbound`, `fork`, `no-header`) | `{ event: 'warning', key, reason: 'media-full' }` (section 5 "Seeder media admission"). Runs until SIGINT/SIGTERM, then closes the seeder (section 5 "Seeder shutdown") and then the health and WebSocket endpoints, and exits 0 (1 after a fatal purge failure). - `seed status` -> `{ association, publicKey, certificate, admitted, blocklist, blocklistHeld, running }`, read without the data-dir lock and without opening a store, so it also answers while `seed` runs, and it writes nothing (`Seeder.status`). `association` = `config.json`'s (`Seeder.checkConfig`: a missing or non-seeder `config.json` -> `erro: diretório não é de um semeador`, a different `--association` -> `erro: associação diferente da configurada`, exit 1; config.json is never created); `publicKey` = the hex64 of `seeder-key.json` or `null` when the file is missing (an invalid file -> `erro: arquivo de chave inválido`); `certificate` = `'ok'`, `'missing'` (no `seeder-cert.json`), `'malformed'` (unreadable JSON) or the reason of `seederCertForKey(cert, publicKey, association)`; `admitted` = the number of hex64 keys in `admitted.json` (it includes keys a previous run left mid-drop); `blocklist` = `{ seq, date }` of the stored snapshot (`readBlocklist`, an absent or unreadable `blocklist.json` reads as none) or `null`; `blocklistHeld` = `true` when `blocklist` is `null` and a torn file is kept aside (`blocklist.json.ilegivel-`), the case in which a start holds new admissions again (`false` otherwise, and when the directory cannot be listed; it does not predict the first start after a torn file with no copy, or after a missing file with a copy that does not verify, because nothing is kept aside before that start); `running` = `lockHeld(dataDir)` (section 1 rule 9). Exit 0. Stdout, six lines: `associação: `, `chave do semeador: ` or `chave do semeador: ausente (use seed key)`, `certificado: válido` | `certificado: ausente (use seed cert add)` | `certificado: inválido ()`, `diários admitidos: `, `lista de bloqueio: nenhuma` | `lista de bloqueio: seq de `, `estado: em execução` | `estado: parado`. - `seed list` -> `{ admitted: [{ key, length, byteLength, media: [{ key, length, byteLength }] }] }` in `admitted.json` order (each diary with the media cores bound to it; a listed media core whose diary is not listed is not shown, the next start purges it) (`Seeder.list`): `Seeder.checkConfig` as in `seed status`, then `openStore(dataDir)` (the data-dir lock: while `seed` runs -> `erro: diretório de dados em uso`, exit 1) BEFORE `admitted.json` is read; for each hex64 key, when the main store's storage holds its core (`store.storage.hasCore(discoveryKey)`), a read-only session reports `length = core.length` and `byteLength = core.byteLength` (the signed size, the one the quota checks); a listed key with no stored core is reported `0` / `0` and never opened, so listing creates no core. Stdout one line per entry, ` blocos bytes`, followed by one indented line per bound media core, ` mídia blocos bytes`, or `nenhum diário admitido`. - `seed drop ` -> `{ key }`, stdout `diário removido do semeador: ` (`Seeder.drop`): `` is hex64 in any case (lowercased; else USAGE `chave inválida`; missing -> USAGE `informe a chave do diário`); `Seeder.checkConfig`; `openStore(dataDir)` (the lock, as in `seed list`); then, in the startup-drop order of R6.1, `purgeReplica(store, key)` FIRST when the storage holds the core, and only then the key leaves `admitted.json` (`writeJsonAtomic` of `{ v: 1, admitted, media }` with every other entry unchanged). A diary's bound media cores are purged first and leave `media` with it; `` may also be a media core key, which is purged and un-listed alone (the next scan of its diary binds it again). A key neither listed (as a diary or a media core) nor stored -> `erro: diário não está no semeador` (exit 1); a purge failure throws (exit 1) and leaves `admitted.json` untouched. A drop is not a block: the author's next `announce` runs the full gate again, and it is refused only when the key is in the blocklist snapshot (B2: `mod block`, section 3). @@ -1708,7 +1708,7 @@ The same listener answers the engagement index of section 5 ("Seeder engagement ### Seeder logs -`seed` writes its events (above) only to stdout, one per line (`--json`: JSON Lines), and errors to stderr. No line carries a time stamp (the supervisor adds one), an IP address or port of a peer, a block's content, a certificate or a secret, and the health endpoint logs no request. Diary keys and peer keys (Noise public keys, `peerKey8` in human lines) do appear: they are pseudonymous identifiers. Rotation and retention belong to the supervisor (`deploy/seeder/`: Docker `json-file` with `max-size` / `max-file`, journald `MaxRetentionSec`); the values shipped there are provisional pending the legal opinion on Marco Civil Art. 15 access logs (issue #38). The README section "Política de registros" is the operator-facing policy. +`seed` writes its events (above) only to stdout, one per line (`--json`: JSON Lines), and errors to stderr. No line carries a time stamp (the supervisor adds one), except the epoch ms `at` of `ws` and `ready` and `stopListeningAt` of `stopped`, which time a deploy; no line carries an IP address or port of a peer, a block's content, a certificate or a secret, and the health endpoint logs no request. Diary keys and peer keys (Noise public keys, `peerKey8` in human lines) do appear: they are pseudonymous identifiers. Rotation and retention belong to the supervisor (`deploy/seeder/`: Docker `json-file` with `max-size` / `max-file`, journald `MaxRetentionSec`); the values shipped there are provisional pending the legal opinion on Marco Civil Art. 15 access logs (issue #38). The README section "Política de registros" is the operator-facing policy. ### FeedItem diff --git a/docs/verification/feat-seeder-shutdown-timing.md b/docs/verification/feat-seeder-shutdown-timing.md new file mode 100644 index 00000000..b6480fb7 --- /dev/null +++ b/docs/verification/feat-seeder-shutdown-timing.md @@ -0,0 +1,22 @@ +# Medição do desligamento do semeador (branch feat/seeder-shutdown-timing) + +Mudança: só medição, sem mudança de comportamento. Os eventos `ws` e `ready` do log JSON de `seed` ganham `at` (instante absoluto em ms desde 1970) e, em SIGTERM, o evento `stopped` registra `drainMs` (do sinal ao fim do drain do WebSocket), `closeMs` (do sinal ao fim do fechamento do armazenamento) e `stopListeningAt` (instante em que a escuta WebSocket parou). Com isso, uma implantação dá: (a) o tempo de fechamento C = `closeMs` do processo antigo; (b) o tempo da porta sem escuta = `ws.at` do processo novo menos `stopListeningAt` do antigo. Sem `--ws-port`, `stopped` não traz `stopListeningAt`; se o semeador se fechou sozinho (falha fatal), `stopped` traz `fatal: true` em vez de `closeMs`. Descrição em `docs/protocol.md` (seção 5, passo 5 da partida do semeador, e o item `seed` da seção 7). + +## Comandos de teste + +```sh +node apps/cli/test/seed-shutdown-timing.test.js +node apps/cli/test/seed-ws-drain.test.js +node packages/core/test/seeder-start-timing.test.js +node apps/cli/test/seed-ops.test.js +node apps/cli/test/changelog.test.js +node apps/cli/test/readme-help.test.js +``` + +## Limites conhecidos + +- [ ] Os números vêm de uma única implantação, não de uma distribuição. +- [ ] O tempo da porta sem escuta precisa dos logs dos dois contêineres (o antigo e o novo) e supõe relógios da mesma máquina; entre máquinas diferentes o desvio de relógio entra na conta. +- [ ] `stopListeningAt` é lido logo antes de chamar o drain, que para de escutar em seguida; o erro é de milissegundos. +- [ ] Um SIGTERM que chega antes de `seed ready` conta o resto da partida em `drainMs` e `closeMs` (os dois contam a partir do sinal); uma amostra assim superestima C. +- [ ] O caminho fatal (`fatal: true`, sem `closeMs`) não tem teste próprio; o teste novo cobre só o SIGTERM. diff --git a/packages/core/lib/seeder.js b/packages/core/lib/seeder.js index 275acef9..5ebbc518 100644 --- a/packages/core/lib/seeder.js +++ b/packages/core/lib/seeder.js @@ -2090,7 +2090,7 @@ class Seeder { media: { kept: mediaKept, dropped: mediaBefore - mediaKept }, groups: { kept: groupsKept, dropped: groupsBefore - groupsKept } } - this.log({ event: 'ready', topic, admitted, phases, cores }) + this.log({ event: 'ready', topic, admitted, phases, cores, at: Date.now() }) // Background pass (never inside start()): scan every served diary for // media-core records, one diary at a time (_scanQueue), and index it on // the separate index queue (`indexing` stays true until every diary