Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions docs/rpc.md

Large diffs are not rendered by default.

63 changes: 63 additions & 0 deletions docs/verification/feat-varandinha-node.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Varandinha, o nó (PR feat/varandinha-node)

Este PR acrescenta o contrato `garden.*` ao `@varanda/rpc` (os métodos `garden.set`, `garden.state`, `garden.play` e `garden.help` em `packages/rpc/lib/methods.js` e as seções 5.157 a 5.160 de `docs/rpc.md`), os stubs do nó do core (`packages/core/lib/session.js` responde aos quatro com `USAGE` `'leitura sob demanda só na versão web'`), as operações do nó do navegador (`gardenOwn`, `gardenSet`, `gardenLeave`, `gardenPlay`, `gardenHelpCheck` e `gardenHelp` em `packages/web-member/lib/member-ops.js`), os quatro handlers e a checagem do vaso do dono fora da cadeia (`gardenTarget`, que falha fechado) em `packages/web-member/lib/session.js`, e um teste de ponta a ponta com um semeador local (`packages/web-member/test/garden-e2e.test.js`).

## Handlers do nó do navegador (`packages/web-member/lib/session.js`)

Rodado no Node 24.22.1, sobre 2fd8e2a2 (a ponta de feat/varandinha-index, o PR de baixo da pilha), com as mudanças deste PR ainda fora de commit:

- `npx standard packages/web-member/lib/session.js packages/web-member/test/garden-e2e.test.js`
resultado: passou.
- `npm test -w packages/web-member -- test/garden-e2e.test.js`
resultado: passou, 1/1 teste e 51/51 asserções, 1 arquivo, 0 falha.
- `npm test -w packages/web-member -- test/garden.test.js test/visits-e2e.test.js test/scraps.test.js`
resultado: passou, 3 arquivos, 0 falha; `garden.test.js` 20/20 testes e 130/130 asserções, `visits-e2e.test.js` 2/2 e 40/40, `scraps.test.js` 5/5 e 49/49.

O que `packages/web-member/test/garden-e2e.test.js` cobre (um `Seeder` real atrás de `startSeedWs`, nós do navegador reais sobre armazenamento em memória, DHT local presa a `127.0.0.1` e diretórios temporários):

- A entra na Varandinha (`garden.set` ligado); entrar de novo não escreve nada. A planta manjericão no vaso 0 numa jogada; `garden.state` devolve o estado salvo e `savesToday` 1.
- B segue A e C; antes de ligar a própria Varandinha a rega é recusada com `'ligue a Varandinha para regar'`; regar a si mesmo, `'não dá para regar a própria varanda'`. D, que liga a Varandinha mas não segue A, recebe `'você só rega a varanda de quem você segue'`.
- Com a sincronização de B rodando (as espiadas saem dela): C, que nunca entrou, `'esta pessoa não está na Varandinha'`; o vaso 3 vazio de A, `'este vaso não tem planta para regar'`.
- Falha fechada: com a resposta do índice `/index/garden/<A>` trocando os ponteiros `on` e `state` (cada um aponta para um bloco de outro tipo), marcada como `indexing`, ou sem resposta, a rega responde `NOT_FOUND` `'semeador indisponível'`. O índice mente pela opção `fetchMedia` do nó, que repassa à rota real do semeador.
- A rega de B no vaso 0 de A dá certo e grava um `garden-help` com `to` e `pot`; a segunda rega à mesma varanda no mesmo dia de Brasília é recusada com `'você já regou esta varanda hoje'`; `garden.state` de B mostra `helpsToday` 1 e a rega em `given`.
- Na hora 3 (o `Date.now` do processo adiantado `GARDEN_WATER_GAP_MS` mais um minuto, como em `dm-moment-e2e.test.js`), A rega o manjericão: `w` 1 e `water` igual ao `at` do novo estado.
- A sai (`garden.set` desligado): `garden.state` com `on` falso, `state` nulo e `given` vazio; sair de novo não escreve nada. B sai e a rega some de `given` e de `helpsToday`.
- Toda recusa confere que o diário de quem chamou ficou do mesmo tamanho.

Não coberto no teste de ponta a ponta: uma página como `to` (`'páginas não têm Varandinha'`). Registrar uma página exige o serviço de conta, que assina e anexa o diário da página com a chave dela; o teste não sobe esse serviço. A checagem é a mesma de `scrap.write` e `fan.set` (um `page-roster` no bloco 1 ou 2 espiado).

