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
14 changes: 14 additions & 0 deletions docs/protocol.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/rpc.md
Original file line number Diff line number Diff line change
Expand Up @@ -1660,7 +1660,7 @@ This is the `isUnsafe` set of `packages/core/lib/safe.js` plus the three marks a

## 12. Module exports (`require('@varanda/rpc')`)

`index.js` re-exports: every constant of section 2 (including `FEED_INCOMPLETE_MAX`, `PEEK_LIMIT_DEFAULT`, `PEEK_LIMIT_MAX`, `PROFILE_LIMIT_MAX`, `ENGAGEMENT_LIMIT_MAX`, `PEEK_SEQS_MAX`, `PEEK_TIMEOUT_MS`, `NOTICES_LIMIT_DEFAULT`, `NOTICES_LIMIT_MAX`, `AVATAR_SIDE`, `MAX_AVATAR_BLOCKS`, `MAX_AVATAR_BYTES`, `AVATAR_MIMES`, `GROUP_LIMIT_DEFAULT`, `GROUP_LIMIT_MAX`, `GROUP_MEMBERS_LIMIT_MAX`, `GROUP_REACTIONS_MAX`, `GROUP_REACTORS_MAX`, `MAX_GROUP_NAME`, `MAX_GROUP_CUTS`, `MAX_GROUPS_PER_COMMUNITY`, `COMMUNITY_LIST_MAX`, `MAX_DM_MEDIA`, `DM_MEDIA_CHUNK_BYTES`, `DM_MEDIA_MAX_CHUNKS`, `DM_MEDIA_MAC_BYTES`, `DM_THREAD_LIMIT_DEFAULT` and `DM_THREAD_LIMIT_MAX`); the DM inner helpers of `lib/dm-budget.js` (5.75): `DM_INNER_KEYS`, `DM_INNER_KEYS_V2`, `DM_INNER_KEYS_V4`, `DM_INNER_KEYS_V7`, `DM_BLOB_KEYS`, `canonicalBlobDescriptor`, `DM_TARGET_KEYS`, `DM_MEDIA_KEYS`, `DM_CARD_KEYS`, `dmInnerVersion`, `canonicalDmInnerJson`, `dmTextBytes` and `dmTextBudget`; the signup invite card helpers of `lib/invite-card.js` (5.101): `INVITE_CARD_MAX_URL`, `FRAGMENT_MARK`, `NAME_MAX`, `MESSAGE_MAX_BYTES`, `DESIGNS`, `REGIONS`, `designIndex`, `designAt`, `canonicalInviteCardText`, `isInviteCode`, `isInviteCardExpires`, `buildInviteCardUrl`, `parseInviteCardUrl` and `messageRoom`; the link card rules of `lib/link-card.js` (protocol section 2, "Link cards"): `MAX_CARD_URL`, `MAX_CARD_TITLE`, `MAX_CARD_DESC`, `MAX_CARD_IMAGE_BYTES`, `isCardForbiddenChar`, `cardTextLength`, `cardText` and `cardUrlHost`; the momento music rules of `lib/music.js` (5.113): `MOMENT_MUSIC_KEYS`, `MOMENT_SNIPPET_S` and `isMomentMusic`; `feira` (`lib/feira.js`, the Feira rules of protocol sections 2 and 15: constants, shape checks, `unitAllowed`, `cityKey`, `priceLabel`, `statusLabel`, `dealPayload` and `parseOfferRef`); `mediaBounds`, `mediaSize`, `MAX_MEDIA_PIXELS`, `MAX_MEDIA_FRAMES` and `MAX_MEDIA_TOTAL_PIXELS` (`lib/media-bounds.js`, the image header bounds of protocol section 13; `mediaSize(bytes, mime)` reads the same headers and returns `{ width, height, frames }` without the dimension and pixel bounds, or `null` like `mediaBounds` (more than `MAX_MEDIA_FRAMES` frames is still `null`), for a caller with its own cap, such as the web photo encoder); `findMentions`, `mentionTokens`, `mentionSegments`, `activeMention` and `MENTION_MAX` (`lib/mentions.js`, the `@nome` grammar of protocol section 2; `NOTICE_KINDS` is not exported here, it lives in `@varanda/core` `lib/notices-v2.js`, and `NOTICE_V3_KINDS` (the v3 kinds, with `like` and `repost`) in `lib/notices-v3.js`); every export of section 7; `METHODS` (array, including `recovery.sign` and the IPC-only `identity.recoveryLookup`, `identity.recoveryOpen`, `identity.recoveryWrap` and `identity.recoveryBind`, 5.90 to 5.94; only `identity.recoveryBind` is in `MUTATING`), `MUTATING` (frozen array), `isMethod`, `isMutating`, `validateParams`, `isKey`, `isRef(str, minSeq = 1)`; `isReaction`, `REACTION_MAX_POINTS` (8) and `REACTION_MAX_BYTES` (40) (`lib/reaction.js`, the one-emoji rule of a `group-react` record, protocol section 10); `EVENTS` (`['sync.started', 'sync.event', 'sync.stopped', 'warning', 'follows.changed', 'groups.changed', 'dm.changed', 'dm.sending', 'seen.changed', 'dm.pageKeyMismatch', 'devices.changed', 'dm.copyProgress', 'dm.copyImported']`), `STOP_REASONS` (`['done', 'stopped', 'preempted', 'timeout', 'error', 'idle']`), `validateRequest`, `validateResponse`, `validateEvent`; `encodeFrame`, `createFrameDecoder`, `parseMessage`; `displayText`, `utf8ByteLength`, `utf8Encode`, `utf8Decode`, `clipText(str, max)`; `tokensEqual`; `capList`, `capSyncResult`; `createServerDispatcher`, `createClient`. Files: `lib/limits.js`, `lib/errors.js`, `lib/methods.js`, `lib/mentions.js`, `lib/dm-budget.js`, `lib/link-card.js`, `lib/invite-card.js`, `lib/reaction.js`, `lib/media-bounds.js`, `lib/envelope.js`, `lib/framing.js`, `lib/text.js`, `lib/token.js`, `lib/server.js`, `lib/client.js`.
`index.js` re-exports: every constant of section 2 (including `FEED_INCOMPLETE_MAX`, `PEEK_LIMIT_DEFAULT`, `PEEK_LIMIT_MAX`, `PROFILE_LIMIT_MAX`, `ENGAGEMENT_LIMIT_MAX`, `PEEK_SEQS_MAX`, `PEEK_TIMEOUT_MS`, `NOTICES_LIMIT_DEFAULT`, `NOTICES_LIMIT_MAX`, `AVATAR_SIDE`, `MAX_AVATAR_BLOCKS`, `MAX_AVATAR_BYTES`, `AVATAR_MIMES`, `GROUP_LIMIT_DEFAULT`, `GROUP_LIMIT_MAX`, `GROUP_MEMBERS_LIMIT_MAX`, `GROUP_REACTIONS_MAX`, `GROUP_REACTORS_MAX`, `MAX_GROUP_NAME`, `MAX_GROUP_CUTS`, `MAX_GROUPS_PER_COMMUNITY`, `COMMUNITY_LIST_MAX`, `MAX_DM_MEDIA`, `DM_MEDIA_CHUNK_BYTES`, `DM_MEDIA_MAX_CHUNKS`, `DM_MEDIA_MAC_BYTES`, `DM_THREAD_LIMIT_DEFAULT` and `DM_THREAD_LIMIT_MAX`); the DM inner helpers of `lib/dm-budget.js` (5.75): `DM_INNER_KEYS`, `DM_INNER_KEYS_V2`, `DM_INNER_KEYS_V4`, `DM_INNER_KEYS_V7`, `DM_BLOB_KEYS`, `canonicalBlobDescriptor`, `DM_TARGET_KEYS`, `DM_MEDIA_KEYS`, `DM_CARD_KEYS`, `dmInnerVersion`, `canonicalDmInnerJson`, `dmTextBytes` and `dmTextBudget`; the signup invite card helpers of `lib/invite-card.js` (5.101): `INVITE_CARD_MAX_URL`, `FRAGMENT_MARK`, `NAME_MAX`, `MESSAGE_MAX_BYTES`, `DESIGNS`, `REGIONS`, `designIndex`, `designAt`, `canonicalInviteCardText`, `isInviteCode`, `isInviteCardExpires`, `buildInviteCardUrl`, `parseInviteCardUrl` and `messageRoom`; the link card rules of `lib/link-card.js` (protocol section 2, "Link cards"): `MAX_CARD_URL`, `MAX_CARD_TITLE`, `MAX_CARD_DESC`, `MAX_CARD_IMAGE_BYTES`, `isCardForbiddenChar`, `cardTextLength`, `cardText` and `cardUrlHost`; the momento music rules of `lib/music.js` (5.113): `MOMENT_MUSIC_KEYS`, `MOMENT_SNIPPET_S` and `isMomentMusic`; `feira` (`lib/feira.js`, the Feira rules of protocol sections 2 and 15: constants, shape checks, `unitAllowed`, `cityKey`, `priceLabel`, `statusLabel`, `dealPayload` and `parseOfferRef`); `garden` (`lib/garden.js`, the Varandinha rules shared by core, the node and the app: the `GARDEN_*` constants (six pots, the six plants with their `ripeMs`, the water, help and daily caps, the help window, the Brasília day math and the 24 h future tolerance), the shape checks `isPlantId`, `isPotIndex`, `isPot(v, recordAtMs)`, `isPots`, `isSaveOrdinal`, `isAct`, `isActs` and `isFollowOf(record, owner)`, `gardenDay`, `dayStart`, growth under the reader clock `potView(pot, now, { received, given })`, the play reducer `applyActs(state, acts, now, { received, given })` (watering judged with no neighbour boosts, harvest under the passed per-pot counts, one invalid act refuses the batch), the folds `foldHelps`, `foldGiven` and `foldBalcony`, `helpAllowed` and `saveOrdinal`; nothing throws, no input is mutated, the clock is always a `now` argument in ms); `mediaBounds`, `mediaSize`, `MAX_MEDIA_PIXELS`, `MAX_MEDIA_FRAMES` and `MAX_MEDIA_TOTAL_PIXELS` (`lib/media-bounds.js`, the image header bounds of protocol section 13; `mediaSize(bytes, mime)` reads the same headers and returns `{ width, height, frames }` without the dimension and pixel bounds, or `null` like `mediaBounds` (more than `MAX_MEDIA_FRAMES` frames is still `null`), for a caller with its own cap, such as the web photo encoder); `findMentions`, `mentionTokens`, `mentionSegments`, `activeMention` and `MENTION_MAX` (`lib/mentions.js`, the `@nome` grammar of protocol section 2; `NOTICE_KINDS` is not exported here, it lives in `@varanda/core` `lib/notices-v2.js`, and `NOTICE_V3_KINDS` (the v3 kinds, with `like` and `repost`) in `lib/notices-v3.js`); every export of section 7; `METHODS` (array, including `recovery.sign` and the IPC-only `identity.recoveryLookup`, `identity.recoveryOpen`, `identity.recoveryWrap` and `identity.recoveryBind`, 5.90 to 5.94; only `identity.recoveryBind` is in `MUTATING`), `MUTATING` (frozen array), `isMethod`, `isMutating`, `validateParams`, `isKey`, `isRef(str, minSeq = 1)`; `isReaction`, `REACTION_MAX_POINTS` (8) and `REACTION_MAX_BYTES` (40) (`lib/reaction.js`, the one-emoji rule of a `group-react` record, protocol section 10); `EVENTS` (`['sync.started', 'sync.event', 'sync.stopped', 'warning', 'follows.changed', 'groups.changed', 'dm.changed', 'dm.sending', 'seen.changed', 'dm.pageKeyMismatch', 'devices.changed', 'dm.copyProgress', 'dm.copyImported']`), `STOP_REASONS` (`['done', 'stopped', 'preempted', 'timeout', 'error', 'idle']`), `validateRequest`, `validateResponse`, `validateEvent`; `encodeFrame`, `createFrameDecoder`, `parseMessage`; `displayText`, `utf8ByteLength`, `utf8Encode`, `utf8Decode`, `clipText(str, max)`; `tokensEqual`; `capList`, `capSyncResult`; `createServerDispatcher`, `createClient`. Files: `lib/limits.js`, `lib/errors.js`, `lib/methods.js`, `lib/mentions.js`, `lib/dm-budget.js`, `lib/link-card.js`, `lib/invite-card.js`, `lib/reaction.js`, `lib/media-bounds.js`, `lib/envelope.js`, `lib/framing.js`, `lib/text.js`, `lib/token.js`, `lib/server.js`, `lib/client.js`.

