仕組み

動作原理: ブリッジ、セッションごとのエンジン、起動トークン、署名付きライセンス付与、チェックイン、シート、Origin ルール、資格情報の保管場所。

SQLly Embedded は、SQLly を、シークレットを必要とする半分と必要としない半分に分割します。SQLly の UI は WebAssembly としてユーザーのブラウザー内で動作します。データベースに触れる処理はすべて、SQLly ブリッジと、そこから起動されるエンジンの内側で、お客様のサーバー上で動作します。お客様の Web アプリはブリッジの隣に置かれ、誰がどの接続で SQLly を開けるかをブリッジに伝えます。このページでは、各構成要素と、そのように作られている理由を説明します。

アーキテクチャ

SQLly Embedded のアーキテクチャ ユーザーのブラウザは、お使いの Web アプリから SQLly を読み込み、WebSocket 経由で SQLly ブリッジに接続します。アプリは、ループバックの管理 API を通じてブリッジを操作します。ブリッジはセッションごとに 1 つの SQLly エンジンを実行し、そのエンジンがデータベースに接続します。ブリッジは 20 分ごとに sqlly.app でライセンスを確認します。 ユーザー お使いのサーバー sqlly.app ブラウザ SQLly (WebAssembly) ここにパスワードはありません Webアプリ サインイン · 誰にどのプロファイルを割り当てるか · web/ を配信 sqlly-bridge 組み込み :8444 /proxy(ブラウザ、wss) :8445 /manage(管理アプリ、ループバック) プロファイル · トークン · シート · ライセンス sqlly-cliエンジン セッションごとに 1 つ データベース 任意のSQLlyエンジン sqlly.app ライセンスに署名する チェックインごとの許諾 https wss ベアラートークン stdio 20分ごとにチェックイン
青い経路はユーザーの作業を運びます。破線の経路はライセンスのチェックインで、クエリ、結果、資格情報は一切運びません。オフライン ライセンスでは、この経路そのものがありません。

分割する理由

  • シークレットはサーバー側にとどまります。 ブラウザは、データベースのパスワードをそのユーザーから隠しておけません。だから、ブラウザはパスワードを一切受け取りません。受け取るのは接続一覧で、クエリフレームを送るだけです。実行はブリッジが担当し、認証情報はサーバーだけが保持しています。
  • IDの管理は、引き続きアプリが担います。 ブリッジにはユーザーアカウントがありません。誰がサインインしているかは、アプリがすでに把握しています。アプリがブリッジに「次のユーザーのために SQLly を開く」と伝えます これ ユーザーと これ プロファイル」の起動トークンを発行することで行い、ブリッジはそのトークンを信頼します。
  • セッションごとに 1 つのエンジン。 各ブラウザータブには専用の sqlly-cli プロセスごとに分かれているため、セッション同士が接続状態、トランザクション、一時テーブルを共有することはなく、クラッシュしても影響を受けるのは 1 つのタブだけで、ブリッジは落ちません。

ブリッジの内部

sqlly-bridge embedded は 3 つの役割を持つ 1 つのプロセスです:

ジョブ待ち受け:接続先
ブラウザプロキシ: SQLly のタブごとに WebSocket を受け入れ、その Origin と起動トークンを確認し、トークンのプロファイルでエンジンを起動し、フレームを双方向に中継します。--bind、デフォルト 0.0.0.0:8444、パス /proxyブラウザー (前段に TLS を置く)
管理API: プロファイル、起動トークン、シート、接続テスト、ライセンスステータス、およびクエリ監査トレイル。 リファレンス.--manage-bind、デフォルト 127.0.0.1:8445アプリのサーバー側からのみ、ベアラートークンを使って
ライセンスモニター: 起動時と 20 分ごとに sqlly.app にチェックインし(接続時)、またはライセンスファイルを毎分再読み込みして(オフライン時)、ブリッジをライセンス状態間で遷移させます。なしHTTPS 上で sqlly.app (接続のみ)