Conferido que o teste falha sem a checagem: com a chamada a `gardenTarget` tirada de `garden.help`, o arquivo falhou nas recusas de C, do vaso vazio e nos três casos de falha fechada (asserções 27 a 36); com a chamada de volta, passou de novo.

Conferido à mão que as seções 5.157 a 5.160 de `docs/rpc.md` descrevem a ordem das checagens, a saída sem nada a fazer, a leitura de `garden.state` sem a chave destravada e a resposta de falha fechada do código, e que não há travessão (U+2014) nem meia-risca (U+2013) nas linhas novas.

## Contrato, stubs e operações (depois da revisão e da sincronização)

Rodado no Node 24.22.1, sobre 9dd4ad75 (a ponta de feat/varandinha-index, já com a `main` em 063a3590), com as mudanças deste PR ainda fora de commit. As seções do `docs/rpc.md` passaram de 5.152 a 5.155 para 5.156 a 5.159, porque a `main` usou 5.152 a 5.155 para `device.*`, e depois para 5.157 a 5.160, porque a `main` usou 5.156 para `dm.historyCopy`.

- `npx standard packages/rpc/lib/methods.js packages/rpc/test/methods.test.js packages/core/lib/session.js packages/core/test/engagement-session.test.js packages/web-member/lib/member-ops.js packages/web-member/lib/session.js packages/web-member/test/garden.test.js packages/web-member/test/garden-e2e.test.js`
resultado: passou.
- `node packages/rpc/test/methods.test.js`
resultado: passou, 7459/7459 asserções.
- `node packages/core/test/engagement-session.test.js`
resultado: passou, 136/136 asserções (os quatro `garden.*` respondem `USAGE` `'leitura sob demanda só na versão web'` sem escrever bloco; parâmetro a mais, `'parâmetro desconhecido'`).
- `node packages/web-member/test/garden.test.js`
resultado: passou, 22/22 testes e 160/160 asserções. Inclui `gardenTargetSeqs` (a lista da espiada, ou nada para recusar) e `gardenTargetVerdict` (20 casos de espiada montada: página, bloco 1 ou 2 faltando, bandeira desligada, de outro tipo ou datada mais de 24 h à frente, estado ausente, abaixo da bandeira, datado à frente, vaso vazio, plantado depois de agora, maduro).
- `node packages/web-member/test/garden-e2e.test.js`
resultado: passou, 51/51 asserções.
- `node packages/web-member/test/session-devices.test.js`
resultado: passou, 16/16 asserções (o arquivo da `main` que divide `session.js` com este PR).

## CI completa

Rodado na raiz, no Node 24.22.1, sobre 9dd4ad75 com as mudanças deste PR, na ordem da CI:

- `npm ci --ignore-scripts`
resultado: passou.
- `npm run lint`
resultado: passou.
- `npm test -- --affected=origin/main`
resultado: passou, 821 arquivos de teste, 0 falha.
- `npm run demo`
resultado: passou, terminou com "DEMO OK".

Não rodado: o Node 20 (a CI roda os dois); um navegador de verdade (os testes usam o nó do navegador sobre armazenamento em memória).
16 changes: 16 additions & 0 deletions packages/core/lib/session.js
Original file line number Diff line number Diff line change
Expand Up @@ -1107,6 +1107,22 @@ function createSession ({
return r
}),

// Varandinha (docs/rpc.md garden.*): the help check needs peeks of the
// owner's diary and the seeder index the core node does not read; refused
// the same way, nothing written.
'garden.set': serial(async () => {
throw new UsageError(PEEK_WEB_ONLY)
}),
'garden.state': serial(async () => {
throw new UsageError(PEEK_WEB_ONLY)
}),
'garden.play': serial(async () => {
throw new UsageError(PEEK_WEB_ONLY)
}),
'garden.help': serial(async () => {
throw new UsageError(PEEK_WEB_ONLY)
}),

