Кракен - веб-сервер для MS SQL Server

Оглавление

I. Общие сведения

Кракен предназначен для работы с базами данных MS SQL по протоколу HTTP и получения данных в формате JSON.

Разработанный на Rust, веб сервер максимально быстро обрабатывает запросы, внося минимальные задержки.

Асинхронная архитектура позволяет параллельно обработывать тысячи запросов.

Общий цикл работы:

ФункцииБесплатная версияКоммерческая
Асинхронный веб сервер с легкой конфигурацией++
Запуск как консольного приложения и как службы Windows++
Basic аутентификация клиентов++
Логирование запросов и процесса обработки++
Настраиваемый пул подключений к MS SQL Server++
Сериализация результатов выборки данных в JSON++
Выборка нескольких таблиц одним запросом-+
Количество строк в таблице результатедо 100Без ограничений
Использование в запросах конструкций 'FOR XML' и 'FOR JSON'-+

Для получения информации о коммерческой версии и приобретении лицензии пишите на адрес kraxe@exponenta.info

II. Установка

Скачать актуальную версию.

Файлы и каталоги Кракена:

У Кракена есть параметры запуска:

> kraxe.exe -install --- установка службы Windows.
> kraxe.exe -start --- запуск службы Windows. Предварительно служба должна быть установлена.
> kraxe.exe -stop --- остановка службы Windows.
> kraxe.exe -delete --- удаление службы Windows.
> kraxe.exe -auto --- используется в параметрах службы Windows для автоматического запуска.
> kraxe.exe -console --- запуск сервера из командной строки как обычного консольного приложения.

Альтернативный вариант - для установки службы использовать стандартную программу Windows sc.exe
В командной строке, запущенной от имени администратора, выполняем:

> sc.exe create Kraxe type= own start= auto error= normal binPath= "C:\...\kraxe\kraxe.exe -auto"
> sc.exe description Kraxe "Kraxe - Web Server for MS SQL"
> sc.exe start Kraxe

Для удаления службы:

> sc.exe stop Kraxe
> sc.exe delete Kraxe

Для подключения к SQL серверу Кракен использует TCP протокол. В настройках MS SQL доступ по этому протоколу должен быть включен. А также в настройках файервола Windows открыт соответствующий порт.

III. Файл настроек kraxe.conf

Настройки хранятся в JSON формате. На верхнем уровне файл содержит 4 раздела:

{
  "global": {...}, // Глобальные настройки Кракена
  "http_server": {...}, // Настройки HTTP протокола
  "sql_server": {...}, // Настройки взаимодействия с MS SQL Server
  "bindings": {...} // Связи URL ресурсов с SQL запросами
  "parameters": {...} // Дефолтные значения переменных для SQL запросов
}

III.a. Глобальные параметры сервера

"global": {
  "cached_queries": Bool,
  "log_level": String
}

cached_queries - булево - в случае, когда значение равно true, все тексты SQL-запросов читаются из файлов в оперативную память один раз при запуске сервера. Это позволяет ускорить обработку запросов. Если значение равно false, текст SQL-запроса читается из файла для каждого нового входящего запроса. Такое поведение несколько замедляет сервер, но позволяет динамически менять запросы, выполнять отладку текстов, не перезапуская весь сервер. По умолчанию, если параметр не указан в настройках, будет установлено значение true.

log_level - строка - уровень логирования. Может принимать следующие значения: "None" - логирование полностью отключено, "Error" - записывать только критические ошибки, "Warning" - записывать ошибки и предупреждения, "Info" - записывать ошибки, предупреждения и информацию об обрабатываемых запросах, "Debug" - максимально подробная информация о работе сервера. По умолчанию, если параметр не указан, будет установлено значение "Info".

III.b. Параметры HTTP-сервера

"http_server": {
  "host": "localhost",
  "port": 80,
  "auth": [
    {
      "scheme": "anonymous",
      "parameters": {
        "user_string": {
          "name": "@USER_STRING",
          "value": {
            "type": "String",
            "default": "User's non-overridable string."
          }
        }
      }
    },
    {
      "scheme": "basic",
      "name": "client",
      "password": "12345678"
    }
  ]
}

host - строка - локальный ip-адрес, на котором сервер будет ожидать входящие запросы. Необязательный параметр. Значение по умолчанию "127.0.0.1".

port - число - номер TCP-порта, на котором сервер ожидает входящие HTTP-запросы. Необязательный параметр. Значение по умолчанию 80.

auth - массив объектов - описание пользователей сервиса. Для того, чтобы сервер мог принимать и обрабатывать запросы, в массиве должна быть задана хотя бы одна запись.

auth.scheme - строка - допустимые значения: "anonymous", "basic". Вариант аутентификации пользователей сервера. Если в разделе "auth" есть хотя бы одна запись где указана схема аутентификации "anonymous", к серверу допустимы запросы без аутентификации. Вариант "basic" - аутентификация в соответствии с RFC 2617. Значение по умолчанию "basic".

