Как это работает

Теория работы: мост, движок на каждый сеанс, токены запуска, подписанный грант лицензии, чек-ины, места, правило Origin и где хранятся учётные данные.

SQLly Embedded разделяет SQLly на две половины — ту, которой нужны секреты, и ту, которой не нужны. Интерфейс SQLly работает в браузере пользователя как WebAssembly. Всё, что обращается к базе данных, выполняется на вашем сервере, внутри моста SQLly и запускаемых им движков. Ваше веб-приложение работает рядом с мостом и сообщает ему, кто и с какими подключениями может открыть SQLly. На этой странице разобран каждый узел этой конструкции и то, почему она устроена именно так.

Архитектура

Архитектура SQLly Embedded Браузер пользователя загружает SQLly из вашего веб-приложения и подключается к мосту SQLly по WebSocket. Ваше приложение управляет мостом через его loopback-API управления. Мост запускает по одному движку SQLly на сеанс, который подключается к вашим базам данных. Мост проверяет лицензию на sqlly.app каждые 20 минут. ваши пользователи ваш сервер sqlly.app Браузер SQLly (WebAssembly) здесь нет паролей Ваше веб-приложение вход · кто получает какой профиль · обслуживает web/ встроенный sqlly-bridge :8444 /proxy (браузеры, wss) :8445 /manage (ваше приложение, loopback) профили · токены · места · лицензия sqlly-cli движок один на сессию Ваши базы данных любой движок SQLly sqlly.app подписывает лицензию выдаётся при каждом check-in https wss bearer-токен stdio чек-ин каждые 20 минут
Синие пути несут работу ваших пользователей; пунктирный путь — это регистрация лицензии, которая не передаёт ни запросов, ни результатов, ни учётных данных. При офлайн-лицензиях его нет вовсе.

Зачем такое разделение

  • Секреты остаются на сервере. Браузер не может скрыть пароль базы данных от собственного пользователя. Поэтому браузер его никогда не получает. Он получает список подключений, отправляет фреймы запросов, а мост выполняет их с учетными данными, которые есть только у сервера.
  • Ваше приложение само отвечает за идентификацию. У моста нет пользовательских учётных записей. Ваше приложение и так знает, кто вошёл. Оно говорит мосту «открыть SQLly для этого пользователя с этого профилем" путем создания токена запуска, и мост доверяет этому токену.
  • Один движок на сессию. Каждая вкладка браузера получает свой собственный sqlly-cli процесс, поэтому сеансы никогда не используют общее состояние соединений, транзакции или временные таблицы, и сбой влияет на одну вкладку, а не на мост.

Внутри моста

sqlly-bridge embedded — это один процесс с тремя задачами:

ЗаданиеПрослушиваетВзаимодействует с
Браузерный прокси: принимает WebSocket для каждой вкладки SQLly, проверяет её Origin и токен запуска, запускает движок с профилем из токена и ретранслирует кадры в обоих направлениях.--bind, по умолчанию 0.0.0.0:8444, путь /proxyБраузеры (поставьте TLS впереди)
API управления: профили, токены запуска, рабочие места, проверки соединения, статус лицензии и журнал аудита запросов. Справочник.--manage-bind, по умолчанию 127.0.0.1:8445Только серверная часть вашего приложения, с токеном Bearer
Монитор лицензий: связывается с sqlly.app при запуске и каждые 20 минут (когда есть сеть) или перечитывает файл лицензии каждую минуту (офлайн), а также переводит мост между состояниями лицензии.Ничегоsqlly.app через HTTPS (только при подключении)

Его директория состояния (--state-dir, создаваемая с правами только для владельца на Linux и macOS) хранит каждый профиль в виде profiles/<id>.json, последнюю действующую лицензию (license.json), ключ связанной установки (license-key, режим 0600), файлы учётных данных сессий, которые он передаёт своим движкам, и журнал аудита запросов (queries.jsonl: каждый запрос, выполненный в сессии, с его SQL-текстом). Сделайте резервную копию и храните его так же конфиденциально, как файл с паролями, потому что он таковым и является. Куда его поместить и что нужно Windows.

Профили: что видит пользователь

A профиль — это именованный документ учётных данных SQLly: тот же формат JSON, который настольное приложение SQLly импортирует и экспортирует. В нём перечислены подключения (сервер, база данных, движок, аутентификация, TLS, правила безопасности) и метки клиента, проекта и окружения, которые окрашивают и группируют их. Ваше приложение хранит профили в PUT /manage/profiles/{id}. Мост проверяет весь документ заранее и сообщает обо всех проблемах одновременно, поэтому опечатка вроде "pasword" приводит к явной ошибке, а не игнорируется.

