Como funciona
Como funciona por dentro: a ponte, o mecanismo por sessão, os tokens de inicialização, a concessão de licença assinada, os check-ins, os assentos, a regra de Origin e onde ficam as credenciais.
O SQLLY Embedded divide o SQLLY em uma metade que precisa de segredos e outra que não precisa. A interface do SQLLY roda no navegador do usuário como WebAssembly. Tudo o que toca um banco de dados roda no seu servidor, dentro da ponte do SQLLY e dos mecanismos que ela inicia. Seu aplicativo web fica ao lado da ponte e informa quem pode abrir o SQLLY com quais conexões. Esta página explica cada componente e por que ele foi construído assim.
A arquitetura
Por que a divisão
- Segredos permanecem no lado do servidor. Um navegador não consegue esconder uma senha de banco de dados do próprio usuário. Então o navegador nunca recebe uma. Ele recebe a lista de conexões, envia frames de consulta, e a ponte os executa com credenciais que só o servidor guarda.
- Seu aplicativo continua responsável pela identidade. A ponte não tem contas de usuário. Seu aplicativo já sabe quem está com a sessão aberta. Ele diz à ponte «abra o SQLly para este usuário com este perfil" emitindo um token de inicialização, e a ponte confia no token.
- Um mecanismo por sessão. Cada aba do navegador recebe seu próprio
sqlly-cliprocesso, então as sessões nunca compartilham estado de conexão, transações ou tabelas temporárias, e uma falha derruba apenas uma aba, não a ponte.
Dentro da ponte
sqlly-bridge embedded é um processo só, com três funções:
| Job | Escuta em | Fala com |
|---|---|---|
| Proxy do navegador: aceita um WebSocket por aba do SQLly, verifica a Origem e o token de inicialização, inicia um motor com o perfil do token e retransmite os frames nos dois sentidos. | --bind, padrão 0.0.0.0:8444, caminho /proxy | Navegadores (coloque TLS na frente) |
| API de gerenciamento: perfis, tokens de inicialização, assentos, testes de conexão, status da licença e trilha de auditoria de consultas. Referência. | --manage-bind, padrão 127.0.0.1:8445 | Somente do lado do servidor do seu aplicativo, com um token bearer |
| Monitor de licença: verifica no sqlly.app na inicialização e a cada 20 minutos (conectado), ou relê o arquivo de licença a cada minuto (offline), e move a ponte entre os estados de licença. | Nada | sqlly.app via HTTPS (somente conectado) |
Seu diretório de estado (--state-dir, criado apenas para o proprietário no Linux e macOS) mantém cada perfil como profiles/<id>.json, a última concessão de licença válida (license.json), a chave de uma instalação vinculada (license-key, modo 0600), os arquivos de credenciais por sessão que ele entrega aos seus mecanismos e a trilha de auditoria de consultas (queries.jsonl: cada consulta que uma sessão executou, com seu texto SQL). Faça um backup e guarde-o com a mesma privacidade de um arquivo de senhas, porque é um. Onde colocá-la, e o que o Windows precisa.
Perfis: o que um usuário pode ver
A perfil é um documento de credenciais do SQLly com nome: o mesmo formato JSON que o app desktop do SQLly importa e exporta. Ele lista conexões (servidor, banco de dados, motor, autenticação, TLS, regras de segurança) e os rótulos de cliente, projeto e ambiente que as colorem e agrupam. Seu app armazena perfis com PUT /manage/profiles/{id}. A ponte valida o documento inteiro de uma vez e relata todos os problemas ao mesmo tempo, então um erro de digitação como "pasword" falha de forma evidente em vez de ser ignorado.
Os usuários não pertencem a perfis na ponte. Cada inicialização nomeia um. Dê aos analistas um perfil somente leitura (uma etiqueta com only_allow_select, ou block_all_but_select na conexão: o mecanismo recusa qualquer coisa que não seja SELECT antes de chegar ao banco de dados) e outra para o pessoal de suporte, ou crie um perfil por cliente em um aplicativo multi-inquilino. Mecanismos baseados em arquivos (SQLite, DuckDB) são recusados, a menos que a ponte seja iniciada com --allow-file-engines, porque eles dão acesso a arquivos aos usuários no host da ponte. Para dar a alguém menos conexões, crie outro perfil. Quando uma sessão é aberta, o navegador recebe o catálogo: nomes de conexão, motores, bancos de dados e etiquetas, com todos os segredos removidos. Editar um perfil se aplica à próxima execução. Sessões já abertas mantêm o catálogo com o qual começaram.
A vida de uma sessão
- Um usuário autenticado abre a página do SQLly no seu aplicativo.
- Seu servidor chama
POST /manage/tokenscom seu ID para o usuário e o perfil que ele deve receber, e opcionalmente o que abrir: abas de consulta com o script, a conexão, os valores de parâmetro e o cursor (contexto de inicialização). - A ponte verifica a licença e a quantidade de assentos, captura o perfil e retorna um token aleatório, sua expiração e o URL do proxy público.
- Seu servidor retorna a página SQLly (
web/index.html) com duas variáveis globais definidas antesboot.js:SQLLY_PROXY_URLeSQLLY_PROXY_TOKEN. - O SQLly abre
wss://…/proxy?token=…. A ponte verifica, na ordem: o navegadorOrigin(recusado na atualização com 403), o token, a licença, as sessões abertas do usuário e seu próprio limite de sessão. Um navegador não pode ler por que uma atualização falhou, então toda recusa após a verificação de origem é entregue no socket aberto como umaerrormensagem com o motivo, seguida pelo código de fechamento4000 + HTTP status(4401 token desconhecido ou expirado, 4503 licença não válida, 4429 limite de sessão); SQLly mostra a sentença. - A ponte escreve as credenciais do perfil em um arquivo privado por sessão e inicia
sqlly-clino modo de engine com ele. - O navegador recebe um hello com o catálogo de conexões sem segredos e o estado atual da licença. A primeira sessão de um token gerado com contexto de inicialização também recebe as abas a abrir; o SQLly as carrega, mas não executa nada.
- A partir daqui, as solicitações do SQLly (conectar, executar, cancelar, buscar metadados para o IntelliSense, paginar resultados) viajam como frames binários. A ponte as retransmite ao mecanismo, registra todas as consultas e edições de linhas em seu trilha de auditoria, e as recusa com uma mensagem se a licença deixar de ser válida.
Assentos e sessões
A assento é um id de usuário distinto que tem uma sessão aberta ou um token de inicialização ainda válido. Os assentos são por concorrência, não nominais: quando a última aba de um usuário fecha e o último token dele expira, o assento fica livre na hora e outra pessoa pode usá-lo. O bridge conta os assentos em todos os bridges da licença, porque o sqlly.app informa os usuários das outras instâncias a cada check-in.
- Emitir para um usuário que já tem um assento sempre dá certo. Emitir para um usuário novo quando todos os assentos estão ocupados falha com
409 seat_limit, então seu aplicativo pode mostrar uma mensagem clara. - Cada assento pode conter
sessionsPerSeatabas abertas: quatro em planos pagos, uma no teste. Uma aba extra é avisada e fechada (código 4429). A ponte manda um ping em cada aba e descarta a que ficar em silêncio por 90 segundos, então uma aba perdida por um notebook em suspensão libera a sessão sozinha; quando a última aba de um usuário fecha, os tokens de lançamento dele expiram em até dois minutos. DELETE /manage/seats/{user}revoga os tokens de um usuário e fecha suas sessões. Chame isso quando alguém sair do seu aplicativo ou perder acesso.- O id do usuário é o que você passar. Use um id estável e opaco (uma chave de banco de dados ou um hash), se preferir não enviar endereços de e-mail: os ids que ocupam assentos são relatados ao sqlly.app para que os assentos possam ser contados entre as pontes.
Quem pode conectar: a regra de Origem
Cada licença está vinculada a um domínio. A ponte aceita um WebSocket de navegador apenas quando seu Origin cabeçalho é esse domínio ou qualquer subdomínio dele (de qualquer profundidade, esquema ou porta), ou localhost / 127.0.0.1 / [::1] enquanto --allow-localhost-origins está ativado (o padrão, para desenvolvimento). Uma licença sem domínio vinculado admite apenas localhost. Vincule o domínio em sua página Embedded, ou inicie a ponte uma vez com --domain.
A API de gerenciamento não envia nenhum cabeçalho CORS. É de servidor para servidor: um navegador em outra origem não consegue chamá-la e, de qualquer forma, ela deve estar vinculada ao loopback.
Como a licença é aplicada
A ponte confia em uma coisa: uma concessão de licença, um JWS compacto que o sqlly.app assina com ES384 (ECDSA P-384). A chave de verificação é compilada na ponte. Cada permissão (assentos, sessões por assento, instâncias da ponte, domínio, fim do período, dias de carência, funcionalidades) é lida a partir das claims assinadas da concessão. O JSON não assinado ao redor é apenas para exibição.
Licenças conectadas
- Na inicialização e a cada 20 minutos a ponte envia
POST /api/embedded/checkincom sua chave de licença, seu ID de instância, um nonce novo de 32 bytes, sua versão e nome do host, o domínio para o qual ela foi iniciada, e os IDs dos usuários que ocupam assentos no momento. - A concessão da resposta precisa validar contra a chave compilada no binário, ecoar esse nonce, nomear esta instância e a mesma licença, e ter sido emitida com no máximo 5 minutos de diferença do relógio da ponte. Uma resposta repetida ou forjada falha nessas verificações e conta como um check-in malsucedido. Mantenha o relógio do host ajustado (NTP).
- Uma concessão vale por 40 minutos. Se o sqlly.app ficar inacessível, a ponte continua servindo com a última concessão válida até ela expirar, e então vai obsoleto e se recusa a trabalhar até o próximo check-in bem-sucedido, sem necessidade de reinício. Uma ponte reiniciada durante uma interrupção começa apenas a partir de sua concessão em cache, enquanto essa concessão não tiver expirado.
- Cada licença conectada permite um número de pontes instâncias ao mesmo tempo (uma por padrão). Uma segunda ponte na mesma chave é registrada, mas não é admitida enquanto a primeira continua se reportando. Uma ponte que para corretamente libera seu slot imediatamente. Uma que morre o libera 40 minutos depois.
Licenças offline
Uma licença offline é um arquivo ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }) que você baixa do sqlly.app depois que o domínio dele está configurado. A concessão dentro dele é de longa duração: expira no fim do período mais os dias de carência. A ponte verifica tudo localmente, nunca contata nenhum servidor SQLly e relê o arquivo a cada minuto, então renovar significa substituir o arquivo. Licenças offline não têm limite de instâncias.
Instalações vinculadas
Uma ponte iniciada sem chave e sem arquivo está sem licença: a API de gerenciamento funciona (você pode configurar e testar perfis), mas as inicializações são recusadas. Assim, seu aplicativo de administração pode vinculá-lo sem que ninguém precise copiar uma chave: ele pede um código de link ao sqlly.app, o dono da licença aprova no próprio navegador, e o aplicativo recebe uma chave gerada só para esta instalação e a entrega à ponte com PUT /manage/license. A ponte a verifica, armazena e continua usando-a mesmo após reinicializações. Cada instalação vinculada tem sua própria chave, então o proprietário pode revogar uma sem afetar as outras. Como construí-lo.
Quando a licença não é válida
Em todos os estados, exceto ok e grace, a ponte mantém os sockets abertos conectados, mas responde a cada frame de requisição com uma falha que traz uma frase clara («…não foi possível confirmar a licença com o sqlly.app por 40 minutos; peça ao seu administrador para verificar.»). O cliente SQLly mostra essa frase na linha de status e como notificação, para que os usuários saibam o motivo. Novas sessões recebem a mesma frase e são fechadas (código 4503), e os tokens de lançamento são recusados com 503 license_not_ok. Durante os 15 dias de carência depois que um período termina, tudo funciona, mas cada usuário vê uma contagem regressiva. Cada estado, explicado.
O que sai do seu servidor
| Enviado para sqlly.app no check-in | Nunca enviado para lugar nenhum |
|---|---|
| Chave de licença · ID da instância do bridge · versão do bridge · nome do host · domínio solicitado · IDs de usuários com assentos · número de sessões abertas | Consultas · resultados · nomes de bancos de dados e hosts · credenciais · perfis · qualquer coisa que seus usuários digitarem |
Licenças offline não enviam nada. O navegador conversa apenas com seu app e seu bridge.