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

Arquitetura do SQLly Embedded O navegador do usuário carrega o SQLly do seu aplicativo web e se conecta à ponte SQLly via WebSocket. Seu aplicativo controla a ponte através de sua API de gerenciamento de loopback. A ponte executa um mecanismo SQLly por sessão, que se conecta aos seus bancos de dados. A ponte verifica sua licença com sqlly.app a cada 20 minutos. seus usuários seu servidor sqlly.app Navegador SQLly (WebAssembly) sem senhas aqui Seu aplicativo web login · quem recebe qual perfil · serve web/ sqlly-bridge incorporado :8444 /proxy (navegadores, wss) :8445 /manage (seu app, loopback) perfis · tokens · assentos · licença sqlly-cli engine um por sessão Seus bancos de dados qualquer mecanismo do SQLly sqlly.app assina uma licença concessão por check-in https wss token de portador stdio check-in a cada 20 min
Os caminhos azuis carregam o trabalho dos seus usuários; o caminho tracejado é o check-in da licença, que não leva consultas, resultados nem credenciais. Licenças offline eliminam esse caminho por completo.

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-cli processo, 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:

JobEscuta emFala 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 /proxyNavegadores (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:8445Somente 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.Nadasqlly.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

Iniciando o SQLly para um usuário O navegador pede o SQLly ao seu aplicativo. Seu aplicativo gera um token de inicialização a partir da ponte e devolve a página do SQLly com a URL do proxy e o token. O navegador abre um WebSocket com a ponte usando o token. A ponte confere Origin, token, licença e assentos, inicia um mecanismo com as credenciais do perfil e manda ao navegador um hello com o catálogo de conexões e o estado da licença. Os frames de consulta então fluem do navegador pela ponte e pelo mecanismo até o banco de dados, e de volta. Navegador Seu aplicativo Ponte Motor Banco de dados 1 abrir SQLly (com login feito) 2 POST /manage/tokens 3 201 {token, proxyUrl} 4 Página do SQLly + token 5 wss /proxy?token=… (Origem verificada) 6 start, com credenciais 7 hello {catalog, license} - sem segredos 8 frame de consulta SQL linhas 9 os resultados voltam em streaming O token pode ser reutilizado até expirar (recarregamento da página); fechar a última aba libera o assento imediatamente.
Os passos 2-4 são a única parte que seu aplicativo implementa. Tudo após a abertura do WebSocket ocorre entre o navegador e a ponte.
  1. Um usuário autenticado abre a página do SQLly no seu aplicativo.
  2. Seu servidor chama POST /manage/tokens com 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).
  3. 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.
  4. Seu servidor retorna a página SQLly (web/index.html) com duas variáveis globais definidas antes boot.js: SQLLY_PROXY_URL e SQLLY_PROXY_TOKEN.
  5. O SQLly abre wss://…/proxy?token=…. A ponte verifica, na ordem: o navegador Origin (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 uma error mensagem com o motivo, seguida pelo código de fechamento 4000 + HTTP status (4401 token desconhecido ou expirado, 4503 licença não válida, 4429 limite de sessão); SQLly mostra a sentença.
  6. A ponte escreve as credenciais do perfil em um arquivo privado por sessão e inicia sqlly-cli no modo de engine com ele.
  7. 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.
  8. 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 sessionsPerSeat abas 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/checkin com 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-inNunca 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.