Fonctionnement

Le principe de fonctionnement : le pont, le moteur par session, les jetons de lancement, l'octroi de licence signé, les vérifications périodiques, les sièges, la règle d'origine, et l'emplacement des identifiants.

SQLly Embedded divise SQLly en deux : la moitié qui a besoin de secrets et celle qui n'en a pas. L'interface SQLly s'exécute dans le navigateur de vos utilisateurs en tant que WebAssembly. Tout ce qui touche à une base de données s'exécute sur votre serveur, dans le bridge SQLly et les moteurs qu'il lance. Votre application web se place à côté du bridge et lui indique qui peut ouvrir SQLly avec quelles connexions. Cette page explique chaque rouage et pourquoi il est conçu ainsi.

L'architecture

Architecture de SQLly Embedded Le navigateur de l'utilisateur charge SQLly depuis votre application web et se connecte au pont SQLly via un WebSocket. Votre application pilote le pont via son API de gestion en boucle locale. Le pont exécute un moteur SQLly par session, qui se connecte à vos bases de données. Le pont vérifie sa licence auprès de sqlly.app toutes les 20 minutes. vos utilisateurs votre serveur sqlly.app Navigateur SQLly (WebAssembly) aucun mot de passe ici Votre application web connexion · qui obtient quel profil · sert web/ sqlly-bridge intégré :8444 /proxy (navigateurs, wss) :8445 /manage (votre application, boucle locale) profils · jetons · sièges · licence sqlly-cli engine un par session Vos bases de données tout moteur SQLly sqlly.app signe une licence autorisation par check-in https wss jeton porteur stdio check-in toutes les 20 min
Les chemins bleus transportent le travail de vos utilisateurs ; le chemin en pointillés est l'enregistrement de la licence, qui ne transporte ni requêtes, ni résultats, ni identifiants. Les licences hors ligne le suppriment entièrement.

Pourquoi la séparation

  • Les secrets restent côté serveur. Un navigateur ne peut pas cacher un mot de passe de base de données à son propre utilisateur. Donc le navigateur n'en reçoit jamais. Il reçoit une liste de connexions, envoie des trames de requêtes, et le pont les exécute avec des identifiants que seul le serveur possède.
  • Votre application reste responsable de l’identité. Le pont n'a pas de comptes utilisateurs. Votre application sait déjà qui est connecté. Elle dit au pont « ouvrir SQLly pour cet utilisateur avec cet profil » en créant un jeton de lancement, et le pont fait confiance au jeton.
  • Un moteur par session. Chaque onglet du navigateur a son propre sqlly-cli processus, donc les sessions ne partagent jamais l'état des connexions, les transactions ou les tables temporaires, et un crash ferme un onglet, pas le pont.

Dans le pont

sqlly-bridge embedded est un processus avec trois tâches :

TravailÉcoute surCommunique avec
Proxy navigateur: accepte un WebSocket par onglet SQLly, vérifie son Origine et le jeton de lancement, démarre un moteur avec le profil du jeton et relaie les trames dans les deux sens.--bind, par défaut 0.0.0.0:8444, chemin /proxyNavigateurs (mettre TLS devant)
API de gestion: profils, jetons de lancement, sièges, tests de connexion, statut de la licence et journal d'audit des requêtes. Référence.--manage-bind, par défaut 127.0.0.1:8445Uniquement le côté serveur de votre application, avec un jeton porteur
Moniteur de licence: contacte sqlly.app au démarrage et toutes les 20 minutes (connecté), ou relit le fichier de licence toutes les minutes (hors ligne), et fait transiter le pont entre les états de licence.Riensqlly.app via HTTPS (connecté uniquement)

Son répertoire d'état (--state-dir, créé propriétaire uniquement sur Linux et macOS) contient chaque profil comme profiles/<id>.json, la dernière autorisation de licence valide (license.json), la clé d'une installation liée (license-key, mode 0600), les fichiers d'identification par session qu'il remet à ses moteurs, et la piste d'audit des requêtes (queries.jsonl: chaque requête exécutée lors d'une session, avec son texte SQL). Sauvegardez-la et gardez-la aussi privée que vous garderiez un fichier de mots de passe, car c'en est un. Où la mettre, et ce dont Windows a besoin.