Пользователи не привязаны к профилям в мосте — профиль задаётся при каждом запуске. Дайте аналитикам профиль только для чтения (метка с only_allow_select, или block_all_but_select в подключении: движок не пропускает ничего, кроме SELECT, прежде чем запрос попадёт в базу данных), а сотрудникам поддержки — другой, или создайте по одному профилю на клиента в многопользовательском приложении. Файловые движки (SQLite, DuckDB) отклоняются, если мост не запущен с --allow-file-engines, потому что они дают пользователям доступ к файлам на хосте моста. Чтобы выдать кому-то меньше подключений, создайте другой профиль. Когда сессия открывается, браузер получает из профиля в каталоге: имена соединений, движки, базы данных и метки, при этом все секреты удалены. Редактирование профиля применяется к следующему запуску. Уже открытые сессии сохраняют каталог, с которым они начали.

Жизненный цикл сессии

Запуск SQLly для пользователя Браузер запрашивает SQLly у вашего приложения. Приложение выпускает токен запуска через мост и возвращает страницу SQLly с прокси-URL и токеном. Браузер открывает с мостом WebSocket-соединение, передав токен. Мост проверяет Origin, токен, лицензию и количество мест, запускает движок с учётными данными профиля и отправляет браузеру приветствие с каталогом подключений и состоянием лицензии. Затем кадры запросов идут от браузера через мост и движок в базу данных и обратно. Браузер Ваше приложение Мост Движок База данных 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 с вашим идентификатором пользователя и профилем, который он должен получить, а также (опционально) что открыть: вкладки запросов со скриптом, подключением, значениями параметров и курсором (контекст запуска).
  3. Мост проверяет лицензию и число мест, снимает профиль и возвращает случайный токен, срок его действия и публичный URL прокси.
  4. Ваш сервер возвращает страницу SQLly (web/index.html) с двумя глобальными переменными, заданными заранее 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. Браузер получает приветствие с каталогом подключений без секретов и текущим состоянием лицензии. Первая сессия токена, выпущенного с контекстом запуска, также получает вкладки для открытия; SQLly загружает их, но ничего не выполняет.
  8. С этого момента запросы SQLly (подключение, выполнение, отмена, получение метаданных для IntelliSense, пролистывание результатов) передаются в виде бинарных фреймов. Мост пересылает их движку, фиксирует каждый запрос и изменение строки в своём журнал аудита, и отказывает в них с сообщением, если лицензия становится недействительной.

Места и сессии

A место — это отдельный id пользователя, у которого открыт сеанс или не истёк токен запуска. Места считаются по одновременному использованию, а не поимённо: как только у пользователя закрывается последняя вкладка и истекает последний токен, место освобождается, и его может занять кто-то другой. Bridge считает места по всем мостам лицензии, потому что sqlly.app при каждой регистрации сообщает пользователей с других экземпляров.

  • Создание токена для пользователя, который уже занимает место, всегда удается. Создание токена для нового пользователя, когда все места заняты, завершается неудачей с 409 seat_limit, поэтому ваше приложение может показать понятное сообщение.
  • Каждое место допускает sessionsPerSeat открытых вкладок: четыре на платных тарифах, одна на пробном. Лишняя вкладка получает отказ и закрывается (код 4429). Мост пингует каждую вкладку и сбрасывает ту, что молчит 90 секунд, — так вкладка, потерянная из-за уснувшего ноутбука, сама освобождает свою сессию; когда у пользователя закрывается последняя вкладка, его токены запуска истекают в течение двух минут.
  • DELETE /manage/seats/{user} отзывает токены пользователя и закрывает его сессии. Вызывайте это, когда кто-то выходит из вашего приложения или теряет доступ.
  • ID пользователя — это то, что вы передадите. Используйте стабильный непрозрачный идентификатор (ключ базы данных или хеш), если не хотите отправлять адреса электронной почты: идентификаторы, занимающие места, передаются на sqlly.app, чтобы места можно было считать по всем мостам.

Кто может подключаться: правило Origin

