funifier-mcp 0.2.25 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/websocket.md

@@ -1,41 +1,474 @@
-# WebSocket (WebSocket)
+# `websocket`
 
 **Acesso Studio:** `/studio/websocket`
 **API Endpoint:** `/v3/websocket`
+**Endpoint WS (runtime):** `ws://<host>/ws/{socket}`
+**Coleção MongoDB:** `websocket`
 
-## O que é
+---
 
-Entrega de feedbacks em tempo real e interação instantânea entre jogadores. Permite configurar rotinas para enviar e receber informações instantaneamente entre jogadores e o sistema, sem precisar recarregar a página.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `websocket` é um **motor de execução de scripts Groovy acionados por eventos de conexão WebSocket**. Cada documento `websocket` guarda um script Groovy que é compilado, cacheado em memória e executado quando um cliente abre, envia mensagem ou fecha uma conexão WebSocket cujo path aponta para o `_id` daquele documento.
 
-- Para comunicação em tempo real durante competições
-- Para feedback instantâneo ao completar desafios
-- Para chats ao vivo entre jogadores
-- Para atualização de status em tempo real
+É um irmão mais simples do módulo [`trigger`](trigger.md): compartilha exatamente a mesma infraestrutura de sandbox (`SecureASTCustomizer` + `TriggerExpressionChecker`), o mesmo padrão de cache de classe compilada invalidado por `updated`, e o mesmo executor isolado com timeout. A diferença é o gatilho: em vez de eventos de ciclo de vida de entidades, o gatilho são os eventos de socket `onOpen` / `onMessage` / `onClose`.
 
-## Checklist de Configuração no Studio
+Papel arquitetural:
 
-- [ ] Configurar rotinas de websocket
-- [ ] Definir eventos que disparam mensagens
-- [ ] Configurar canais de comunicação
+- Permite implementar lógica de comunicação em tempo real (chat, broadcast, notificação push para o navegador) sem recompilar o serviço.
+- O endpoint físico WebSocket (`WebSocketServer`, JSR-356 `@ServerEndpoint("/ws/{socket}")`) recebe a conexão, resolve o tenant pela apiKey extraída do token e delega cada evento ao `WebSocketManager`.
+- O `WebSocketManager` mantém **em memória** o mapa de sessões abertas por socket e o cache de classes Groovy compiladas.
+- O envio efetivo de bytes ao navegador só acontece **de dentro do próprio script**, via o helper `broadcast(...).send()` (classe `Message`).
 
-## API Endpoints
+Relação com outros módulos:
 
-### Listar WebSockets
-**Método:** GET
-**Endpoint:** `/v3/websocket`
+- **`trigger`** — reutiliza `TriggerExpressionChecker` (mesma lista de classes/métodos proibidos no AST).
+- **`ai`** — `POST /v3/ai/build/websocket` (`AIRest.buildWebSocket`) gera um rascunho de `WebSocket` via GPT-3.5. Ver seção 4 e seção 7 (contém bugs de copy-paste).
+- **`auth`** — autenticação da conexão WS via token na querystring (`AuthBean`, `TokenUtil`).
 
-### Criar WebSocket
-**Método:** POST
-**Endpoint:** `/v3/websocket`
+> ⚠️ **Aviso de runtime, confirmado no código:** o registro programático do endpoint WebSocket está **comentado** em `Configuration.java:544-553`. Ver seção 7 e seção 8 — esta é a informação operacional mais importante deste módulo.
 
-### Deletar WebSocket
-**Método:** DELETE
-**Endpoint:** `/v3/websocket/:id`
+---
 
-## Validações e Testes
+## 2. Arquitetura e Fluxos
 