Profils : ce qu'un utilisateur peut voir

A profil est un document d'identifiants SQLly nommé : le même format JSON que l'application de bureau SQLly importe et exporte. Il liste les connexions (serveur, base de données, moteur, authentification, TLS, règles de sécurité) et les étiquettes client, projet et environnement qui les colorent et les regroupent. Votre application stocke les profils avec PUT /manage/profiles/{id}. Le pont valide l'ensemble du document dès le départ et signale tous les problèmes d'un coup, donc une faute de frappe comme "pasword" échoue bruyamment au lieu d'être ignorée.

Les utilisateurs n'appartiennent pas à des profils dans le pont. Chaque lancement en définit un. Donnez aux analystes un profil en lecture seule (une étiquette avec only_allow_select, ou block_all_but_select sur la connexion : le moteur refuse tout sauf SELECT avant d'atteindre la base de données) et au personnel de support un autre, ou créez un profil par client dans une application multi-locataire. Les moteurs basés sur des fichiers (SQLite, DuckDB) sont refusés sauf si le pont est démarré avec --allow-file-engines, car ils donnent aux utilisateurs un accès aux fichiers sur l'hôte du pont. Pour donner à quelqu'un moins de connexions, créez un autre profil. Lorsqu'une session s'ouvre, le navigateur reçoit le catalogue: noms de connexion, moteurs, bases de données et étiquettes, avec tous les secrets supprimés. La modification d'un profil s'applique au lancement suivant. Les sessions déjà ouvertes conservent le catalogue avec lequel elles ont commencé.

Le cycle de vie d’une session

Lancement de SQLly pour un utilisateur Le navigateur demande SQLly à votre application. Votre application génère un jeton de lancement via le pont et renvoie la page SQLly avec l'URL du proxy et le jeton. Le navigateur ouvre un WebSocket vers le pont avec le jeton. Le pont vérifie l'origine, le jeton, la licence et le nombre de sièges, démarre un moteur avec les identifiants du profil, puis envoie au navigateur un hello avec le catalogue de connexions et l'état de la licence. Les trames de requête circulent ensuite du navigateur, à travers le pont et le moteur, jusqu'à la base de données et reviennent. Navigateur Votre application Pont Moteur Base de données 1 ouvrir SQLly (connecté) 2 POST /manage/tokens 3 201 {token, proxyUrl} 4 Page SQLly + jeton 5 wss /proxy?token=… (Origine vérifiée) 6 démarrer, avec les identifiants 7 hello {catalog, license} - pas de secrets 8 trame de requête SQL lignes 9 les résultats reviennent en flux Le jeton peut être réutilisé jusqu'à son expiration (rechargements de page) ; la fermeture du dernier onglet libère immédiatement le siège.
Les étapes 2 à 4 sont la seule partie que votre application implémente. Tout ce qui suit l'ouverture du WebSocket se passe entre le navigateur et le pont.
  1. Un utilisateur connecté ouvre la page SQLly dans votre application.
  2. Votre serveur appelle POST /manage/tokens avec votre identifiant pour l'utilisateur et le profil à lui attribuer, et éventuellement ce qu'il faut ouvrir : des onglets de requête avec leur script, leur connexion, leurs valeurs de paramètres et leur curseur (contexte de lancement).
  3. Le pont vérifie la licence et le nombre de sièges, capture le profil, et renvoie un jeton aléatoire, sa date d'expiration et l'URL publique du proxy.
  4. Votre serveur renvoie la page SQLly (web/index.html) avec deux variables globales définies auparavant boot.js: SQLLY_PROXY_URL et SQLLY_PROXY_TOKEN.
  5. SQLly ouvre wss://…/proxy?token=…. Le pont vérifie, dans l'ordre : le navigateur Origin (refusé lors de la mise à niveau avec 403), le jeton, la licence, les sessions ouvertes de l'utilisateur et sa propre limite de session. Un navigateur ne peut pas lire pourquoi une mise à niveau a échoué, donc chaque refus après la vérification de l'origine est transmis sur le socket ouvert comme un error message avec la raison, suivi du code de fermeture 4000 + HTTP status (4401 jeton inconnu ou expiré, 4503 licence invalide, 4429 limite de session); SQLly affiche la phrase.
  6. Le pont écrit les identifiants du profil dans un fichier privé par session et démarre sqlly-cli en mode moteur avec celui-ci.
  7. Le navigateur reçoit un message hello portant le catalogue de connexion sans secrets et l'état actuel de la licence. La première session d'un jeton généré avec le contexte de lancement reçoit également les onglets à ouvrir ; SQLly les charge mais n'exécute rien.
  8. À partir de ce point, les requêtes de SQLly (connecter, exécuter, annuler, récupérer des métadonnées pour IntelliSense, parcourir les résultats) circulent sous forme de trames binaires. Le pont les relaie au moteur, enregistre chaque requête et modification de ligne dans son piste d'audit, et les refuse avec un message si la licence cesse d'être valide.