auth.name - строка - имя пользователя для basic аутентификации. Не имеет значения для схемы "anonymous".

auth.password - строка - пароль пользователя для basic аутентификации. Не имеет значения для схемы "anonymous".

auth.parameters - объект - набор переменных для SQL-запросов (подробнее о параметрах см. ниже). Необязательный. Допустимо для любой схемы аутентификации.

III.с. Параметры SQL-сервера

"sql_server": {
  "host": "192.168.100.9",
  "port": 1433,
  "database": "kraxe_test",
  "auth_method": "SqlServer",
  "login": "sa",
  "password": "12345678",
  "pool_size": 1,
  "date_offset": 0
}

host - строка - ip адрес SQL сервера. Необязательный. Значение по умолчанию "localhost".

port - число - номер порта SQL сервера. Необязательный параметр. Значение по умолчанию 1433.

database - строка - имя базы данных. Обязательный параметр.

auth_method - строка - вариант аутентификации на SQL сервере. Возможные значения: “SqlServer” - встроенная аутентификация SQL Server (значение по умолчанию), “Windows” - аутентификация пользователя Windows. Не обязательный параметр.

login - строка - имя пользователя базы данных. Необязательный. Значение по умолчанию "sa".

password - строка - пароль пользователя базы данных.

pool_size - число - максимальное количество одновременных подключений, которое может открыть Кракен для обмена данными с SQL сервером. Необязательный. Значение по умолчанию 1.

date_offset - число - количество лет, которое нужно прибавить при записи даты в БД и вычесть при чтении даты из БД. Используется базами данных, созданными из 1С:Предприятие. Необязательный. Значение по умолчанию 0.

III.d. Описание ресурсов HTTP-сервера

Раздел bindings содержит объекты, описывающие возможные HTTP-запросы к серверу и параметры их обработки. Ключ каждой записи - это http-метод и URL ресурса, который могут запросить клиенты. Например, если клиент запрашивает ресурс "GET http://mydomain.com/my_url_1?...", Кракен будет искать в разделе bindings запись с именем ресурса "/my_url_1".

"bindings": {
  "GET /my_url_1": {
    "path": "page1.sql",
    "tables": [
      {
        "id": 0,
        "hide": false,
        "json": false
      },
      {
        "id": 1,
        "hide": false,
        "json": true
      }
    ],
    "parameters": {
      "my_bool": {
        "name": "@MY_BOOL",
        "value": {
          "type": "Bool",
          "default": false
        }
      },
      "my_number": {
        "name": "@MY_NUMBER",
        "value": {
          "type": "I16",
          "default": 157
      }
      }
    }
  }
}

path - строка - имя файла в каталоге /queries, который содержит текст SQL-запроса. Обязательный параметр.

tables - массив - описание таблиц, которые вернет SQL сервер в ответ на запрос. Необязательный параметр.

tables.id - число - индекс таблицы в результах.

tables.hide - булево - признак необходимости скрыть таблицу, не выводить в ответ клиенту. В случае, если значение равно true, таблица будет получена в результате SQL запроса, но в результирующий JSON выведена не будет. Необязательный параметр. Значение по умолчанию равно false.

tables.json - булево - признак того, что в SQL запросе использована конструкция "FOR JSON PATH" и SQL сервер вернет уже готовый JSON, который не требует сериализации. Необязательный параметр. Значение по умолчанию равно false.

parameters - объект - определение значений переменных запроса. Необходимо перечислить в этом разделе все переменные, указанные в SQL-запросе и указать для них значения по умолчанию. Эти значения будут использованы Кракеном, если параметры не переданы пользователем в HTTP-запросе.

III.e. Параметры (переменные) SQL запроса

"parameters": {
 "begin": {
  "name": "@BEGIN",
  "value": {
   "type": "Date",
   "default": "2024-01-01T00:00:00+02:00"
  }
 },
 "end": {
  "name": "@END",
  "value": {
   "type": "Date",
   "default": "2024-12-31T23:59:59Z"
  }
 }
}

Значения переменных в SQL запрос устанавливаются из 4 источников:

Каждый параметр имеет имя, которое используется в HTTP-запросах. Имена чувствительны к регистру.

name - строка - содержит имя переменной, как она будет использоваться в SQL запросе. В текстах запросов имена параметров должны начинаться с символа '@'.

value.type - строка - тип значения. Указатель для Кракена, как интерпретировать значение HTTP-запроса, чтобы передать его в переменную SQL. Допустимые значения:

value.default - строка, число, булево - значение по умолчанию для переменной. Если в пользовательском HTTP-запросе не будет задан соответствующий параметр, тогда в переменную SQL-запроса будет установлено это значение.

Исключительный случай - переменная @DATA. В эту переменную Кракен передаёт всё тело запроса как значение типа String. Имя переменной зарезервировано и не может быть переопределено.

© 2024, exponenta.info   По всем вопросам пишите на адрес kraxe@exponenta.info