Rotas, permissões e WebSocket para plugins nativos
Crie uma página de status que lê e altera um registro da empresa autenticada. Ao confirmar uma mudança, o backend avisa as páginas abertas pelo WebSocket do Titan Continuum. Cada página consulta novamente a API com sua própria sessão e seu próprio escopo.
Pré-requisitos
- Instalação de homologação do Titan Continuum com PHP 8.2 ou superior, MySQL com InnoDB e Workerman atendendo o WebSocket do host.
- Acesso de mantenedor para incluir código nativo revisado na distribuição. A instalação consiste em publicar a pasta do projeto em
titansource/plugins/native/statuspelo processo normal da equipe. - Um administrador de homologação e duas contas comuns de teste, com IDs conhecidos e sem dados de produção.
- Noções de PHP, PDO e JavaScript. Para preparar o ambiente do SDK, use o guia de desenvolvimento e a referência da CLI.
O tutorial usa o manifesto de um plugin nativo. Nele, permissions é um mapa de grupos e chaves. O manifesto FEX usa uma lista de chaves em permissions. Aprovar e selecionar um FEX no Plugin Manager registra a versão selecionada no catálogo. Páginas, menus e tópicos deste tutorial são registrados pelo carregador de módulos nativos.
1. Declare rotas, menu e tópicos
Crie titansource/plugins/native/status e organize os arquivos conforme a árvore abaixo.
status/
├── manifest.json
├── index.php
├── api.php
├── service.php
└── assets/
└── status.js
Salve o manifesto completo do tutorial em manifest.json.
{
"id": "empresa.status",
"name": "Status da operação",
"version": "1.0.0",
"apiVersion": 1,
"runtime": "php",
"entrypoint": "service.php",
"dependencies": [],
"permissions": {
"Status": {
"plugin_status.acessar": "Consultar e atualizar o status da operação"
}
},
"routes": {
"ext-status/index": "ext-status-atualizacoes",
"ext-status/api": "ext-status-atualizacoes"
},
"topics": {
"ext-status-atualizacoes": "plugin_status.acessar"
},
"controllers": {
"ext-status/index": "index.php",
"ext-status/api": "api.php"
},
"navigation": [
{
"path": "ext-status/index",
"label": "Status da operação",
"icon": "chart-line",
"requires": ["plugin_status.acessar"],
"badge": ""
}
],
"schemas": {"empresa_status": 1},
"assets": ["status.js"]
}
O diretório status determina a primeira parte da rota, o prefixo da permissão e o prefixo do tópico. O ID empresa.status identifica o módulo para dependências e migrações. Use reversaUrl() no PHP para gerar links válidos também para instalações montadas em um prefixo.
2. Prepare os dados de teste por empresa
O exemplo possui uma tabela de vínculos administrados pelo plugin e uma tabela de registros. A sessão do Titan identifica o usuário. A tabela de vínculos determina a empresa desse usuário neste plugin. Seu ambiente pode oferecer um serviço autorizador próprio para o vínculo. Resolva o escopo no servidor em todas as consultas.
Defina a migração e as funções de acesso aos dados em service.php.
<?php
declare(strict_types=1);
use Titan\Architect\Core\NativeMigrations;
function statusInstalar(PDO $pdo): void
{
require_once dirname(__DIR__, 3).'/nucleo/core/NativeMigrations.php';
NativeMigrations::apply($pdo, 'empresa.status', 'empresa_status', static function () use ($pdo): void {
$pdo->exec('CREATE TABLE IF NOT EXISTS empresa_status_vinculos (
user_id BIGINT UNSIGNED PRIMARY KEY,
empresa_id BIGINT UNSIGNED NOT NULL
) ENGINE=InnoDB');
$pdo->exec('CREATE TABLE IF NOT EXISTS empresa_status_registros (
empresa_id BIGINT UNSIGNED NOT NULL,
id BIGINT UNSIGNED NOT NULL,
situacao VARCHAR(20) NOT NULL,
versao INT UNSIGNED NOT NULL DEFAULT 1,
PRIMARY KEY (empresa_id, id)
) ENGINE=InnoDB');
});
}
function statusEmpresa(PDO $pdo, int $usuario): int
{
$consulta = $pdo->prepare('SELECT empresa_id FROM empresa_status_vinculos WHERE user_id=?');
$consulta->execute([$usuario]);
return (int)$consulta->fetchColumn();
}
function statusRegistro(PDO $pdo, int $empresa, int $id): ?array
{
$consulta = $pdo->prepare('SELECT id, situacao, versao FROM empresa_status_registros
WHERE empresa_id=? AND id=?');
$consulta->execute([$empresa, $id]);
$registro = $consulta->fetch(PDO::FETCH_ASSOC);
if (!$registro) {
return null;
}
return ['id' => (int)$registro['id'], 'situacao' => $registro['situacao'], 'versao' => (int)$registro['versao']];
}
function statusResponder(int $codigo, array $dados): never
{
http_response_code($codigo);
echo json_encode($dados, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
exit;
}
Após incluir o plugin na distribuição de homologação, execute statusInstalar($pdo) com a conexão da instalação. Aplique a migração pelo procedimento administrativo do ambiente, fora de transações de negócio. Para usar as instruções SQL em um banco descartável, troque 101 e 202 pelos IDs das duas contas de teste.
INSERT INTO empresa_status_vinculos (user_id, empresa_id) VALUES (101, 10), (202, 20);
INSERT INTO empresa_status_registros (empresa_id, id, situacao)
VALUES (10, 1, 'normal'), (20, 1, 'atencao'), (20, 2, 'normal');
O uso do mesmo id em empresas distintas permite verificar que a consulta depende da combinação (empresa_id, id).
3. Proteja o controlador da página e a API
Salve este index.php. O cabeçalho da aplicação carrega o cliente WebSocket e aplica o menu da sessão.
<?php
declare(strict_types=1);
$raiz = dirname(__DIR__, 3);
require_once $raiz.'/config/database.php';
verificarAutenticacao();
reversaExigirPermissao('plugin_status.acessar');
$esc = static fn (string $valor): string => htmlspecialchars($valor, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$tituloPagina = 'Status da operação';
require $raiz.'/includes/header.php';
?>
<section aria-labelledby="status-titulo" data-status-app
data-api="<?= $esc(reversaUrl('ext-status/api')) ?>"
data-csrf="<?= $esc(reversaCsrfToken()) ?>">
<h1 id="status-titulo">Status da operação</h1>
<p data-situacao aria-live="polite">Carregando status.</p>
<form data-status-form>
<label for="status-situacao">Nova situação</label>
<select id="status-situacao" name="situacao">
<option value="normal">Normal</option>
<option value="atencao">Atenção</option>
</select>
<button type="submit" disabled>Salvar</button>
</form>
<p data-status-mensagem role="status"></p>
</section>
<script src="<?= $esc(reversaUrl('plugin-assets/status/status.js')) ?>" defer></script>
<?php
require $raiz.'/includes/footer.php';
echo '</div></body></html>';
Salve este api.php. O GET lê o registro. O POST revalida o método, a sessão, a permissão, o CSRF, o vínculo e o registro da empresa. A versão esperada impede que a gravação sobrescreva silenciosamente uma mudança concorrente.
<?php
declare(strict_types=1);
$raiz = dirname(__DIR__, 3);
require_once $raiz.'/includes/resposta.php';
require_once __DIR__.'/service.php';
reversaCabecalho('Content-Type: application/json; charset=utf-8');
reversaCabecalho('Cache-Control: no-store, private');
if (!defined('REVERSA_WEBSOCKET_EXECUCAO') || REVERSA_WEBSOCKET_EXECUCAO !== true) {
statusResponder(405, ['ok' => false, 'erro' => 'Use o WebSocket do Titan.']);
}
require_once $raiz.'/config/database.php';
verificarAutenticacao();
reversaExigirPermissao('plugin_status.acessar');
$metodo = $_SERVER['REQUEST_METHOD'] ?? '';
if (!in_array($metodo, ['GET', 'POST'], true)) {
statusResponder(405, ['ok' => false, 'erro' => 'Método não permitido.']);
}
if ($metodo === 'POST') {
reversaCsrfExigir();
}
$empresa = statusEmpresa($pdo, (int)$_SESSION['usuario_id']);
if ($empresa < 1) {
statusResponder(403, ['ok' => false, 'erro' => 'Sua conta não tem empresa vinculada neste plugin.']);
}
$entrada = $metodo === 'POST' ? $_POST : $_GET;
$id = filter_var($entrada['id'] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if ($id === false) {
statusResponder(422, ['ok' => false, 'erro' => 'Informe um ID válido.']);
}
if ($metodo === 'GET') {
$registro = statusRegistro($pdo, $empresa, $id);
if ($registro === null) {
statusResponder(404, ['ok' => false, 'erro' => 'Registro não encontrado.']);
}
statusResponder(200, ['ok' => true, 'registro' => $registro]);
}
$situacao = $_POST['situacao'] ?? null;
$versao = filter_var($_POST['versao'] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if (!in_array($situacao, ['normal', 'atencao'], true) || $versao === false) {
statusResponder(422, ['ok' => false, 'erro' => 'Situação ou versão inválida.']);
}
try {
$pdo->beginTransaction();
$atualizar = $pdo->prepare('UPDATE empresa_status_registros SET situacao=?, versao=versao+1
WHERE empresa_id=? AND id=? AND versao=?');
$atualizar->execute([$situacao, $empresa, $id, $versao]);
if ($atualizar->rowCount() !== 1) {
$pdo->rollBack();
if (statusRegistro($pdo, $empresa, $id) === null) {
statusResponder(404, ['ok' => false, 'erro' => 'Registro não encontrado.']);
}
statusResponder(409, ['ok' => false, 'erro' => 'O registro mudou. Atualize a página antes de gravar.']);
}
$pdo->commit();
} catch (Throwable $erro) {
if ($pdo->inTransaction()) {
$pdo->rollBack();
}
throw $erro;
}
require_once $raiz.'/includes/realtime.php';
$eventoPublicado = true;
try {
reversaWsPublicar($pdo, 'ext-status-atualizacoes');
} catch (Throwable $erro) {
$eventoPublicado = false;
error_log('empresa.status: atualização confirmada, aviso WebSocket indisponível.');
}
statusResponder(200, ['ok' => true, 'evento_publicado' => $eventoPublicado]);
reversaExigirPermissao() valida a autorização da sessão em cada entrada. O escopo do objeto continua na consulta SQL. Uma página oculta no menu e um usuário com permissão concedida sem vínculo são casos distintos. Neste tutorial, a mesma chave concede consulta e edição. Em um plugin com perfis diferentes, declare e exija chaves específicas nas ações de escrita.
O aviso sai depois do commit. Uma falha de publicação posterior produz evento_publicado: false, com a operação já confirmada. Para eventos com garantia de entrega e reprocessamento, use a fila transacional descrita na arquitetura.
4. Atualize a página ao receber o aviso
Salve este assets/status.js. O fetch do Titan encaminha operações registradas do mesmo host pelo WebSocket. Use URLSearchParams ou FormData para os campos de POST. O cliente fornece observe() e devolve uma função para cancelar a observação.
(() => {
'use strict';
const app = document.querySelector('[data-status-app]');
if (!app) return;
const form = app.querySelector('[data-status-form]');
const botao = form.querySelector('button');
const texto = app.querySelector('[data-situacao]');
const mensagem = app.querySelector('[data-status-mensagem]');
const live = window.ReversaRealtime;
const url = new URL(app.dataset.api, location.href);
url.searchParams.set('id', '1');
let versao = null;
let gravando = false;
let ultimaConsulta = 0;
async function consultar() {
const consulta = ++ultimaConsulta;
try {
const resposta = await fetch(url, {headers: {Accept: 'application/json'}});
if (!resposta.ok) throw new Error('Consulta indisponível.');
const {registro} = await resposta.json();
if (consulta !== ultimaConsulta) return;
versao = registro.versao;
texto.textContent = registro.situacao === 'normal' ? 'Normal' : 'Atenção';
} catch {
if (consulta !== ultimaConsulta) return;
versao = null;
texto.textContent = 'Status indisponível.';
} finally {
botao.disabled = gravando || versao === null;
}
}
if (!live?.supports(url)) {
texto.textContent = 'Rota indisponível. Confira a instalação e recarregue a página.';
return;
}
const parar = live.observe('ext-status-atualizacoes', consultar);
window.addEventListener('pagehide', (evento) => { if (!evento.persisted) parar(); });
form.addEventListener('submit', async (evento) => {
evento.preventDefault();
if (gravando || versao === null) return;
gravando = true;
botao.disabled = true;
mensagem.textContent = '';
try {
const corpo = new URLSearchParams(new FormData(form));
corpo.set('id', '1');
corpo.set('versao', String(versao));
const resposta = await fetch(url, {
method: 'POST',
headers: {Accept: 'application/json', 'X-CSRF-Token': app.dataset.csrf},
body: corpo,
});
const dados = await resposta.json();
if (!resposta.ok) {
mensagem.textContent = dados.erro ?? 'Gravação recusada.';
} else {
mensagem.textContent = dados.evento_publicado
? 'Atualização salva.' : 'Atualização salva. Aviso às outras páginas indisponível.';
}
} catch {
mensagem.textContent = 'Confira a situação atual antes de tentar salvar novamente.';
} finally {
await consultar();
gravando = false;
botao.disabled = versao === null;
}
});
})();
observe() recebe o nome de um tópico ou uma lista. O callback é agendado quando a conexão fica pronta, quando ela retorna e quando o tópico muda. Ele também pode rodar ao voltar para uma aba visível. Use {initial: false} quando já fizer a primeira leitura por outro caminho. O callback recebe um aviso de mudança sem os dados do registro, pode agrupar mudanças próximas e deve sempre ler o estado atual pela API. As sessões autorizadas no tópico podem observar o momento do aviso. Preserve informações da empresa e identificadores de objetos no endpoint com escopo.
Fluxo de uma alteração
Navegador A autenticado
→ POST ext-status/api pelo WebSocket, com CSRF e versão esperada
→ controlador valida permissão, empresa e registro
→ transação confirma a alteração
→ reversaWsPublicar grava o tópico autorizado
→ Workerman notifica sessões com a permissão do tópico
→ observe agenda nova leitura no navegador B
→ GET ext-status/api reaplica autorização e escopo do navegador B
Referência do manifesto e do transporte
| Campo ou API | Contrato do exemplo |
|---|---|
id |
ID namespaced empresa.status. A instalação usa o diretório status. O prefixo titan. é reservado aos módulos distribuídos pelo Titan. |
routes |
Mapa de caminho lógico sem barra inicial ou .php para tópico. Extensões nativas adotam ext-<diretório>/<rota> e declaram cada controlador. |
controllers |
Mapa da mesma chave de rota para um arquivo PHP na raiz do plugin. |
permissions |
Mapa de grupo para chave e rótulo. Para status, a chave começa com plugin_status.. Para um diretório com hífen, o prefixo de permissão usa _ no lugar do hífen. |
topics |
Mapa de canal para uma permissão declarada pelo próprio plugin. Use ext-<diretório>-<sinal> com até 32 bytes ASCII. O diretório pode incluir hífens. O sinal segue [a-z][a-z0-9]*. |
navigation |
path aponta para a rota e requires lista as permissões exigidas no menu. label, icon e badge completam a entrada. |
assets |
Caminhos públicos relativos a assets/. A URL usa /plugin-assets/<diretório>/<arquivo>. Mantenha constantes privadas, dados de empresas e código PHP fora dessa lista. |
reversaWsPublicar($pdo, $topico) |
Registra um aviso do tópico ativo. Canal personalizado ausente ou bloqueado é recusado. O código responsável publica explicitamente depois do commit. |
window.ReversaRealtime.observe(topic, callback, options) |
Agenda leituras após avisos e no ciclo de conexão. Retorna função de cancelamento. |
window.ReversaRealtime.supports(url) |
Confere se a operação está registrada para o transporte no navegador. A validação de acesso ocorre no servidor. |
Homologue com e sem permissão
- Publique a pasta de teste com o procedimento normal da instalação e confirme
empresa.statusno catálogo nativo. Aplique a migração e os dados de teste. Confirme que o WebSocket está conectado no navegador. - Em Administração, confira o grupo Status. Conceda
plugin_status.acessarà primeira conta comum. Entre com ela em dois navegadores ou janelas isoladas e abra Status da operação. - Grave uma alteração na primeira janela. A segunda deve consultar a API de novo. Confira o quadro
changeddo WebSocket e as consultas no painel de rede. O quadro deve conter o nome do tópico. Busque o estado de cada empresa pela API. - Use a segunda conta comum sem concessão. O menu deve sumir. Acesse a rota da página diretamente e chame a API por
fetchde uma página autenticada da mesma instalação. Confira HTTP 403 e ausência da notificação do tópico nessa sessão. A API deve negar antes de consultar ou alterar os dados do plugin. - Conceda a permissão à segunda conta e abra uma sessão nova. Para
id=1, confirme que cada conta vê o próprio registro. Paraid=2, a primeira deve receber 404. Verifique no banco de homologação que a escrita nunca altera um registro da outra empresa. - Com uma conta autorizada, envie um
POSTde homologação sem CSRF ou com token inválido. Confira a recusa e ausência da gravação. Em duas sessões autorizadas da mesma empresa, envie uma versão desatualizada e confirme HTTP 409. - Interrompa e restabeleça a conexão em uma janela de teste. A interface deve buscar o estado atual. Suspenda o módulo na próxima distribuição de homologação e confirme que autenticação, Home, Perfil e Plugin Manager continuam acessíveis. As rotas e o tópico de Status devem sair do catálogo ativo.
Resultados esperados e diagnóstico
| Resposta ou sintoma | Verificação |
|---|---|
401 na API |
Verifique a sessão da conexão WebSocket. Entre novamente ou recarregue após a troca de conta. |
403 com sessão ativa |
Confirme a permissão do plugin, o vínculo de empresa e o CSRF no POST. |
404 da página ou do recurso público |
Confirme a pasta, o manifesto, o mapa de controladores, o catálogo ativo e o caminho relativo do arquivo. |
404 da API para um registro |
Confira o ID e o vínculo da conta. Objetos de outra empresa seguem a mesma resposta de um objeto ausente. |
405 em acesso HTTP direto à API |
Faça a consulta a partir de uma página autenticada com o cliente WebSocket inicializado. |
409 |
Leia o registro novamente. O usuário pode conferir a versão atual antes de decidir pela gravação. |
422 |
Confira o formato dos campos. O exemplo aceita normal ou atencao e inteiros positivos para ID e versão. |
| Rota indisponível no cliente | Confira supports(url) e o manifesto ativo. O WebSocket recusa requisições que indiquem uma operação fora do catálogo. |
| A tela grava, mas outra janela fica antiga | Verifique evento_publicado, a conexão, a chave de permissão do tópico e as consultas disparadas por observe. As abas ocultas voltam a consultar ao ficarem visíveis. |
Conexão perdeu a resposta durante o POST |
Releia o estado antes de repetir. A transação pode ter sido confirmada. |