## 13. Known limits (v1)

Expand Down
17 changes: 17 additions & 0 deletions docs/verification/feat-varandinha-records.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Varandinha, registros (PR feat/varandinha-records)

Este PR acrescenta as regras puras de `packages/rpc/lib/garden.js` (exportadas como `garden` por `@varanda/rpc`), os três tipos de registro `garden`, `garden-state` e `garden-help` com os construtores em `packages/core/lib/records.js`, os testes `packages/rpc/test/garden.test.js` e `packages/core/test/garden.test.js`, o caso de leitor antigo em `packages/core/test/records.test.js`, o texto na seção 2 de `docs/protocol.md` e a menção na seção 12 de `docs/rpc.md`. Não há rota, método nem tela novos.

Conferido à mão que cada constante, chave e função citada na seção 2 existe com o mesmo valor em garden.js e records.js. Os três exemplos JSON passam `validateRecord` na seq 1: rodado, com `<hex64>` de `garden-help` trocado por um hex64 minúsculo.

Rodado no Node 24.22.1, depois de `npm ci --ignore-scripts`, sobre a `main` em 34a4e34f:

- `npm run lint`
resultado: passou.
- `npm test -- --affected=origin/main`
resultado: 800 arquivos, 798 passaram e 2 falharam por tempo, os dois fora deste PR. Detalhes, e os arquivos deste PR:
- `apps/cli/test/update.test.js` estourou o tempo na rodada paralela; sozinho (`node apps/cli/test/update.test.js`) passou, 73/73 testes e 1901/1901 asserções.
- `packages/core/test/private-member-3.test.js`: o teste "private: fake bans from an unadmitted writer never inflate a rotation" estourou os 30 s, na rodada paralela e duas vezes sozinho. Numa cópia limpa da mesma `main` (34a4e34f, sem este PR) falha igual, com o mesmo tempo esgotado. O teste grava 5000 banimentos de grupo e sincroniza; nenhum passa pelos tipos novos. A CI da `main` no GitHub passa com ele.
- `packages/rpc/test/garden.test.js`: 39/39 testes, 370/370 asserções. `packages/core/test/garden.test.js`: 12/12. `packages/core/test/records.test.js`: 70/70.
- `npm run demo`
resultado: passou, terminou com "DEMO OK".
50 changes: 48 additions & 2 deletions packages/core/lib/records.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