Sièges et sessions

A poste est un identifiant utilisateur distinct qui a une session ouverte ou un jeton de lancement non expiré. Les places sont simultanées, pas nominatives : quand le dernier onglet d'un utilisateur se ferme et que son dernier jeton expire, la place se libère immédiatement et quelqu'un d'autre peut l'utiliser. Le pont compte les places sur tous les ponts de la licence, car sqlly.app recense les utilisateurs des autres instances à chaque enregistrement.

  • La création pour un utilisateur qui possède déjà détient une place réussit toujours. L'émission d'une licence pour un nouvel utilisateur quand toutes les places sont prises échoue avec 409 seat_limit, de sorte que votre application peut afficher un message clair.
  • Chaque siège peut accueillir sessionsPerSeat onglets ouverts : quatre sur des forfaits payants, un sur l'essai. Un onglet supplémentaire en est informé et fermé (code 4429). Le pont envoie un ping à chaque onglet et abandonne celui qui reste silencieux pendant 90 secondes, si bien qu'un onglet perdu parce qu'un ordinateur portable est passé en veille libère sa session tout seul ; quand le dernier onglet d'un utilisateur se ferme, ses jetons de lancement expirent sous deux minutes.
  • DELETE /manage/seats/{user} révoque les jetons d'un utilisateur et ferme ses sessions. Appelez-le lorsqu'une personne se déconnecte de votre application ou perd l'accès.
  • L'identifiant utilisateur est celui que vous transmettez. Utilisez un identifiant stable et opaque (une clé de base de données ou un hachage) si vous préférez ne pas envoyer d'adresses e-mail : les identifiants occupant des sièges sont transmis à sqlly.app afin que les sièges puissent être comptés entre les ponts.

Qui peut se connecter : la règle d'origine