-- [ ] WebSocket aparece na lista
-- [ ] Mensagens são entregues em tempo real
-- [ ] Conexão se mantém estável
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `WebSocket` | `engine/websocket/WebSocket.java` | Entidade persistida — script + metadados. |
+| `WebSocketManager` | `engine/websocket/WebSocketManager.java` | Orquestrador — CRUD, mapa de sessões, cache `compiled`/`dates`, compilação e execução. |
+| `Message` | `engine/websocket/Message.java` | Helper de broadcast — filtra sessões por player e envia texto. |
+| `WebSocketServer` | `ws/WebSocketServer.java` | Endpoint físico JSR-356 `@ServerEndpoint("/ws/{socket}")`. |
+| `WebSocketRest` | `rest/v3/rest/WebSocketRest.java` | Endpoints REST `/v3/websocket` (CRUD da definição). |
+| `TriggerExpressionChecker` | `engine/integration/trigger/TriggerExpressionChecker.java` | `SecureASTCustomizer.ExpressionChecker` reaproveitado do `trigger`. |
+| `ManagerFactory` | `controller/ManagerFactory.java` | Instancia **um** `WebSocketManager` por tenant (`getWebSocketManager()`). |
+| `Entity.WEBSOCKET` | `engine/util/Entity.java:242` | Mapeia a coleção `websocket` → `WebSocket.class`. |
+
+### 2.2 Pipeline de cadastro (REST `POST /v3/websocket`)
+
+Sequência real (`WebSocketRest.insert`):
+
+```
+1. [Entrada]      insert(authBean, obj)            — obj == null → retorna {} com HTTP 201 e nada acontece
+2. [Resolve]      getManagerFactory().getWebSocketManager()
+3. [Monta script] manager.getScript(obj)           — embrulha obj.script na classe FunifierWebSocket
+4. [Valida]       manager.compile(script)           — compila com SecureASTCustomizer
+   ├─ CompilationFailedException → result = {websocket, status:"ERROR", message} → HTTP 201
+   └─ OK →
+5. [Persiste]     manager.save(obj)                 — upsert por _id na coleção `websocket`
+6. [Resposta]     result = {websocket, status:"OK"} → HTTP 201
+```
+
+Pontos não-convencionais (ver seção 4):
+- O HTTP **201 é retornado mesmo quando a compilação falha** — o campo `status` no corpo é o sinal real de sucesso/erro.
+- `compile()` é chamado **antes** de `save()`: um script inválido nunca é persistido.
+
+### 2.3 Pipeline de execução de evento (runtime WS)
+
+Disparado por `WebSocketServer.onOpen/onMessage/onClose` → `WebSocketManager.onOpen/onMessage/onClose` → `run(...)` → `executor(...)`.
+
+Pseudocódigo de `WebSocketManager.run`:
+
+```
+se websocket.updated == null:
+    save(websocket)                      # força criação e define updated
+lastCompilation = dates[websocket._id]
+clazz = compiled[websocket._id]
+se clazz != null E lastCompilation != null E lastCompilation > websocket.updated:
+    executor(clazz, ...)                 # reaproveita classe em cache
+senão:
+    script = getScript(websocket)
+    clazz  = compile(script)
+    compiled[websocket._id] = clazz
+    dates[websocket._id]    = agora      # marca data da compilação
+    executor(clazz, ...)
+```
+
+### Fluxo de compilação e cache — `WebSocketManager.run`
+
+```mermaid
+flowchart TD
+    A[Evento de socket] --> B{websocket.updated == null?}
+    B -- sim --> C[save: define updated]
+    B -- nao --> D{cache valido?<br/>lastCompilation > updated}
+    C --> D
+    D -- sim --> E[reutiliza classe em compiled]
+    D -- nao --> F[getScript + compile]
+    F --> G[guarda em compiled e dates]
+    G --> H[executor]
+    E --> H[executor: thread isolada + timeout]
+    H --> I{metodo}
+    I -- onOpen --> J[script.onOpen session, config]
+    I -- onMessage --> K[script.onMessage session, message]
+    I -- onClose --> L[script.onClose session, reason]
+```
+
+`WebSocketManager.executor` (síncrono, bloqueante por evento):
+
+1. Cria `Executors.newSingleThreadExecutor()`.
+2. `timeout = websocket.timeout` se `> 0`, senão `30` segundos.
+3. Instancia a classe compilada (`clazz.newInstance()`).
+4. Injeta `setId`, `setContext`, `setManager`, `setSessions` no objeto Groovy.
+5. Despacha **apenas** `onOpen` | `onMessage` | `onClose` conforme o evento (⚠️ `onError` não é despachado — seção 7).
+6. Chama `addAllOutput` para coletar os `println` do script.
+7. `future.get(timeout, SECONDS)` — se estourar, `future.cancel(true)` + `executor.shutdownNow()`.
+8. Qualquer exceção (compilação, segurança, timeout, execução) é coletada na lista `exceptions` — que é **descartada** pelos chamadores `onOpen/onMessage/onClose` (não há retorno ao cliente). Falhas de script são, na prática, silenciosas em runtime (no máximo um `printStackTrace`).
+
+### 2.4 Interação entre componentes (push para o navegador)
+
+```mermaid
+sequenceDiagram
+    participant B as Browser
+    participant S as WebSocketServer<br/>(/ws/{socket})
+    participant M as WebSocketManager
+    participant G as Script Groovy<br/>(FunifierWebSocket)
+    participant Msg as Message
+    B->>S: WS connect ?authorization=Bearer&player=alice
+    S->>S: getApiKey(token) / getPlayer(token|?player)
+    S->>S: session.userProperties["id"] = player
+    S->>M: onOpen(socket, session, config)
+    M->>M: getSessions(socket).add(session)  (via script)
+    B->>S: send("texto")
+    S->>M: onMessage(socket, session, "texto")
+    M->>G: onMessage(session, message)
+    G->>Msg: broadcast(message).to("alice").send()
+    Msg->>M: getSessions(socket)
+    Msg-->>B: session.getAsyncRemote().sendText(message)
+```
+
+> O `WebSocketManager.send(socket, message)` **não** envia diretamente — ele delega para `onMessage(socket, null, message)`, ou seja, re-executa o script do socket com `session = null`. O laço de broadcast direto está comentado no código. O único caminho que efetivamente escreve bytes no cliente é `Message.send()`, invocado de dentro do script via `broadcast(...)`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `WebSocket` — documento raiz
+
+Coleção `websocket`. Anotada com `@JsonIgnoreProperties(ignoreUnknown=true)` → **qualquer campo não listado abaixo é silenciosamente descartado na desserialização**.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.shortTimeMillis()` se vazio/branco) | — | Identificador. **É usado como `{socket}` na URL** `ws://<host>/ws/{_id}`. Defina um valor legível (ex. `reward`, `chat`). |
+| `title` | String | — | não | Nome de exibição no Studio. **Não usado em runtime.** |
+| `description` | String | — | não | Descrição. **Não usado em runtime.** |
+| `script` | String | — | sim (de fato) | Código Groovy com os métodos `onOpen` / `onMessage` / `onClose`. Sem ele, a compilação gera uma classe vazia e nenhum evento faz nada. |
+| `timeout` | Long | 30 (fallback no `executor`) | não | Timeout em **segundos** do executor por evento. Ver dupla-camada de timeout abaixo. |
+| `updated` | Date | auto (`new Date()` a cada `save`) | — | Timestamp da última gravação **e** invalidador de cache cross-cluster (ver 3.2). |
+
+#### Campos aceitos e silenciosamente ignorados
+
+- `aggregate`, `collection` — **não existem** na classe `WebSocket`. São sugeridos pelo prompt do builder de IA (`AIRest.buildWebSocket`) por copy-paste do builder de *find/aggregate*, e descartados por `@JsonIgnoreProperties` ao desserializar a resposta do GPT. Ver seção 7.
+- Qualquer outro campo enviado no POST é descartado sem erro.
+
+#### Campos sem persistência (apenas runtime, injetados no script)
+
+Não ficam no documento — são variáveis disponíveis **dentro** do script Groovy (ver 3.3): `_id`, `sessions`, `context`, `manager`, `output`.
+
+### 3.2 Semântica de `updated` (cache cross-cluster)
+
+`updated` tem papel duplo:
+
+1. Timestamp de auditoria da última gravação.
+2. **Invalidador de cache distribuído.** Cada nó do cluster mantém seu próprio `dates[_id]` (data da última compilação local). A condição de reuso de cache é `lastCompilation > websocket.updated`. Quando o nó A salva o script (`save()` atualiza `updated`), o nó B — ao reler o documento do Mongo no próximo evento — verá `updated > lastCompilation` local e **recompilará**, propagando a nova versão sem reinício. Os comentários `//cluster:` no código confirmam esse mecanismo.
+
+### 3.3 Classe gerada `FunifierWebSocket` (runtime)
+
+`WebSocketManager.getScript()` embrulha o `script` do usuário numa classe Groovy anotada com `@TimedInterrupt(value = 30L, unit = TimeUnit.SECONDS)` e com um amplo conjunto de imports (HTTP/Unirest, e-mail, Thumbnailator, entidades Funifier, `ManagerFactory`, classes `javax.websocket.*`, `Message`). Helpers injetados disponíveis para o script:
+
+| Símbolo | Tipo | Significado |
+|---|---|---|
+| `_id` | String | Id do socket atual. |
+| `broadcast(String message)` | `Message` | Cria um `Message` ligado a este socket — encadeie `.to(...)` / `.tos(...)` e finalize com `.send()`. |
+| `sessions` | `Set<Session>` | Sessões abertas deste socket (em memória, neste nó). |
+| `context` | `HashMap` | Mapa **efêmero por evento** — alocado novo a cada `onOpen`/`onMessage`/`onClose`. **Não persiste entre eventos.** |
+| `manager` | `ManagerFactory` | Acesso a todos os managers Funifier (player, action, etc.). |
+| `println(msg)` | void (override) | Não imprime no stdout — acumula em `output` (coletado em `addAllOutput`, mas descartado pelos chamadores). |
+
+### 3.4 `Message` — helper de broadcast
+
+| Método | Efeito |
+|---|---|
+| `to(String player)` | Adiciona um player à lista de destinatários (ignora null/branco). |
+| `tos(List<String> players)` | Adiciona vários players. |
+| `send()` | Se a lista `to` estiver preenchida, envia **apenas** às sessões cujo `session.getUserProperties().get("id")` casa com um player da lista; caso contrário, faz **broadcast a todas** as sessões do socket. Envio via `getAsyncRemote().sendText(message)`. |
+
+> O filtro por player só funciona se o cliente conectou com `player=<id>` na querystring **ou** com um token cujo claim `player` seja `<id>` (definido em `WebSocketServer.onOpen`).
+
+---
+
+## 4. Endpoints
+
+### `POST /v3/websocket` — criar ou substituir (upsert)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Compila e persiste a definição do websocket. |
+| Autenticação | `@BeanParam AuthBean` (Basic/Bearer). |
+| Full replace ou patch | **Full replace / upsert por `_id`** (`col.save(obj)` do Jongo). Não há merge de campos. |
+| Código HTTP | Sempre `201 CREATED`, inclusive em erro de compilação. |
+
+**Comportamento real:**
+- `obj == null` → resposta `{}` (corpo vazio após remoção de nulls) com HTTP 201; nada é persistido.
+- Compila **antes** de salvar. Em `CompilationFailedException`, retorna `status:"ERROR"` + `message` e **não salva**.
+- `_id` ausente/branco → gerado por `Guid.shortTimeMillis()` (string base-encoded de `System.currentTimeMillis()`).
+- `updated` é sempre sobrescrito com `new Date()`.
+
+**Request:**
+
+```json
+{
+  "_id": "chat",
+  "title": "Chat ao vivo",
+  "description": "Canal de chat da competição",
+  "timeout": 30,
+  "script": "void onMessage(session, message) {\n  broadcast(message).send();\n}"
+}
+```
+
+**Response (sucesso):**
+
+```json
+{
+  "websocket": {
+    "_id": "chat",
+    "title": "Chat ao vivo",
+    "description": "Canal de chat da competição",
+    "timeout": 30,
+    "script": "void onMessage(session, message) { broadcast(message).send(); }",
+    "updated": { "$date": "2026-05-20T12:00:00.000Z" }
+  },
+  "status": "OK"
+}
+```
+
+**Response (erro de compilação) — ainda HTTP 201:**
+
+```json
+{
+  "websocket": { "_id": "chat", "script": "void onMessage(... }" },
+  "status": "ERROR",
+  "message": "startup failed: Script1.groovy: 1: unexpected token ..."
+}
+```
+
+### `GET /v3/websocket/{id}` — buscar uma definição
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retorna o documento `WebSocket` por `_id`. |
+| Autenticação | `@BeanParam AuthBean`. |
+| Não encontrado | `find()` faz `findOne("{_id:#}", id)`; se não existir, o corpo serializado é vazio/nulo, HTTP 200. |
+
+```
+GET /v3/websocket/chat
+```
+
+### `DELETE /v3/websocket/{id}` — remover
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remove o documento e limpa o estado em memória. |
+| Autenticação | `@BeanParam AuthBean`. |
+| Código HTTP | `204 NO_CONTENT`. |
+
+Efeitos: `remove("{_id:#}", id)` na coleção, `compiled.remove(id)`, `dates.remove(id)`, `sessions.remove(id)` (descarta o mapa de sessões em memória deste nó).
+
+### `POST /v3/ai/build/websocket` — rascunho via IA (não persiste)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Usa GPT-3.5 (function calling `build_websocket`) para gerar um rascunho de `WebSocket` a partir de uma descrição em linguagem natural. |
+| Autenticação | `@BeanParam AuthBean`. |
+| Persistência | **Nenhuma.** Retorna um objeto `WebSocket` (HTTP 200) que o cliente deve então enviar ao `POST /v3/websocket`. |
+
+**Request:** `{ "content": "um chat onde a mensagem vai só para o player citado" }`
+
+> ⚠️ Contém dois bugs de copy-paste confirmados no código — ver seção 7.
+
+### Endpoint WebSocket (runtime) — `ws://<host>/ws/{socket}`
+
+JSR-356 `@ServerEndpoint("/ws/{socket}")` em `WebSocketServer`. `{socket}` = `_id` do documento `websocket`.
+
+**Query params da conexão:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `authorization` | String | `Bearer <token>`. Usado para extrair a apiKey (`AuthBean.getApiKey`) → resolve o tenant/banco, e o claim `player` (`TokenUtil.getValue(..., "player")`). |
+| `player` | String | Fallback do id do player, usado **apenas** se o token não trouxer o claim `player`. |
+
+No `onOpen`, se um player for resolvido, `session.getUserProperties().put("id", player)` — é esse valor que o `Message.to(...)` usa para filtrar destinatários.
+
+```
+ws://service.funifier.com/ws/chat?authorization=Bearer%20<JWT>&player=alice
+```
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código (não no schema):
+
+- **Compilação obrigatória no cadastro** — script inválido nunca chega ao banco (mas a resposta ainda é 201; cheque `status`).
+- **Isolamento por tenant via apiKey** — não há campo de organização no documento. O isolamento vem do roteamento `FrontController.getInstance(apiKey).getManagerFactory()`: cada apiKey resolve uma conexão/banco Mongo distinto. O `find(socket)` ocorre no banco do tenant dono do token usado na conexão WS.
+- **Dupla camada de timeout** — (1) `@TimedInterrupt(value = 30L, SECONDS)` é injetado **hardcoded** na classe gerada por `getScript()` e instrumenta laços/iterações em nível de AST; (2) `websocket.timeout` (ou 30s) limita o `future.get(...)` do executor. Definir `timeout > 30` **não** contorna o `@TimedInterrupt` de 30s para laços apertados.
+- **Cache invalidado por gravação** — salvar uma definição (`save()`) atualiza `updated` e remove a classe do `compiled` deste nó; demais nós recompilam quando detectam `updated > lastCompilation` (ver 3.2).
+- **Sessões em memória** — o mapa `sessions` é um `HashMap` simples no `WebSocketManager`, vivo apenas no processo. Ver limitação de cluster na seção 7/8.
+- **Execução síncrona e bloqueante por evento** — cada evento roda em uma thread dedicada e o `WebSocketServer` aguarda o resultado.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | `save()` com `_id` vazio/branco | `Guid.shortTimeMillis()` define o id (que vira a URL do socket) | Sim (`websocket`) |
+| Atualização de `updated` | Todo `save()` | Marca timestamp e invalida cache cross-cluster | Sim |
+| Invalidação de cache local | `save()` e `delete()` | `compiled.remove(_id)` (e `dates`/`sessions` no delete) | Memória (por nó) |
+| Auto-criação no 1º evento | `run()` com `websocket.updated == null` | Chama `save()` antes de executar — persiste a definição que ainda não tinha sido gravada | Sim |
+| Recompilação automática | `run()` quando cache inválido | Recompila o script e atualiza `dates[_id]` | Memória |
+| `context` efêmero | Cada `onOpen`/`onMessage`/`onClose` | `HashMap` novo por evento; não há estado entre eventos | Não |
+| Coleta de `println` | `executor` → `addAllOutput` | Saídas do script acumuladas em lista e **descartadas** pelos chamadores | Não |
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD da definição: `POST /v3/websocket` (upsert), `GET /v3/websocket/{id}`, `DELETE /v3/websocket/{id}`.
+- Eventos de script: `onOpen(session, config)`, `onMessage(session, message)`, `onClose(session, reason)`.
+- Broadcast a todas as sessões do socket (`broadcast(msg).send()`).
+- Envio direcionado por player (`broadcast(msg).to("alice").send()` / `.tos([...])`).
+- Acesso aos managers Funifier dentro do script (`manager.getPlayerManager()`, etc.).
+- Geração de rascunho por IA (`POST /v3/ai/build/websocket`).
+- Sandbox de segurança herdado do `trigger` (ver seção 8).
+- Pong automático em mensagens `PongMessage` (`WebSocketServer.onPong`).
+
+### ❌ NÃO Suportado
+
+- **`GET /v3/websocket` (listagem)** — **não existe**. Não há endpoint de lista; só busca por `{id}`. (A documentação anterior afirmava o contrário — estava incorreta.)
+- **PATCH / update parcial** — `POST` é sempre full replace/upsert; não há merge de campos.
+- **Evento `onError` no script** — `executor` despacha **apenas** `onOpen`/`onMessage`/`onClose`. O `WebSocketServer.onError` só faz `printStackTrace()`. O comentário em `WebSocket.java:19` ("onOpen, onMessage, onClose, orError") é enganoso: um método `onError` no script **nunca** é chamado.
+- **Campos `aggregate` e `collection`** — sugeridos pelo prompt do builder de IA, mas **inexistentes** na entidade; descartados silenciosamente por `@JsonIgnoreProperties`.
+- **Broadcast cross-cluster** — `sessions` é um `HashMap` em memória por JVM. Um `broadcast` no nó A **não alcança** sessões conectadas ao nó B. Limitação arquitetural confirmada (não há backplane/pub-sub).
+- **Push a partir de outros módulos** — nenhum manager fora de `engine/websocket` constrói `Message` ou chama `getWebSocketManager().send/onMessage` (verificado por grep no `src/main/java`). O único caminho de push é de dentro do próprio script do socket.
+- **Estado persistente entre eventos** — `context` é recriado a cada evento; não há sessão de estado server-side além do `Set<Session>`.
+- **Helpers `socket()` / `message()` no `WebSocketManager`** — comentados (deprecated).
+- **Registro programático do endpoint WS** — `serverContainer.addEndpoint(WebSocketServer.class)` está **comentado** em `Configuration.java:544-553`. O endpoint `/ws/{socket}` depende inteiramente do auto-scan de anotações do container servlet; se o container não escanear `@ServerEndpoint`, o WebSocket **não sobe**. Confirme a ativação no ambiente antes de assumir que o módulo está operacional.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação REST** — endpoints `/v3/websocket` usam `@BeanParam AuthBean` (Basic/Bearer), como o restante da API v3.
+- **Autenticação WS** — feita pela querystring: `authorization=Bearer <token>` → `AuthBean.getApiKey` resolve o tenant; o claim `player` (ou `?player=`) identifica o usuário. Não há challenge handshake adicional — quem tiver o token entra.
+- **Isolamento multi-tenant** — garantido pelo roteamento por apiKey no `FrontController` (banco Mongo distinto por tenant). O documento `websocket` não carrega campo de organização.
+- **Sandbox de execução (Groovy)** — `compile()` usa `SecureASTCustomizer` + `TriggerExpressionChecker` (compartilhado com `trigger`):
+  - **Tipos bloqueados:** `System`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject`.
+  - **Textos de expressão bloqueados:** `.execute`, `.getDB`, `.getMongo`, `.dropDatabase`.
+  - **Whitelist de tokens** aritméticos/lógicos/comparação e colchetes (ver `compile()`).
+  - Limite de tempo via `@TimedInterrupt` (30s, hardcoded) + timeout do executor.
+- **Superfícies de risco confirmadas no código:**
+  - O sandbox é **parcial** (igual ao `trigger`): a lista de classes proibidas é curta e baseada em correspondência textual da expressão (`indexOf`), contornável por reflexão indireta/aliases. Não trate scripts de fontes não confiáveis como seguros.
+  - O script tem acesso ao `ManagerFactory` completo do tenant — pode ler/alterar qualquer entidade da gamificação daquele tenant.
+  - A apiKey e o player são **logados em stdout** (`System.out.println`) em cada evento (`WebSocketServer`). Evite logs em ambiente compartilhado / cuidado com vazamento.
+  - Falhas de script são silenciosas para o cliente (exceções coletadas e descartadas) — dificulta detecção de abuso/erro.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Como verificar se o módulo está funcionando
+
+1. **A definição existe?**
+   ```
+   GET /v3/websocket/<socket>
+   ```
+   Corpo vazio = documento inexistente (crie via POST).
+
+2. **O script compila?** Reenvie via `POST /v3/websocket` e cheque `status`:
+   - `status: "OK"` → compilou e foi salvo.
+   - `status: "ERROR"` → veja `message` (erro de compilação Groovy). **Lembre:** HTTP é 201 nos dois casos.
+
+3. **O endpoint WS está ativo?** Tente conectar `ws://<host>/ws/<socket>?authorization=Bearer <token>`. Se a conexão não estabelece, verifique primeiro se o `@ServerEndpoint` foi registrado pelo container — o registro programático está comentado (`Configuration.java`).
+
+### Queries úteis (Mongo / coleção `websocket`)
+
+```
+// listar todos os sockets do tenant (não há endpoint REST de lista)
+db.websocket.find({}, {title:1, updated:1})
+
+// inspecionar um script
+db.websocket.findOne({_id: "chat"})
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| Conexão WS recusada / 404 | Endpoint não registrado (registro comentado em `Configuration.java`); container não fez auto-scan. |
+| `status: "ERROR"` no POST | Sintaxe Groovy inválida ou uso de classe/expressão bloqueada pelo sandbox. |
+| Mensagem não chega ao destinatário | Player do destinatário não bateu (`to("x")` exige conexão com `player=x` ou claim `player=x`). |
+| Mensagem não chega em ambiente com vários nós | Destinatário conectado a outro nó do cluster (sessões são por JVM). |
+| Script "trava" e nada acontece | Timeout do executor/`@TimedInterrupt` (30s) abateu a execução; exceção foi descartada silenciosamente. |
+| `onError` no script nunca executa | `onError` não é despachado — comportamento esperado (seção 7). |
+| Campos `aggregate`/`collection` "somem" | Descartados por `@JsonIgnoreProperties` — não existem na entidade. |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — eco/broadcast
+
+```json
+{
+  "_id": "echo",
+  "title": "Echo",
+  "script": "void onMessage(session, message) {\n  broadcast(message).send();\n}"
+}
+```
+
+Toda mensagem recebida é reenviada a todas as sessões conectadas em `/ws/echo`.
+
+### 10.2 Avançado — mensagem direcionada por player + uso de manager
+
+```json
+{
+  "_id": "reward",
+  "title": "Notificação de recompensa",
+  "description": "Avisa um player específico quando algo acontece",
+  "timeout": 30,
+  "script": "void onMessage(session, message) {\n  def msg = JsonUtil.fromJson(message, HashMap.class);\n  String player = msg.get(\"player\");\n  Player p = manager.getPlayerManager().findById(player);\n  String payload = JsonUtil.toJson([player: player, name: p?.name, text: msg.get(\"text\")]);\n  broadcast(payload).to(player).send();\n}"
+}
+```
+
+A mensagem só chega à(s) sessão(ões) cujo `player` casa com o id informado (exige conexão com `?player=<id>` ou claim `player`).
+
+### 10.3 Anti-pattern — o que NÃO fazer
+
+```json
+{
+  "_id": "ruim",
+  "script": "void onOpen(session, config) {\n  context.put(\"count\", 0);\n}\nvoid onMessage(session, message) {\n  context.count = context.count + 1;        // NUNCA persiste entre eventos\n  broadcast(\"total: \" + context.count).send();\n}\nvoid onError(session, t) {\n  broadcast(\"erro\").send();                  // NUNCA é chamado\n}"
+}
+```
+
+Por que é errado:
+- `context` é recriado a cada evento — `count` sempre será `null`/0 no `onMessage`. Para contadores, use o `manager`/banco.
+- `onError` **não é despachado** — esse método é código morto.
+- Confiar em broadcast global em produção multi-nó: só atinge sessões do nó local.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `_id` definido com valor legível e estável (vira a URL `/ws/{_id}`) — se omitido, vira um hash gerado.
+- [ ] `script` contém ao menos um de `onOpen` / `onMessage` / `onClose` (não use `onError` — não é despachado).
+- [ ] POST retornou `status: "OK"` (não confie só no HTTP 201).
+- [ ] Para envio direcionado, confirme que os clientes conectam com `player=<id>` ou token com claim `player`.
+- [ ] `timeout` ≤ 30s é efetivo; valores maiores não contornam o `@TimedInterrupt` de 30s para laços.
+- [ ] **Armadilha:** `context` não persiste entre eventos — use o banco/manager para estado.
+- [ ] **Armadilha:** `aggregate`/`collection` (vindos do builder de IA) são ignorados — remova antes de salvar.
+- [ ] **Pré-requisito de ambiente:** confirme que o `@ServerEndpoint` `/ws/{socket}` está de fato ativo (registro programático comentado em `Configuration.java`).
+- [ ] Em deploy com múltiplos nós, lembre que broadcast não cruza o cluster.