const b4a = require('b4a')
const { validLinkCard, validCardImageBytes, copyLinkCard, CARD_IMAGE_MIME } = require('./link-card')
const { feira, isMomentMusic, MOMENT_MUSIC_KEYS, MAX_TOP_FRIENDS, profileExtra: PX, isPoll, isPick, POLL_MIN, POLL_MAX, MAX_POLL_OPTION, isEvent, event: eventRules } = require('@varanda/rpc')
const { feira, isMomentMusic, MOMENT_MUSIC_KEYS, MAX_TOP_FRIENDS, profileExtra: PX, isPoll, isPick, POLL_MIN, POLL_MAX, MAX_POLL_OPTION, isEvent, event: eventRules, garden } = require('@varanda/rpc')

const MAX_NAME = 80
const MAX_BIO = 280
Expand Down Expand Up @@ -162,6 +162,14 @@ const DEVICE_NONCE_BYTES = 24
const MIN_DEVICE_BOX = 17
// 32 writer pairs and a 40 code point name seal to about 5.2 KB.
const MAX_DEVICE_BOX = 8192
// Varandinha (docs/protocol.md): `garden` is the public flag that a diary
// shows its balcony, latest wins; `garden-state` is the whole balcony after
// a play session (the pot rules are packages/rpc lib/garden.js), latest
// wins; `garden-help` is one watering of another member's pot. No text:
// nothing in them is ever shown as typed by a person.
const GARDEN_KEYS = Object.freeze(['type', 'on', 'at'])
const GARDEN_STATE_KEYS = Object.freeze(['type', 'pots', 'n', 'at'])
const GARDEN_HELP_KEYS = Object.freeze(['type', 'to', 'pot', 'at'])
const { THEME_IDS, MAX_ABOUT, MAX_CITY, MAX_WORK, MAX_STUDIES, MAX_INTERESTS, MAX_MOOD_TEXT } = PX
// Momentos (docs/protocol.md): one photo or short video in the anonymous
// blob pool, its key and nonce public in the record, shown by readers for 24
Expand Down Expand Up @@ -600,7 +608,7 @@ function validPageShape (r) {
isHex64(r.owner) && r.actor === r.owner && validPageAdmins(r.admins, r.owner)
}

