Stores

Uma store é onde o zapo persiste tudo o que uma sessão precisa para sobreviver a um reinício: credenciais de pareamento, estado do protocolo Signal, coleções de app-state e, opcionalmente, seu arquivo de mensagens/threads/contatos. Você constrói uma com createStore e a passa para o client.

import { createStore } from 'zapo-js'
import { createSqliteStore } from '@zapo-js/store-sqlite'

const store = createStore({
  backends: {
    sqlite: createSqliteStore({ path: '.auth/state.sqlite', driver: 'auto' })
  },
  providers: {
    auth: 'sqlite',
    signal: 'sqlite',
    preKey: 'sqlite',
    session: 'sqlite',
    identity: 'sqlite',
    senderKey: 'sqlite',
    appState: 'sqlite',
    privacyToken: 'sqlite',
    messages: 'sqlite',
    threads: 'sqlite',
    contacts: 'sqlite'
  }
})

O modelo

O createStore separa backends (onde os dados ficam) de providers (qual backend cada domínio usa). Isso permite misturar backends — por exemplo, manter o estado quente do signal no Redis enquanto arquiva mensagens no Postgres.

createStore({
  backends: {
    redis: createRedisStore({ redis }),
    postgres: createPostgresStore({ pool })
  },
  providers: {
    auth: 'redis',
    signal: 'redis',
    preKey: 'redis',
    session: 'redis',
    identity: 'redis',
    senderKey: 'redis',
    appState: 'redis',
    privacyToken: 'redis',
    messages: 'postgres',
    threads: 'postgres',
    contacts: 'postgres'
  }
})

Providers são obrigatórios quando você define `backends`

Assim que backends contém ao menos uma entrada, todo domínio de persistência precisa ser atribuído explicitamente em providers. Os domínios obrigatórios são auth, signal, preKey, session, identity, senderKey, appState, privacyToken, messages, threads e contacts. Tanto os tipos TypeScript quanto uma verificação em tempo de execução garantem isso — createStore lança um erro listando as chaves providers.* faltantes quando alguma é omitida. Três valores são válidos para cada domínio:

Um nome de backend de backends (por exemplo 'sqlite') — persiste esse domínio ali.
'memory' — mantém esse domínio no provider de memória embutido nesta execução.
'none' — válido apenas para os domínios de arquivo opcionais (messages, threads, contacts); ignora o domínio por completo.

A verificação existe porque cobertura parcial é quase sempre um bug. Se você persiste apenas auth e deixa o estado do Signal, o app-state ou a caixa de mensagens recairem para a memória, o dispositivo pareia uma vez e depois perde o estado de protocolo a cada reinício. Escolha 'memory' de forma deliberada quando for esse o seu objetivo.

createStore({
  backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
  providers: {
    auth: 'sqlite',
    signal: 'sqlite',
    preKey: 'sqlite',
    session: 'sqlite',
    identity: 'sqlite',
    senderKey: 'sqlite',
    appState: 'sqlite',
    privacyToken: 'sqlite',
    messages: 'none',  // pula o arquivo de mensagens
    threads: 'none',
    contacts: 'none'
  }
})

Quando backends está vazio ou ausente, cada domínio recai para a memória (e os domínios de mailbox para 'none') — útil para testes, mas o dispositivo se re-pareia a cada reinício.

Domínios persistidos

Estes mantêm o estado necessário para manter uma sessão viva. Apoie-os com um backend durável em produção.

Domínio	Mantém
`auth`	Credenciais de pareamento e identidade do dispositivo. Persista isto.
`signal`	Sessões do Signal (guarda-chuva sobre as sub-stores abaixo).
`preKey`	Pre-keys do Signal.
`session`	Sessões do Signal.
`identity`	Chaves de identidade do Signal.
`senderKey`	Sender keys de grupo.
`appState`	Coleções de app-state (silenciar, fixar, ler, arquivar, …).
`privacyToken`	Tokens de contato confiável / privacidade.

Domínios de arquivo opcionais

Estes aceitam 'none' para desabilitar a persistência por completo:

Domínio	Mantém
`messages`	Arquivo de mensagens (`B \| 'memory' \| 'none'`).
`threads`	Metadados de thread.
`contacts`	Diretório de contatos.

Domínios de cache

Configurados em cacheProviders e usam por padrão memória limitada com TTLs:

Domínio	Mantém
`retry`	Fila de retentativa de mensagens de saída.
`groupMetadata`	Cache de metadados de grupo.
`deviceList`	Cache da lista de dispositivos.
`messageSecret`	Cache de message-secret para addons.

createStore({
  backends: { sqlite },
  providers: { /* ... */ },
  cacheProviders: { groupMetadata: 'sqlite', deviceList: 'sqlite' },
  memory: {
    cacheTtlMs: { groupMetadataMs: 600_000, deviceListMs: 600_000 }
  }
})

Cada backend remove entradas expiradas de um jeito: memory faz sweep in-process, Redis e MongoDB usam TTL nativo, SQLite filtra na leitura, e PostgreSQL/MySQL exigem um poller opt-in (result.startCleanup(sessionId)) ou as tabelas de cache crescem sem parar. Veja Expiração e limpeza de cache para a matriz por backend.

