Skip to content

feat(database-redis): adaptador Redis y estado persistente en Redis - #1281

Closed
Juank2001 wants to merge 4 commits into
codigoencasa:builderbotfrom
Juank2001:feat/database-redis
Closed

Juank2001 wants to merge 4 commits into
codigoencasa:builderbotfrom
Juank2001:feat/database-redis

Conversation

@Juank2001

Copy link
Copy Markdown
Contributor

Que tipo de Pull Request es?

  • Mejoras
  • Bug
  • Docs / tests

Descripción

Agrega soporte para Redis, tanto para el historial de conversaciones como para el estado (state) de cada usuario. Así el estado sobrevive a reinicios y se puede compartir entre varias instancias del bot.

Nuevo paquete @builderbot/database-redis

Adaptador RedisAdapter (extiende MemoryDB) construido sobre ioredis. Guarda el historial de cada usuario en una lista de Redis (bot:history:{prefix}:{from}).

Opción Descripción
prefix Namespace de las llaves, para separar varios bots en un mismo Redis
store_messages Máximo de mensajes guardados por usuario (recorta los más antiguos)
expire TTL en segundos del historial; se renueva con cada mensaje
import Redis from 'ioredis'
import { RedisAdapter as Database } from '@builderbot/database-redis'

const redis = new Redis(process.env.REDIS_URL)
const adapterDB = new Database(redis, { prefix: 'my-bot', store_messages: 50 })

Estado en Redis (RedisState) en @builderbot/bot

createBot acepta un argumento nuevo y opcional, RedisOptions. Si se pasa, el state de cada usuario se guarda en Redis (bot:state:{prefix}:{from}) en vez de en memoria. Puede reutilizar la misma conexión del adaptador:

await createBot(
    { flow, provider, database: adapterDB },
    { RedisOptions: { connection: redis, options: { prefix: 'my-bot', expire: 60 * 60 * 24 } } }
)
  • expire: TTL del estado en segundos (24 h por defecto; null o 0 = sin expiración).
  • clearAll() solo borra las llaves de su propio prefix y las recorre con SCAN (no usa KEYS, que bloquea Redis).
  • Sin RedisOptions, el comportamiento es el mismo de siempre (SingleState en memoria).

Cambios en el core

  • Las lecturas de estado se hacen con await. Los tipos de BotState ahora permiten que sus métodos devuelvan promesas.
  • endFlow espera a que se limpie la cola y se actualice el estado.
  • Flujos anidados: si no hay coincidencia y el mensaje anterior pedía capture, el mensaje se procesa como captura libre en vez de buscar keywords globales.
  • WELCOME solo se usa cuando ningún otro evento (location, media, document, voice note, order, template, call, contacts) coincide.
  • addAnswer(...).addAction(...) encadenado recibe su propio ref (${ref}A).

CLI

Redis aparece como opción de base de datos al generar un bot, con su plantilla correspondiente.

Otros

  • printer respeta la variable de entorno BUILDERBOT_SILENT=true para no imprimir mensajes en consola.

Tests

  • RedisState: merge de estado, dot notation, clear, clearAll respetando el prefijo y con varias páginas de SCAN, y TTL por defecto, configurable y desactivado.
  • RedisAdapter con ioredis-mock, sin necesidad de un servidor Redis.
  • Evento CONTACTS: regex y flujo e2e.
  • coreClass ejecutándose con RedisOptions.

pnpm --filter @builderbot/bot test → 224/224 · pnpm --filter @builderbot/database-redis test → 6/6 · build OK.

Add @builderbot/database-redis, a MemoryDB adapter built on ioredis that
stores each user's history in a Redis list (bot:history:{prefix}:{from}),
with optional per-user message cap (store_messages) and TTL (expire).

Add RedisState to @builderbot/bot so per-user state can live in Redis
instead of memory. It is enabled with the new `RedisOptions` argument of
createBot ({ connection, options: { prefix, expire } }) and can reuse the
adapter's connection. State TTL defaults to 24h; clearAll only removes
keys under its own prefix and walks them with SCAN instead of KEYS.

Core changes:
- stateHandler is SingleState or RedisState; state reads are awaited
- BotState methods may return promises
- endFlow awaits queue clearing and state update
- nested flows with no match fall through to free capture when the
  previous answer requested capture
- WELCOME is only used when no other event (location, media, contacts...)
  matched
- addAnswer chained addAction gets its own ref (`${ref}A`)

CLI: add Redis to the database options and its generator template.

Tests: RedisState and RedisAdapter units (ioredis-mock), CONTACTS event
regex and e2e flow, coreClass running with RedisOptions.

@leifermendez leifermendez left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revisión

Gracias por el trabajo, el adaptador está bien resuelto y se nota que cubriste los casos difíciles (SCAN en vez de KEYS, ltrim, TTL). Dejé la revisión ordenada por severidad.