その ステートディレクトリ (--state-dir、Linux と macOS では所有者のみの権限で作成)には、すべてのプロファイルが次の形式で profiles/<id>.json、最後に有効だったライセンス付与(license.json)には通知が表示され、license-key、モード 0600)、エンジンに渡すセッションごとの認証情報ファイル、およびクエリの監査証跡(queries.jsonl: セッションが実行したすべてのクエリ(SQL テキスト付き)。バックアップを取り、パスワードファイルと同じくらい厳重に非公開で保管してください。実際、それがパスワードファイル相当だからです。 置く場所と、Windows に必要なもの.

プロファイル:ユーザーに見える範囲

A プロファイル は名前付きの SQLly 資格情報ドキュメントで、SQLly のデスクトップアプリがインポート/エクスポートするのと同じ JSON 形式です。接続 (サーバー、データベース、エンジン、認証、TLS、安全ルール) と、それらを色分け・グループ化するクライアント、プロジェクト、環境のラベルを一覧にします。アプリはプロファイルを次に保存します PUT /manage/profiles/{id}。ブリッジはドキュメント全体を最初に検証し、すべての問題を一度に報告するため、次のようなタイプミスも "pasword" 無視されず、はっきりと失敗します。

ユーザーはブリッジ内のプロファイルに属しません。起動のたびに 1 つ指定します。アナリストには読み取り専用のプロファイルを割り当ててください(ラベル付きの only_allow_select、または block_all_but_select を接続に設定すると、エンジンはデータベースに届く前に SELECT 以外を拒否します)。サポート担当には別のプロファイルを、マルチテナントアプリでは顧客ごとに 1 つのプロファイルを用意することもできます。ファイルベースのエンジン(SQLite、DuckDB)は、ブリッジを次のフラグ付きで起動していない限り拒否されます --allow-file-engines、そのような接続では、ユーザーがブリッジホスト上のファイルにアクセスできてしまうためです。すでに開いているセッションは、開始時のカタログのまま動作し、変更は次回の起動時に適用されます。 カタログ: 接続名、エンジン、データベース、ラベルを含み、すべてのシークレットは除去されています。プロファイルの編集は次回の起動から反映されます。すでに開いているセッションは、開始時のカタログを保持します。

セッションの一生

ユーザー向けに SQLly を起動する ブラウザーがアプリに SQLly を要求します。アプリはブリッジから起動トークンを発行し、プロキシ URL とトークンを付けた SQLly ページを返します。ブラウザーはトークンを使ってブリッジへの WebSocket を開きます。ブリッジは Origin、トークン、ライセンス、席数を確認し、プロファイルの認証情報でエンジンを起動し、接続カタログとライセンス状態を含む hello をブラウザーに送ります。その後、クエリのフレームは、ブラウザーからブリッジとエンジンを経由してデータベースへ流れ、同じ経路で戻ります。 ブラウザ アプリ ブリッジ エンジン データベース 1 SQLly を開く (サインイン済み) 2 POST /manage/tokens 3 201 {token, proxyUrl} 4 SQLlyページ+トークン 5 wss /proxy?token=… (Origin チェック済み) 6 起動 (認証情報付き) 7 hello {catalog, license} - 機密情報なし 8 クエリフレーム SQL 行 9 件の結果がストリーミングで返ってくる トークンは、有効期限が切れる(ページを再読み込みする)まで再利用できます。最後のタブを閉じると、シートはすぐに解放されます。
手順2〜4が、アプリ側で実装する唯一の部分です。WebSocket が開いたあとは、すべてブラウザとブリッジの間で行われます。
  1. サインイン済みのユーザーが、アプリ内の SQLly ページを開きます。
  2. サーバーが呼び出す POST /manage/tokens ユーザーの ID と付与するプロファイル、必要に応じて開く内容を指定します:スクリプト、接続、パラメーター値、カーソルを含むクエリタブ (起動コンテキスト).
  3. ブリッジはライセンスと席数を確認し、プロファイルを取得して、ランダムなトークンとその有効期限、公開プロキシ URL を返します。
  4. サーバーはSQLlyのページを返します(web/index.html)に、2 つのグローバル変数を次より前に設定したうえで boot.js: SQLLY_PROXY_URL そして SQLLY_PROXY_TOKEN.
  5. SQLly は wss://…/proxy?token=…。ブリッジは次の順に確認します:ブラウザーの Origin (アップグレード時に 403 で拒否)、トークン、ライセンス、ユーザーの開いているセッション、そして独自のセッション上限です。ブラウザーはアップグレードが失敗した理由を読み取れないため、オリジンチェック後のすべての拒否は、開いたソケット上で次の形で届けられます: error 理由を含むメッセージ、続いてクローズコード 4000 + HTTP status (4401 不明または期限切れのトークン、4503 ライセンスが無効、4429 セッション数の上限)。SQLly はその文言を表示します。
  6. ブリッジは、プロファイルの認証情報をセッションごとのプライベートなファイルに書き出し、起動します sqlly-cli エンジンモードで併用します。
  7. ブラウザーは、シークレットを含まない接続カタログと現在のライセンス状態を伝える hello を受け取ります。起動コンテキスト付きで発行されたトークンの最初のセッションは、開くべきタブも受け取ります。SQLly はそれらを読み込みますが、何も実行しません。
  8. 以降、SQLly のリクエスト(接続、実行、キャンセル、IntelliSense 用メタデータの取得、結果のページング)はバイナリフレームで送られます。ブリッジはそれらをエンジンに中継し、すべてのクエリと行の編集をその 監査ログ、ライセンスが無効になった場合は、メッセージを表示してそれらを拒否します。

シートとセッション

A シート は、開いているセッションまたは期限切れでない起動トークンを持つ、重複のないユーザー ID です。シートは名前付きではなく同時接続数で数えます。ユーザーの最後のタブが閉じ、最後のトークンが失効すると、シートはすぐに解放され、他の人が使えます。ブリッジは、sqlly.app が各チェックイン時に他のインスタンスのユーザーを報告するため、ライセンス内のすべてのブリッジにわたってシートを数えます。

  • 発行対象のユーザーが すでに 席を確保している場合は常に成功します。全席が使用中のときに新しいユーザー向けに発行すると、次で失敗します 409 seat_limit、そのため、アプリで分かりやすいメッセージを表示できます。
  • 各シートには sessionsPerSeat 開けるタブ数:有料プランでは 4、トライアルでは 1。超過したタブはその旨が伝えられて閉じられます(コード 4429)。ブリッジはすべてのタブに ping を送り、90 秒間応答のないタブを切断するため、スリープしたノート PC で失われたタブはセッションを自力で解放します。ユーザーの最後のタブが閉じると、その起動トークンは 2 分以内に失効します。
  • DELETE /manage/seats/{user} ユーザーのトークンを無効にし、セッションを閉じます。アプリから誰かがサインアウトしたとき、またはアクセス権を失ったときに呼び出してください。
  • ユーザー ID は、渡したものがそのまま使われます。メールアドレスを送信したくない場合は、安定した不透明な ID(データベースキーやハッシュなど)を使ってください。シートを保持している ID は sqlly.app に報告され、ブリッジをまたいでシート数を数えられます。

接続できる人: Origin ルール

各ライセンスは 1 つのドメインに紐づいています。ブリッジがブラウザーの WebSocket を受け入れるのは、その Origin ヘッダーがそのドメインまたはそのサブドメイン(階層の深さ、スキーム、ポートは問いません)である場合、または localhost / 127.0.0.1 / [::1] の間 --allow-localhost-origins は (開発用のデフォルト) オンです。ドメインが紐付けられていないライセンスは localhost のみ許可されます。ドメインを紐付けるには 埋め込みページ、またはブリッジを一度起動して --domain.

管理 API は CORS ヘッダーをまったく送信しません。これはサーバー間通信用で、別のオリジンのブラウザーからは呼び出せず、いずれにせよループバックにバインドしておくべきです。

ライセンスがどのように適用されるか

ブリッジが信頼するものは 1 つだけです: ライセンスの付与、sqlly.app が ES384(ECDSA P-384)で署名するコンパクトな JWS です。検証キーはブリッジにコンパイルされています。すべての許容量(シート、シートあたりのセッション数、ブリッジのインスタンス数、ドメイン、期間の終了日、猶予日数、機能)は、付与の署名付きクレームから読み取られます。その周りの署名なしの JSON は表示用にすぎません。

接続型ライセンス

  • 起動時と 20 分ごとに、ブリッジは次を送信します POST /api/embedded/checkin ライセンスキー、インスタンス ID、新しく発行した 32 バイトの nonce、バージョンとホスト名、起動時に指定されたドメイン、そして現在シートを保持しているユーザー ID。
  • 返信に含まれる許可は、コンパイル時に組み込まれたキーで検証でき、そのノンスをそのまま返し、このインスタンスと同じライセンスを指定し、ブリッジの時計で 5 分以内に発行されたものでなければなりません。再送された返信や偽造された返信はこれらの検証に失敗し、チェックイン失敗として数えられます。ホストの時計を正確に保ってください (NTP)。
  • グラントの有効期間は 40 分です。sqlly.app に到達できない場合、ブリッジは最後の有効なグラントが切れるまでサービスを提供し続け、その後は 古い 、そして次回のチェックインが成功するまで作業を拒否します。再起動は不要です。障害中に再起動されたブリッジは、キャッシュ済みの権限がまだ失効していない場合に限り、それを使って起動します。
  • 接続中のライセンスごとに使えるブリッジの インスタンス 同時に(デフォルトは1つ)。同じキーの2つ目のブリッジは記録されますが、最初のブリッジがチェックインを続けている間は受け入れられません。正常に停止したブリッジはスロットをすぐに解放します。異常終了したブリッジは40分後に解放します。

オフラインライセンス

オフラインライセンスはファイルです({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" })ドメインを設定すると sqlly.app からダウンロードできます。中に含まれる付与は長期有効で、期間の終了日に猶予日数を足した日に失効します。ブリッジはローカルで検証し、SQLly のサーバーには一切問い合わせず、ファイルを毎分再読み込みするため、更新はファイルを置き換えるだけで済みます。オフラインライセンスにはインスタンス数の上限はありません。

リンク済みのインストール

キーもファイルも指定せずに起動したブリッジは ライセンスなし: 管理 API は動作します(プロファイルの設定とテストが可能)が、起動は拒否されます。その場合、管理者アプリは誰もキーをコピーすることなくリンクできます。アプリが sqlly.app にリンクコードを要求し、ライセンス所有者がブラウザで承認すると、アプリはこのインストール専用に発行されたキーを受け取り、次の方法でブリッジに渡します。 PUT /manage/license。ブリッジはそれを検証して保存し、再起動後も使い続けます。リンクされたインストールにはそれぞれ専用のキーがあるため、所有者はほかに影響を与えずに 1 つだけ失効させられます。 ビルド方法.

ライセンスが有効でないとき

次を除くすべての状態で ok そして grace、ブリッジはオープンなソケットを接続したまま保持しますが、各リクエストフレームには平易な一文を添えた失敗を返します(「…は 40 分間、sqlly.app でライセンスを確認できませんでした。管理者に確認を依頼してください。」)。SQLly クライアントはその一文をステータス行と通知に表示するため、ユーザーは理由が分かります。新しいセッションにも同じ一文が通知されたうえで閉じられ(コード 4503)、起動トークンは次の理由で拒否されます 503 license_not_ok。期間の終了後 15 日間の猶予期間中も、すべての機能は動作しますが、すべてのユーザーにカウントダウンが表示されます。 すべての状態を解説.

サーバーから外に出るもの

チェックイン時に sqlly.app へ送信されますどこにも送信されません
ライセンスキー・ブリッジのインスタンス ID・ブリッジのバージョン・ホスト名・要求されたドメイン・シートを保持しているユーザー ID・開いているセッション数 クエリ · 結果 · データベース名とホスト · 認証情報 · プロファイル · ユーザーが入力するあらゆる内容

オフラインライセンスは何も送信しません。ブラウザーが通信するのは、お使いのアプリとブリッジだけです。