Multialojamiento e idempotencia

# gateway.env
# Owner pool — runs migrations and privileged maintenance
AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable
# Restricted role — activates RLS for normal request traffic
AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable

side-effect requested
   └─▶ compute resume-stable ledger key
         └─▶ barrier: key already committed?
               ├─ yes ─▶ skip (no double-send)
               └─ no  ─▶ perform effect ─▶ commit key

AiHummer es **multitenant**: un único gateway puede servir a muchos espacios de trabajo desde una sola base de datos mientras mantiene sus datos separados. Dos mecanismos hacen que eso sea seguro — **Seguridad a Nivel de Fila en Postgres (RLS)** para aislamiento de lectura/escritura, y un **capa de idempotencia** para que los reintentos y la recuperación de turnos nunca dupliquen un efecto secundario del mundo real. **Nivel:** El aislamiento multitenant a nivel de fila está restringido por la versión de pago **Empresa** nivel — no forma parte de la plataforma gratuita/Comunidad; la capa de idempotencia es parte del núcleo. ## Aislamiento de inquilinos con seguridad a nivel de fila El aislamiento se aplica en la base de datos, no solo en el código de la aplicación. AiHummer ejecuta consultas a través de un **rol restringido de Postgres** (`aihummer_app`) que tiene políticas RLS aplicadas, por lo que la propia base de datos rechaza las filas que no pertenecen al inquilino activo. RLS es **optar por participar**. Lo activas proporcionando al gateway una segunda cadena de conexión para el rol restringido: ```ini # gateway.env # Owner pool — runs migrations and privileged maintenance AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable # Restricted role — activates RLS for normal request traffic AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable ``` > [!NOTE] > Para instalaciones nativas en el anfitrión, el instalador establece `AIHUMMER_DB_APP_URL` > automáticamente, por lo que RLS está activado por defecto en una implementación estándar. Si el > si la variable está ausente, el gateway funciona solo en el grupo del propietario y RLS no está > activo. ### Alcance por inquilino Dentro del rol restringido, cada solicitud está limitada a su inquilino: la pasarela establece el contexto del inquilino actual en la conexión para que las políticas RLS se resuelvan contra el espacio de trabajo correcto. `WHERE tenant_id = …` los filtros no se aplican manualmente en todas partes; la política lo hace cumplir de manera centralizada, lo que significa que un filtro omitido no puede filtrar las filas de otro inquilino. ### Sistema / modo de omisión Parte del trabajo es legítimamente entre inquilinos: trabajadores en segundo plano, planificadores y tareas de mantenimiento que operan en toda la instancia. Estos se ejecutan en un **sistema / modo de omisión** para que puedan ver lo que necesitan. El bypass está reservado para empleados internos de confianza, no para rutas de manejo de solicitudes. > [!WARNING] > **Las migraciones siempre se ejecutan en el grupo propietario**, nunca bajo el rol restringido. > La conexión del propietario tiene los privilegios para alterar el esquema y aplicar RLS > políticas; el rol restringido deliberadamente no lo hace. Mantén las dos conexiones > cuerdas distintas y otorgar el `aihummer_app` rol solo lo que necesita. ## Efectos secundarios idempotentes Una acción puede producir efectos secundarios en el mundo real: enviar correo, publicar un mensaje de vuelta en un canal. Si se reintenta una acción —debido a un error transitorio, o porque la puerta de enlace se reinició a mitad de la acción y la recuperación la reproduce— esos efectos secundarios deben **no** suceder dos veces. AiHummer garantiza esto con dos piezas que cooperan. ### Una clave de libro mayor estable para resumen Cada efecto secundario se registra contra un **clave de libro mayor estable para currículum**: una clave que se deriva de manera determinista del turno, por lo que una repetición del mismo turno calcula la *misma* clave en lugar de una nueva. El libro mayor recuerda qué claves ya han sido utilizadas. ### Una barrera de efectos secundarios Antes de un efecto como **correo** o **canal-enviar** se realiza, pasa por un **barrera de efectos secundarios** que verifica el libro mayor. Si esta clave ya se ha activado, la barrera se corta y el efecto se omite; si no, el efecto se ejecuta y la clave se confirma. ```text side-effect requested └─▶ compute resume-stable ledger key └─▶ barrier: key already committed? ├─ yes ─▶ skip (no double-send) └─ no ─▶ perform effect ─▶ commit key ``` El resultado es **comportamiento externo exactamente una vez aunque la entrega sea al menos una vez internamente**. Los reintentos son seguros por construcción, lo que permite la recuperación de giro (ver [Entrega y recuperación confiables](/es/v1.0/architecture/delivery-outbox)) reproducir un turno interrumpido sin que un cliente reciba el mismo correo electrónico o la misma respuesta dos veces. > [!TIP] > Por esto es que AiHummer puede ofrecer entrega garantizada y recuperación automática de giro > sin el riesgo habitual de mensajes duplicados — la idempotencia es la base > las garantías de entrega se construyen sobre. ## ¿A dónde vamos ahora? - El tiempo de ejecución que impulsa un turno: [Motor de puerta y giro](/es/v1.0/architecture/gateway-turn-engine). - Cómo se devuelven las respuestas exactamente una vez: [Entrega y recuperación confiables](/es/v1.0/architecture/delivery-outbox).