const TYPES = Object.freeze(['member-cert', 'profile', 'post', 'username', 'media-core', 'follow', 'like', 'repost', 'group-join', 'delete', 'group-cut', 'group-confirm', 'dm-key', 'page-roster', 'page-accept', 'page-offer', 'page-close', 'page-moved', 'page-origin', 'page-delegate', 'page-link', 'listing', 'listing-edit', 'listing-status', 'listing-rate', 'testimonial', 'testimonial-show', 'moment', 'post-share', 'scrap', 'scrap-hide', 'scrap-wall', 'profile-about', 'mood', 'fan', 'top-friends', 'choice', 'visits', 'device'])
const TYPES = Object.freeze(['member-cert', 'profile', 'post', 'username', 'media-core', 'follow', 'like', 'repost', 'group-join', 'delete', 'group-cut', 'group-confirm', 'dm-key', 'page-roster', 'page-accept', 'page-offer', 'page-close', 'page-moved', 'page-origin', 'page-delegate', 'page-link', 'listing', 'listing-edit', 'listing-status', 'listing-rate', 'testimonial', 'testimonial-show', 'moment', 'post-share', 'scrap', 'scrap-hide', 'scrap-wall', 'profile-about', 'mood', 'fan', 'top-friends', 'choice', 'visits', 'device', 'garden', 'garden-state', 'garden-help'])