Chaque licence est liée à un seul domaine. Le pont n'accepte un WebSocket de navigateur que lorsque son Origin en-tête correspond à ce domaine ou à n'importe quel sous-domaine de celui-ci (à n'importe quelle profondeur, schéma ou port), ou localhost / 127.0.0.1 / [::1] tandis que --allow-localhost-origins est activé (par défaut, pour le développement). Une licence sans domaine lié n'admet que localhost. Liez le domaine sur votre page Embedded, ou démarrez le pont une fois avec --domain.

L’API de gestion n’envoie aucun en-tête CORS. C’est du serveur à serveur : un navigateur sur une autre origine ne peut pas l’appeler, et de toute façon elle devrait être liée au loopback.

Comment la licence est appliquée

Le pont fait confiance à une seule chose : une octroi de licence, un JWS compact que sqlly.app signe avec ES384 (ECDSA P-384). La clé de vérification est compilée dans le pont. Chaque autorisation (postes, sessions par poste, instances du pont, domaine, fin de période, jours de grâce, fonctionnalités) est lue à partir des revendications signées de l'octroi. Le JSON non signé autour n'est utilisé qu'à des fins d'affichage.

Licences connectées

  • Au démarrage et toutes les 20 minutes, le pont envoie POST /api/embedded/checkin avec sa clé de licence, son identifiant d'instance, un nouveau nonce de 32 octets, sa version et son nom d'hôte, le domaine pour lequel il a été démarré, et les identifiants des utilisateurs occupant actuellement des places.
  • L'autorisation (grant) contenue dans la réponse doit se vérifier avec la clé intégrée à la compilation, renvoyer ce nonce, nommer cette instance et la même licence, et avoir été émise à moins de 5 minutes de l'horloge du pont. Une réponse rejouée ou falsifiée échoue à ces vérifications et compte comme une vérification en échec. Maintenez l'horloge de l'hôte à l'heure (NTP).
  • Une autorisation est valable pendant 40 minutes. Si sqlly.app n'est pas joignable, le pont continue de fonctionner avec sa dernière autorisation valide jusqu'à son expiration, puis devient obsolète et refuse de travailler jusqu'au prochain contact réussi, sans qu'un redémarrage soit nécessaire. Un pont redémarré pendant une panne repart de son octroi mis en cache tant que celui-ci n'a pas expiré.
  • Chaque licence connectée permet un certain nombre d' instances de pont simultanément (un par défaut). Un deuxième pont sur la même clé est enregistré mais non admis tant que le premier continue de se manifester. Un pont qui s'arrête proprement libère sa place immédiatement. Un pont qui meurt la libère 40 minutes plus tard.

Licences hors ligne

Une licence hors ligne est un fichier ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }) que vous téléchargez depuis sqlly.app une fois que son domaine est défini. L'autorisation à l'intérieur est de longue durée : elle expire à la fin de la période plus les jours de grâce. Le pont la vérifie localement, ne contacte jamais aucun serveur SQLly, et relit le fichier chaque minute, donc pour renouveler, il suffit de remplacer le fichier. Les licences hors ligne n'ont pas de limite d'instance.

Installations liées

Un pont démarré sans clé et sans fichier est sans licence: l'API de gestion fonctionne (vous pouvez configurer et tester des profils) mais les lancements sont refusés. Votre application admin peut alors la lier sans que personne ne copie une clé : elle demande à sqlly.app un code de liaison, le propriétaire de la licence l'approuve dans son navigateur, et l'application récupère une clé émise uniquement pour cette installation et la remet au pont avec PUT /manage/license. Le pont la vérifie, la stocke et continue de l'utiliser à chaque redémarrage. Chaque installation liée a sa propre clé, donc le propriétaire peut en révoquer une sans toucher aux autres. Comment le construire.

Lorsque la licence n'est pas valide

Dans tous les états sauf ok et grace, le pont garde les sockets ouverts mais répond à chaque trame de requête par un échec portant une phrase simple (« …n’a pas pu confirmer sa licence avec sqlly.app pendant 40 minutes ; demandez à votre administrateur de vérifier. »). Le client SQLly affiche cette phrase dans sa ligne d’état et comme notification, afin que les utilisateurs sachent pourquoi. Les nouvelles sessions reçoivent la même phrase et sont fermées (code 4503), et les jetons de lancement sont refusés avec 503 license_not_ok. Pendant la période de grâce de 15 jours après la fin d’une période, tout fonctionne mais chaque utilisateur voit un compte à rebours. Chaque état, expliqué.

Ce qui quitte votre serveur

Envoyé à sqlly.app lors de la vérificationJamais envoyé ailleurs
Clé de licence · ID de l'instance du pont · version du pont · nom d'hôte · domaine demandé · ID des utilisateurs occupant des places · nombre de sessions ouvertes Requêtes · résultats · noms et hôtes de bases de données · identifiants · profils · tout ce que vos utilisateurs tapent

Les licences hors ligne n'envoient rien du tout. Le navigateur communique uniquement avec votre application et votre pont.