// Foruns e enquetes (docs/rpc.md): a vote checks the poll post with a
// peek the core node does not make; refused, nothing written.
'choice.set': serial(async () => {
Expand Down
19 changes: 19 additions & 0 deletions packages/core/test/engagement-session.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,25 @@ test('the visitas methods are refused on the node session, nothing written', asy
t.alike(await failure(m.call('visits.note', { key: 'zz' })), { code: 'USAGE', message: 'parâmetro inválido: key' })
})

test('the varandinha methods are refused on the node session, nothing written', async (t) => {
const NO = { code: 'USAGE', message: 'leitura sob demanda só na versão web' }
const m = await member(t)
const before = await m.call('log.read')
t.alike(await failure(m.call('garden.set', { on: true })), NO)
t.alike(await failure(m.call('garden.set', { on: false })), NO)
t.alike(await failure(m.call('garden.state', {})), NO)
t.alike(await failure(m.call('garden.play', { acts: [{ op: 'plant', pot: 0, plant: 'manjericao' }] })), NO)
t.alike(await failure(m.call('garden.help', { to: OTHER, pot: 0 })), NO)
t.alike(await m.call('log.read'), before, 'nothing written')
t.alike(m.session.internal, [])
const UNKNOWN = { code: 'USAGE', message: 'parâmetro desconhecido' }
t.alike(await failure(m.call('garden.set', { on: true, extra: 1 })), UNKNOWN)
t.alike(await failure(m.call('garden.help', { to: OTHER, pot: 0, at: '2026-11-16T00:00:00.000Z' })), UNKNOWN)
t.alike(await failure(m.call('garden.set', { on: 'sim' })), { code: 'USAGE', message: 'parâmetro inválido: on' })
t.alike(await failure(m.call('garden.help', { to: 'zz', pot: 0 })), { code: 'USAGE', message: 'parâmetro inválido: to' })
t.alike(await failure(m.call('garden.help', { to: OTHER, pot: 6 })), { code: 'USAGE', message: 'parâmetro inválido: pot' })
})

test('the enquete methods are refused on the node session, nothing written', async (t) => {
const NO = { code: 'USAGE', message: 'leitura sob demanda só na versão web' }
const m = await member(t)
Expand Down
10 changes: 10 additions & 0 deletions packages/rpc/lib/methods.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ const { isReaction } = require('./reaction')
const PX = require('./profile-extra')
const { isPoll, isPick } = require('./poll')
const { isEvent, copyEvent } = require('./event')
const garden = require('./garden')

const HEX64 = /^[0-9a-f]{64}$/
const REF = /^([0-9a-f]{64}):(0|[1-9][0-9]*)$/
Expand Down Expand Up @@ -1604,6 +1605,15 @@ const SPECS = {
'visits.list': { fields: none },
'visits.clear': { fields: none, mutating: true },
'visits.note': { fields: { key: req(isKey) }, mutating: true },
// Varandinha, browser node only (docs/rpc.md 5.157 to 5.160). garden.set
// turns the caller's own game on or off; garden.state reads it; garden.play
// applies one batch of acts as one save; garden.help waters pot `pot` of
// the balcony of `to`, a diary key. No date parameter: the node sets every
// `at` from its own clock.
'garden.set': { fields: { on: req(isBool) }, mutating: true },
'garden.state': { fields: none },
'garden.play': { fields: { acts: req(garden.isActs) }, mutating: true },
'garden.help': { fields: { to: req(isKey), pot: req(garden.isPotIndex) }, mutating: true },
// Páginas (docs/rpc.md 5.84 to 5.87). page.sign signs a page statement or
// a page record and appends nothing; the node fills in member, actor and
// association, so a caller never chooses the bytes. The exact op of each
Expand Down
54 changes: 52 additions & 2 deletions packages/rpc/test/methods.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ test('method list and mutating set', (t) => {
t.alike([...METHODS].sort(), [
'account.sign', 'age.proof', 'age.sign', 'appeal.sign', 'block.list', 'block.set', 'cert.add', 'choice.mine', 'choice.set', 'community.admin', 'community.admit', 'community.ban', 'community.create', 'community.info', 'community.invitePolicy', 'community.join', 'community.leave', 'community.list', 'community.members', 'community.meta', 'community.removeGroup', 'community.requests', 'device.disconnect', 'device.hello', 'device.list', 'device.reconnect', 'diary.peek',
'dm.enable', 'dm.historyCopy', 'dm.list', 'dm.lookup', 'dm.pageDraft', 'dm.pageForget', 'dm.pageGenerate', 'dm.pageLegacyBlocks', 'dm.pageLegacyChunk', 'dm.pageSecrets', 'dm.pageSend', 'dm.pageShare', 'dm.pull', 'dm.putMedia', 'dm.react', 'dm.reportSign', 'dm.seen', 'dm.send', 'dm.set', 'dm.thread', 'engagement.read', 'fan.set', 'feed.read', 'follow.add', 'follow.list', 'follow.remove',
'group.admin', 'group.admit', 'group.ban', 'group.choose', 'group.create', 'group.events', 'group.hide', 'group.info', 'group.invitePolicy', 'group.join', 'group.leave', 'group.list', 'group.members',
'garden.help', 'garden.play', 'garden.set', 'garden.state', 'group.admin', 'group.admit', 'group.ban', 'group.choose', 'group.create', 'group.events', 'group.hide', 'group.info', 'group.invitePolicy', 'group.join', 'group.leave', 'group.list', 'group.members',
'group.meta', 'group.post', 'group.react', 'group.reactors', 'group.read', 'group.rekey', 'group.requests', 'group.seal', 'group.seen', 'group.topics', 'group.voters',
'identity.clear', 'identity.create', 'identity.forget', 'identity.install', 'identity.recoveryBind', 'identity.recoveryLookup', 'identity.recoveryOpen', 'identity.recoveryWrap',
'identity.reset', 'identity.sessionSaved', 'identity.show', 'identity.status', 'invite.sign', 'inviteCard.sign', 'inviteCard.verify', 'like.set', 'listing.consent', 'listing.create', 'listing.delete', 'listing.edit', 'listing.mine', 'listing.rate', 'listing.ratings', 'listing.status', 'log.read', 'media.readFile', 'media.uploadFile', 'moment.create', 'moment.delete', 'moment.lookup', 'moment.putMedia', 'moment.seen', 'moments.read', 'moments.seen', 'node.close', 'node.info', 'notices.list', 'outbox.open', 'outbox.seal',
Expand All @@ -29,7 +29,7 @@ test('method list and mutating set', (t) => {
'scrap.delete', 'scrap.hide', 'scrap.wall', 'scrap.write', 'seen.merge', 'seen.onceKey', 'seen.sign', 'session.open', 'sync.start', 'sync.status', 'sync.stop', 'terms.sign', 'testimonial.decide', 'testimonial.delete', 'testimonial.pending', 'testimonial.show', 'testimonial.write', 'top.set', 'username.add', 'visits.clear', 'visits.list', 'visits.note', 'visits.set', 'visits.state'
])
t.alike([...MUTATING].sort(), [
'block.set', 'cert.add', 'choice.set', 'community.admin', 'community.admit', 'community.ban', 'community.create', 'community.invitePolicy', 'community.join', 'community.leave', 'community.meta', 'community.removeGroup', 'device.disconnect', 'device.hello', 'device.reconnect', 'dm.enable', 'dm.historyCopy', 'dm.pageForget', 'dm.pageLegacyChunk', 'dm.pageSecrets', 'dm.pageSend', 'dm.putMedia', 'dm.react', 'dm.send', 'dm.set', 'fan.set', 'follow.add', 'follow.remove', 'group.admin', 'group.admit', 'group.ban',
'block.set', 'cert.add', 'choice.set', 'community.admin', 'community.admit', 'community.ban', 'community.create', 'community.invitePolicy', 'community.join', 'community.leave', 'community.meta', 'community.removeGroup', 'device.disconnect', 'device.hello', 'device.reconnect', 'dm.enable', 'dm.historyCopy', 'dm.pageForget', 'dm.pageLegacyChunk', 'dm.pageSecrets', 'dm.pageSend', 'dm.putMedia', 'dm.react', 'dm.send', 'dm.set', 'fan.set', 'follow.add', 'follow.remove', 'garden.help', 'garden.play', 'garden.set', 'group.admin', 'group.admit', 'group.ban',
'group.choose', 'group.create', 'group.hide', 'group.invitePolicy', 'group.join', 'group.leave', 'group.meta', 'group.post', 'group.react', 'group.rekey', 'identity.clear', 'identity.create', 'identity.forget',
'identity.install', 'identity.recoveryBind', 'identity.reset', 'identity.sessionSaved', 'like.set', 'listing.create', 'listing.delete', 'listing.edit', 'listing.rate', 'listing.status', 'media.uploadFile', 'moment.create', 'moment.delete', 'moment.putMedia', 'node.close', 'page.register', 'post.create', 'post.delete',
'post.quote', 'post.reply', 'post.share', 'post.unshare',
Expand Down Expand Up @@ -3181,6 +3181,56 @@ test('visits: limits and the five methods', (t) => {
bad(t, 'visits.note', [KEY], 'array params')
})

test('garden: the four methods', (t) => {
const G = require('../lib/garden')
t.is(G.GARDEN_ACTS_MAX, 24)
t.is(G.GARDEN_POTS, 6)
for (const m of ['garden.set', 'garden.play', 'garden.help']) t.ok(isMutating(m), m + ' mutates')
t.absent(isMutating('garden.state'), 'garden.state only reads')

ok(t, 'garden.set', { on: true }, { on: true })
ok(t, 'garden.set', { on: false }, { on: false })
for (const on of [undefined, null, 1, 0, 'true', 'false', {}, []]) bad(t, 'garden.set', { on }, 'on ' + String(on))
bad(t, 'garden.set', {}, 'missing on')
bad(t, 'garden.set', { on: true, at: '2026-11-16T12:00:00.000Z' }, 'no at param on garden.set')

ok(t, 'garden.state', {}, {})
bad(t, 'garden.state', { extra: 1 }, 'extra field')
bad(t, 'garden.state', { on: true }, 'no on param on garden.state')

const acts = [
{ op: 'plant', pot: 0, plant: 'manjericao' },
{ op: 'water', pot: 0 },
{ op: 'harvest', pot: 0 },
{ op: 'clear', pot: 5 }
]
ok(t, 'garden.play', { acts }, { acts })
for (const p of G.GARDEN_PLANTS) ok(t, 'garden.play', { acts: [{ op: 'plant', pot: 1, plant: p.id }] })
ok(t, 'garden.play', { acts: Array.from({ length: 24 }, () => ({ op: 'water', pot: 2 })) })
bad(t, 'garden.play', {}, 'missing acts')
bad(t, 'garden.play', { acts: [] }, 'empty acts')
bad(t, 'garden.play', { acts: Array.from({ length: 25 }, () => ({ op: 'water', pot: 2 })) }, '25 acts')
bad(t, 'garden.play', { acts: [{ op: 'dig', pot: 0 }] }, 'unknown op')
bad(t, 'garden.play', { acts: [{ op: 'water', pot: 0, extra: 1 }] }, 'act with an extra key')
bad(t, 'garden.play', { acts: [{ op: 'water', pot: 0, plant: 'tomate' }] }, 'water with a plant key')
bad(t, 'garden.play', { acts: [{ op: 'plant', pot: 0 }] }, 'plant without a plant id')
bad(t, 'garden.play', { acts: [{ op: 'plant', pot: 0, plant: 'rosa' }] }, 'unknown plant id')
bad(t, 'garden.play', { acts: [{ op: 'water', pot: 6 }] }, 'act pot 6')
bad(t, 'garden.play', { acts: [{ op: 'water', pot: 0 }, { op: 'dig', pot: 0 }] }, 'one bad act refuses the batch')
for (const v of [null, 1, 'water', { op: 'water', pot: 0 }]) bad(t, 'garden.play', { acts: v }, 'acts ' + JSON.stringify(v))
bad(t, 'garden.play', { acts, at: '2026-11-16T12:00:00.000Z' }, 'no at param on garden.play')
t.is(validateParams('garden.play', { acts, at: '2026-11-16T12:00:00.000Z' }).message, 'parâmetro desconhecido')

ok(t, 'garden.help', { to: KEY, pot: 0 }, { to: KEY, pot: 0 })
ok(t, 'garden.help', { to: KEY, pot: 5 }, { to: KEY, pot: 5 })
for (const pot of [6, -1, 1.5, '0', null, NaN, Infinity, true]) bad(t, 'garden.help', { to: KEY, pot }, 'pot ' + String(pot))
for (const to of [KEY.toUpperCase(), KEY.slice(1), KEY + 'a', 'g'.repeat(64), '', null, 1, [KEY]]) bad(t, 'garden.help', { to, pot: 0 }, 'to ' + JSON.stringify(to))
bad(t, 'garden.help', { pot: 0 }, 'missing to')
bad(t, 'garden.help', { to: KEY }, 'missing pot')
bad(t, 'garden.help', { to: KEY, pot: 0, at: '2026-11-16T12:00:00.000Z' }, 'no at param on garden.help')
bad(t, 'garden.help', { to: KEY, pot: 0, extra: 1 }, 'extra field')
})

test('choice.set and choice.mine', (t) => {
t.ok(isMutating('choice.set'))
t.absent(isMutating('choice.mine'))
Expand Down
Loading
Loading