Camada de cache read-through

Quando um domínio quente do signal aponta para um backend persistente, cada ida e volta de envio/recebimento paga a latência do backend para buscar a sessão, identidade ou sender key do mesmo peer. A opção cacheLayer envolve a store do backend com um L1 LRU limitado (o provider de memória nativo) para que leituras repetidas do mesmo peer pulem o backend, enquanto escritas continuam write-through e o backend permanece como fonte de verdade. Quatro domínios quentes podem ser cacheados:

Domínio	Estratégia
`session`	Sessões Signal Double-Ratchet. Read-through + write-through.
`identity`	Chaves de identidade remotas. Read-through + write-through.
`senderKey`	Sender keys por (grupo, remetente). Read-through + write-through.
`privacyToken`	Tokens de contato confiável. Read-through + invalidate-on-write (o backend mescla campos parciais no upsert).

Todos os flags têm padrão false. Um flag é no-op a menos que aquele domínio resolva para um backend real em providers — cachear 'memory' ou 'none' na frente de si mesmo não traz ganho e é ignorado.

createStore({
  backends: { postgres, redis },
  providers: {
    auth: 'postgres',
    signal: 'postgres',
    preKey: 'postgres',
    session: 'postgres',
    identity: 'postgres',
    senderKey: 'postgres',
    appState: 'postgres',
    privacyToken: 'postgres',
    messages: 'postgres',
    threads: 'postgres',
    contacts: 'postgres'
  },
  cacheLayer: {
    session: true,
    identity: true,
    senderKey: true,
    privacyToken: true,
    limits: {
      session: 10_000,
      identity: 10_000,
      senderKey: 5_000,
      privacyToken: 5_000
    }
  }
})

limits define o limite de entradas por domínio; quando excedido, o L1 faz despejo LRU. Sem definir, cada domínio usa o limite padrão do provider de memória correspondente.

Quando habilitar

Habilite quando seu backend é uma chamada de rede (Redis, Postgres, MySQL, MongoDB) e você envia ou recebe a uma taxa em que os mesmos peers se repetem — típico de bots, fan-out em grupos e gateways multi-tenant. Com um backend SQLite local os ganhos são menores; meça antes de ativar.

Premissa de escritor único

O L1 é por processo e não tem canal de invalidação entre processos. Habilite cacheLayer apenas quando um único processo é dono das linhas de backend de um dado sessionId — o modelo de conexão padrão da biblioteca. Sessões diferentes compartilhando um backend é OK; a mesma sessão aberta em dois processos não é.

Não habilite cacheLayer quando múltiplos processos compartilham um backend para o mesmo sessionId. As escritas de outro processo deixariam este cache desatualizado e corromperiam o ratchet do Signal.

Por que não todos os domínios?

signal, appState e preKey são deliberadamente excluídos:

signal — a leitura de registro por envio já é memoizada dentro do lock do signal; um segundo cache não adiciona nada.
appState — o cliente de sync já cacheia o estado das coleções pela vida do contexto de sync, o único escopo em que as leituras se repetem e permanecem coerentes.
preKey — pre-keys de uso único são lidas exatamente uma vez e consumidas. Servir uma chave já consumida a partir de um cache desatualizado a reutilizaria e quebraria a forward secrecy.

Backends

SQLite

@zapo-js/store-sqlite — local, processo único.

PostgreSQL

@zapo-js/store-postgres — distribuído, relacional.

MySQL

@zapo-js/store-mysql — distribuído, relacional.

Redis

@zapo-js/store-redis — cache + persistência.

MongoDB

@zapo-js/store-mongo — document store.

Memory

Embutido. Ótimo para testes; não sobrevive a um reinício.

Veja a referência de stores para as opções de config de cada backend.

Apenas memória (testes)

Para experimentos rápidos ou testes, omita backends por completo — cada domínio recorre à memória:

const store = createStore({})
const client = new WaClient({ store, sessionId: 'test' }, logger)

Uma store apenas em memória perde todas as credenciais ao reiniciar, então você pareia novamente a cada boot. Use um backend durável para qualquer coisa de longa duração.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

O modelo

Providers são obrigatórios quando você define `backends`

Domínios persistidos

Domínios de arquivo opcionais

Domínios de cache

Camada de cache read-through

Quando habilitar

Premissa de escritor único

Por que não todos os domínios?

Backends

SQLite

PostgreSQL

MySQL

Redis

MongoDB

Memory

Apenas memória (testes)

​O modelo

​Providers são obrigatórios quando você define backends

​Domínios persistidos

​Domínios de arquivo opcionais

​Domínios de cache

​Camada de cache read-through

​Quando habilitar

​Premissa de escritor único

​Por que não todos os domínios?

​Backends

SQLite

PostgreSQL

MySQL

Redis

MongoDB

Memory

​Apenas memória (testes)

O modelo

Providers são obrigatórios quando você define `backends`

Domínios persistidos

Domínios de arquivo opcionais

Domínios de cache

Camada de cache read-through

Quando habilitar

Premissa de escritor único

Por que não todos os domínios?

Backends

Apenas memória (testes)