Каждая лицензия привязана к одному домену. Мост принимает WebSocket браузера только тогда, когда его Origin заголовок соответствует этому домену или любому его поддомену (любая глубина, схема или порт), или localhost / 127.0.0.1 / [::1] в то время как --allow-localhost-origins включён (по умолчанию, для разработки). Лицензия без привязанного домена допускает только localhost. Привяжите домен на вашей странице Embeddedили запустите мост один раз с --domain.

API управления вообще не отправляет заголовков CORS. Это обмен между серверами: браузер с другого источника не может его вызвать, да и привязывать его в любом случае нужно к loopback.

Как применяется лицензия

Мост доверяет одной вещи: лицензионный грант, компактный JWS, который sqlly.app подписывает с помощью ES384 (ECDSA P-384). Ключ проверки встроен в мост. Каждое разрешение (места, сеансы на место, экземпляры моста, домен, конец периода, льготные дни, функции) читается из подписанных утверждений (claims) гранта. Неподписанный JSON вокруг него предназначен только для отображения.

Подключенные лицензии

  • При запуске и каждые 20 минут мост отправляет POST /api/embedded/checkin со своим лицензионным ключом, идентификатором экземпляра, новым 32-байтовым нонсом, версией и именем хоста, доменом, для которого он был запущен, и идентификаторами пользователей, которые в данный момент занимают места.
  • Грант в ответе должен проходить проверку по вкомпилированному ключу, возвращать тот же nonce, называть этот экземпляр и ту же лицензию и быть выданным в пределах 5 минут по часам моста. Повторенный или подделанный ответ эти проверки не проходит и считается неудачной проверкой связи. Следите, чтобы часы на хосте были точны (NTP).
  • Грант действует 40 минут. Если до sqlly.app не удается добраться, мост продолжает обслуживать на основе последнего действительного гранта до его окончания, а затем прекращает работу устаревший и отказывается работать до следующей успешной проверки связи — без перезапуска. Мост, перезапущенный во время простоя, стартует с кэшированным грантом, только пока тот не истёк.
  • Каждая подключённая лицензия допускает несколько экземпляры одновременно (по умолчанию один). Второй мост с тем же ключом регистрируется, но не допускается, пока первый продолжает отзываться. Мост, завершившийся штатно, освобождает свой слот сразу; аварийно упавший — только через 40 минут.

Офлайн-лицензии

Офлайн-лицензия — это файл ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }), который вы скачиваете с sqlly.app после настройки его домена. Внутренняя лицензия действует долго: срок истекает в конце периода плюс льготные дни. Мост проверяет её локально, никогда не связывается с сервером SQLly и перечитывает файл каждую минуту, поэтому продление — это замена файла. У офлайн-лицензий нет ограничения на количество экземпляров.

Привязанные установки

Мост, запущенный без ключа и без файла, является нелицензированного: API управления работает (можно настроить и проверить профили), но запуски отклоняются. Затем ваше админ-приложение может привязать мост, чтобы никому не пришлось копировать ключ: оно запрашивает у sqlly.app код привязки, владелец лицензии одобряет его в своём браузере, а приложение получает ключ, выпущенный только для этой установки, и передаёт его мосту с PUT /manage/license. Мост проверяет его, сохраняет и продолжает использовать при перезапусках. Каждая связанная установка имеет свой собственный ключ, поэтому владелец может отозвать один, не затрагивая другие. Как его собрать.

Когда лицензия недействительна

В каждом состоянии, кроме ok и grace, мост держит открытые сокеты подключёнными, но отвечает на каждый фрейм запроса ошибкой с понятной фразой («…не удалось подтвердить лицензию на sqlly.app в течение 40 минут; попросите администратора разобраться.»). Клиент SQLly показывает эту фразу в строке состояния и в виде уведомления, чтобы пользователи знали причину. Новым сессиям сообщается та же фраза, и они закрываются (код 4503), а токены запуска отклоняются с 503 license_not_ok. В течение 15-дневного льготного периода после окончания срока всё работает, но каждый пользователь видит обратный отсчёт. Каждое состояние — с объяснением.

Что покидает ваш сервер

Отправляется на sqlly.app при регистрацииНикуда не отправляется
Лицензионный ключ · идентификатор экземпляра моста · версия моста · имя хоста · запрашиваемый домен · идентификаторы пользователей, занимающих места · количество открытых сессий Запросы · результаты · имена баз данных и хосты · учетные данные · профили · все, что печатают ваши пользователи

Офлайн-лицензии ничего не отправляют. Браузер общается только с вашим приложением и вашим мостом.