// Required lazily: lib/group.js requires this module at load time.
function weakBoxKey (hex) {
Expand Down Expand Up @@ -714,6 +722,22 @@ function check (record, seq) {
if (!isCanonicalBase64(record.box, MIN_DEVICE_BOX, MAX_DEVICE_BOX)) return 'malformed'
return isCanonicalIso(record.at) ? null : 'date-invalid'
}
if (type === 'garden') {
if (!hasExactKeys(record, GARDEN_KEYS) || typeof record.on !== 'boolean') return 'malformed'
return isCanonicalIso(record.at) ? null : 'date-invalid'
}
// A pot is judged against this record's own date (read once here): a pot
// watered after the record that states it was written is malformed.
if (type === 'garden-state') {
if (!hasExactKeys(record, GARDEN_STATE_KEYS)) return 'malformed'
const at = record.at
if (!isCanonicalIso(at)) return 'date-invalid'
return garden.isPots(record.pots, Date.parse(at)) && garden.isSaveOrdinal(record.n) ? null : 'malformed'
}
if (type === 'garden-help') {
if (!hasExactKeys(record, GARDEN_HELP_KEYS) || !isHex64(record.to) || !garden.isPotIndex(record.pot)) return 'malformed'
return isCanonicalIso(record.at) ? null : 'date-invalid'
}
if (type === 'top-friends') {
if (!hasExactKeys(record, TOP_FRIENDS_KEYS) || !validTopKeys(record.keys)) return 'malformed'
return isCanonicalIso(record.at) ? null : 'date-invalid'
Expand Down Expand Up @@ -964,6 +988,22 @@ function deviceRecord ({ nonce, box, at = nowIso() } = {}) {
return build({ type: 'device', nonce, box, at }, 1)
}

function gardenRecord ({ on, at = nowIso() } = {}) {
return build({ type: 'garden', on, at }, 1)
}

// `pots` is copied one level down (a pot holds only primitives), so the
// record never shares an object with the caller; anything that is no array
// or no plain pot is passed through for validation to reject.
function gardenStateRecord ({ pots, n, at = nowIso() } = {}) {
const copy = Array.isArray(pots) ? pots.map((p) => (isPlainObject(p) ? { ...p } : p)) : pots
return build({ type: 'garden-state', pots: copy, n, at }, 1)
}

function gardenHelpRecord ({ to, pot, at = nowIso() } = {}) {
return build({ type: 'garden-help', to, pot, at }, 1)
}

function topFriendsRecord ({ keys, at = nowIso() } = {}) {
return build({ type: 'top-friends', keys: Array.isArray(keys) ? keys.slice() : keys, at }, 1)
}
Expand Down Expand Up @@ -1238,6 +1278,9 @@ module.exports = {
MIN_DEVICE_BOX,
MAX_DEVICE_BOX,
isCanonicalBase64,
GARDEN_KEYS,
GARDEN_STATE_KEYS,
GARDEN_HELP_KEYS,
TOP_FRIENDS_KEYS,
MAX_TOP_FRIENDS,
POST_POLL_KEYS,
Expand Down Expand Up @@ -1312,6 +1355,9 @@ module.exports = {
fanRecord,
visitsRecord,
deviceRecord,
gardenRecord,
gardenStateRecord,
gardenHelpRecord,
topFriendsRecord,
momentRecord,
deleteRecord,
Expand Down
Loading
Loading