Estado del CI: Tests en verde (12m48s), Templates in sync en rojo.


1. Bloqueante — falta regenerar starters/apps/**

El job Templates in sync (pnpm run generate:check) falla con 30 directorios sin commitear:

?? starters/apps/base-js-*-redis/
?? starters/apps/base-ts-*-redis/
##[error]Process completed with exit code 1

Al agregar redis a PROVIDER_DATA (packages/cli/src/configuration/index.ts:65) y crear el zone (scripts/generate/zones/databases/redis.json), el generador produce combinaciones nuevas que no están en el repo. Esto además rompe el CLI para el usuario final:

  • NAME_DIR = base-${lang}-${provider}-${database} (packages/cli/src/interactive/index.ts:108-116) → create-builderbot --database=redis termina en TEMPLATE_PATH_NOT_FOUND.

Fix: pnpm run generate.templates y commitear starters/apps/** en este mismo PR (es la regla del repo: create-builderbot copia starters/apps a dist/starters en build).

2. Bloqueante — los templates oficiales rompen con RedisState

scripts/generate/template/ts/src/app.ts:46 y scripts/generate/template/js/src/app.js:46:

await flowDynamic(`${state.get('name')}, thanks for your information!: Your age: ${state.get('age')}`)

Con RedisState eso imprime [object Promise], y no hay error de tipos porque get<K = any> colapsa a any. Convendría cambiar a await state.get(...) en ambos templates antes de regenerar los starters, así entra todo en una sola pasada.

Relacionado: BotState quedó como unión (packages/bot/src/types.ts:200-208):

get: <K = any>(prop: string) => Promise<K> | K
clear: () => Promise<number> | void | boolean

Es contrato público que consumen los bots de los usuarios. Si el backend puede ser async, probablemente sea más honesto tipar los métodos como Promise<...> y que el core siempre haga await (await de un valor sincrónico no cuesta nada), en lugar de una unión que deja pasar el uso sincrónico sin avisar. Si se mantiene la unión, vale anotarlo como breaking en el CHANGELOG del paquete.


Riesgos

3. updateState no es atómico (packages/bot/src/context/redisStateClass.ts:36-52): hace GET y después SET. Justo el caso de uso que vendés (varias instancias compartiendo state) pierde updates cuando dos mensajes del mismo usuario se procesan en paralelo. Sugerencia: HSET por campo, o WATCH/MULTI, o un script Lua.

4. clearAll no es compatible con Redis Cluster (redisStateClass.ts:108-116): el SCAN recorre un solo nodo y el del(...keys) en lote falla si las keys caen en slots distintos. Si el soporte de Cluster no está en el alcance, estaría bueno documentarlo como limitación en el README.

5. ioredis-mock en dependencies (packages/bot/package.json:59-60): es un mock de test, va en devDependencies. Hoy se lo baja todo consumidor de @builderbot/bot.

6. import Redis from 'ioredis' siendo type-only (packages/bot/src/types.ts:10, packages/bot/src/context/redisStateClass.ts:1): mejor import type Redis from 'ioredis'. Hoy TypeScript lo elimina, pero el rollup del core bundlea todo salvo ffmpeg|sharp (packages/bot/rollup.config.js:17-19): si eso cambia, ioredis termina embebido en dist/index.cjs y quedan dos clientes.

7. Metadata del paquete nuevo (packages/database-redis/package.json):

  • "@builderbot/bot": "^1.3.15" — el resto de los adaptadores usa workspace:* (ver database-postgres).
  • "version": "1.3.15-alpha.10" con el workspace en 1.4.4.
  • Falta tslib (el tsconfig.json tiene importHelpers: true) y tsm (lo usa el script test); ambos están declarados en database-postgres.

8. Cambios de semántica en handleMsg sin tests que los fijen.

  • packages/bot/src/core/coreClass.ts:658-666: un nested sin match ahora cae a la búsqueda de keywords globales.
  • coreClass.ts:717: WELCOME pasa a ser fallback en lugar de valor inicial.

Ambos son mejoras razonables, pero coreClass.test.ts solo cambió el fixture. Faltaría un test de nested-sin-match (con y sin capture) y uno de WELCOME como fallback vs. un evento sin flow registrado.

Nits

  • Los 4 archivos nuevos no tienen el header de convención del repo (LAYER / Contains / Rules / BigO / keywords / GOAL): database-redis/src/{index,redisAdapter,types}.ts y bot/src/context/redisStateClass.ts.
  • El PR mezcla dos features: Redis y BUILDERBOT_SILENT. El commit del printer es independiente, capaz conviene moverlo a otro PR. BUILDERBOT_SILENT tampoco está documentado en ningún README.
  • redis_conn en el zone: el resto del repo usa camelCase para variables.

Lo que está bien

  • RedisAdapter testeado con ioredis-mock, sin necesidad de servidor: ltrim, prefijo, TTL y caso sin historial.
  • RedisState: SCAN paginado en vez de KEYS, borrado acotado a su propio prefijo, tests de 250 llaves y de TTL (default / configurable / deshabilitado).
  • endFlow ahora espera clearQueue + update — imprescindible con un backend remoto.
  • El ref determinístico ${ctx.ref}A (packages/bot/src/io/methods/addAnswer.ts:128) arregla un ref aleatorio que rompía la captura al reiniciar el proceso.
  • CONTACTS cableado en el core con test unitario y e2e.
  • El rollup.config.js del adaptador sigue el patrón de database-postgres.

Con los puntos 1 y 2 resueltos el PR queda en muy buen estado.

@Juank2001
Juank2001 force-pushed the feat/database-redis branch 2 times, most recently from 599169d to fa41a54 Compare November 9, 2026 16:45
- RedisState stores each user's state as a Redis hash: update is a single
  atomic HSET (+EXPIRE in the same MULTI), so concurrent updates no longer
  overwrite each other, and reading one property is a single HGET
- BotState keeps its synchronous types so existing TypeScript code still
  compiles; add BotStateAsync for bots that use RedisOptions
- move ioredis-mock to devDependencies of @builderbot/bot
- database-redis depends on @builderbot/bot via workspace:* and is
  versioned 1.4.4 like the rest of the monorepo
- CLI Redis template declares ioredis as a dependency
- coreClass unit tests run with in-memory state by default, with a
  separate set covering RedisOptions; add a concurrent-update test

chore(starters): regenerate starter apps, including the new *-redis ones
…ed starters

- BotState per-user methods (get, getMyState, getAllState, clear) are typed
  as Promise; BotStateGlobal keeps its sync types. In-memory state still
  returns sync values at runtime, so existing JS code keeps working
- templates and provider zones await state.get (fixes [object Promise] and a
  crash in meta-voice-ai with Redis state)
- generator normalizes CRLF so starters are identical on Windows and Linux;
  starters regenerated (Redis starters use `redis` instead of `redis_conn`)
- use `import type` for ioredis so it can never be bundled into the core
- database-redis declares tslib and tsm; add repo headers to new files
- e2e tests for handleMsg fallbacks: nested without match (with and without
  capture) and WELCOME vs. event flows
- document BUILDERBOT_SILENT in the @builderbot/bot README

BREAKING CHANGE: BotState per-user methods (get, getMyState, getAllState,
clear) are now typed as Promise. Use `await state.get(...)`; in-memory state
still returns sync values at runtime.
@Juank2001
Juank2001 force-pushed the feat/database-redis branch from fa41a54 to 5e8b637 Compare November 9, 2026 17:00
@Juank2001

Copy link
Copy Markdown
Contributor Author

¡Gracias por la revisión! Ya quedó todo aplicado:

  • Templates y tipos: los templates y las zones voice-whatsapp y meta-voice-ai ahora usan await state.get(...). Además, BotState quedó tipado como Promise (marcado como breaking change); el estado en memoria sigue funcionando igual.
  • updateState atómico: ya estaba resuelto con HSET en un MULTI (de2db47).
  • Redis Cluster: queda fuera del alcance de este PR.
  • Dependencias: ioredis-mock pasó a devDependencies, se usa import type y en database-redis quedaron workspace:*, la versión 1.4.4, tslib y tsm.
  • Tests: agregué tests para los fallbacks de handleMsg (nested sin match y WELCOME).
  • Nits: headers agregados, BUILDERBOT_SILENT documentado y redis_conn → redis.
  • CI: el generate:check fallaba por los saltos de línea de Windows en el generador; ya está corregido.

@leifermendez

Copy link
Copy Markdown
Member

Superado por #1292 y #1293, ambas mergeadas.

Al revisar el PR quedó claro que no se podía separar de forma mecánica: la activación de Redis vive en packages/bot/src/core/coreClass.ts (stateHandler: SingleState | RedisState y la selección del backend en el constructor), y handleMsg necesita await this.stateHandler.get(...) porque BotState pasó a devolver promesas. Ese mismo archivo traía además la reescritura de fallbacks, el cambio de ref en addAnswer, BUILDERBOT_SILENT y la normalización CRLF del generador.

Por eso quedó dividido en dos unidades revisables por separado:

Gracias por el trabajo: el adaptador y el estado en Redis se mantuvieron tal cual, con tests propios. Cierro este PR para no dejar dos líneas de autoridad abiertas sobre el mismo cambio; si preferís seguir iterando sobre este branch, avisá y lo reabrimos.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants