Revision as of 12:01, 7 June 2024

Поддержка среды разработки Theia IDE

Примечание: данная функциональность входит в набор расширений XSvacer.

Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.

По умолчанию запускается IDE, собранная на основе Theia IDE.

Активация функциональности

Для активации функциональности необходимо указать флаг --xsvacer.features webide при запуске svacer'а.

Примечание: при запуске функциональности webide также будет запущена функциональность docker.

Активации функциональности:

становится доступным REST API управления IDE для просмотра снимков проектов;
в пользовательском интерфейсе появляется кнопка "Открыть в IDE";
устанавливается подключение к хосту docker'а, на котором будут запускаться контейнеры с экземплярами IDE.

Принцип работы

Функциональность запуска IDE для просмотра исходного кода снимков становится доступной пользователю, если соблюдаются условия:

Функциональность активна: при запуске svacer'а указан флаг --xsvacer.features webide;
В конфигурации функциональности xsvacer/webide/theia (Help:XSvacer:Webide#Конфигурация) есть хотя бы одна активная (disabled: false) конфигурация IDE;
У пользователя svacer имеются разрешения "Просмотр маркеров" ("Read markers") и "Экспорт разметки" ("Export markup") на проект, в котором находится снимок, для которого нужно запустить IDE.

В противном случае в пользовательском интерфейсе будет отсутствовать кнопка "Открыть в IDE" ("Open in IDE")

Запуск IDE

Запуск производится путём вызова http-метода POST /api/snapshots/{snapshot_id}/ide с телом запроса {"ideId": "идентификатор IDE"}.

Последовательность действий, выполняемых при запуске IDE:

Производится проверка: была ли уже запущена указанная IDE для указанного снимка:
- Если запущена: производится проверка доступна ли IDE: отвечает на запросы;
  - Если IDE доступна: действие не требуется. Процесс запуска завершается;
  - Если IDE не доступна: продолжается процесс запуска. IDE будет перезапущена;
Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot;
Исходный код снимка скачивается в "корневую папку снимка";
Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate;
Производится настройка и запуск docker-контейнера, в соответствии с настройками xsvacer/webide/theia/{идентификатор конфигурации}/docker:
1. Проверяется наличие на docker-хосте образа IDE, указанного в xsvacer/webide/theia/{идентификатор конфигурации}/docker/image:
  - Если docker-образ отсутствует - он будет загружен на хост;
2. Проверяется наличие на docker-хосте контейнера с IDE для снимка:
  - Если docker-контейнер не существует, то он будет создан и запущен;
  - Если docker-контейнер существует и находится:
    - в статусе running - процесс запуска IDE продолжается;
    - в статусе created,exited или paused - контейнер будет запущен;
    - в других статусах - вернётся соответствующая ошибка и процесс запуска IDE прервётся;
После успешного запуска docker-контейнера осуществляется ожидание окончания запуска процесса IDE в контейнере, в соответствии с настройками xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck:
- Если за отведённое время ответ от IDE получен - процесс запуска завершается.
- Если ответ не получен - вернётся ошибка ide not ready;

Внимание! При возникновении ошибки на одном из этапов запуска IDE, артефакты созданные на предыдущих этапах останутся в системе. В дальнейшем они могут быть использованы при повторном запуске IDE, если причина возникновения ошибки была устранена.

Внимание! Причиной возникновения ошибки ide not ready может стать высокая загруженность или недостаточная производительность docker-хоста, на котором запускается контейнер с IDE. В связи с этим, процесс IDE внутри контейнера может запускаться дольше, чем указано в настойках xsvacer/webide/theia/{идентификатор конфигурации}/healthcheck.
В случае возникновения ошибки ide not ready рекомендуется попытаться повторно запустить IDE через короткий промежуток времени.
Ещё одной причиной возникновения данной ошибки может стать сетевая недоступность docker-контейнера, при подключении к удалённому docker-хосту. В таком случае рекомендуется:
1. проверить сетевую доступность docker-хоста;
2. проверить настройки биндинга docker-контейнера c IDE - xsvacer/webide/theia/{идентификатор конфигурации}/docker/container/hostconfig/portbindings. Контейнер должен быть подключён к доступному сетевому интерфейсу.
3. проверить настройки фаервола на docker-хосте;

Использование IDE: проксирование запросов

После успешного запуска docker-контейнера IDE станут доступны ресурсы с "префиксом" /xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/

Все запросы направленные к ресурсам /xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/* будут проксироваться в соответствующий контейнер IDE.

Например, если docker-контейнер c IDE theia__default для снимка xxx запущен и "слушает" порт 35353 на хосте docker-host, то будет происходить проксирование:

GET http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/ ⇒ GET http://docker-host:35353/

POST http://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?... ⇒ GET http://docker-host:35353/socket.io/?...

GET ws://svacer-host/xsvacer/webide/snapshots/xxx/ide/theia__default/socket.io/?... ⇒ GET ws://docker-host:35353/socket.io/?...

Примечание: для запуска IDE в окне браузера нужно указать адрес http[s]://svacer-host/xvacer/webide/snapshots/{snapshot_id}/{ide_id}/. Завершающий слеш обязателен!

Перезапуск IDE

В процессе работы svacer следит за состоянием запущенных IDE. При попытке повторного запуска IDE проверяется её доступность: если IDE отвечает на запросы, то повторный запуск не производится и обработка запроса завершается.

Также работоспособность IDE контролируется при использовании IDE в момент проксирования запросов в docker-контейнер: если IDE доступна, то запрос проксируется.

Если IDE перестанет отвечать на запросы, то будет произведена попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при первоначальном запуске IDE.

Зачастую потеря связи обусловлена остановкой docker-контейнера с IDE. В таком случае docker-контейнер будет перезапущен.

Если же недоступность IDE обусловлена другими причинами, то запрос на запуск/проксирование продолжит возвращать ошибку, до устранения причин неработоспособности.

Остановка IDE

Запуск производится путём вызова http-метода DELETE /api/snapshots/{snapshot_id}/ide с телом запроса {"ideId": "идентификатор IDE"}.

В ходе обработки запроса останавливается docker-контейнер IDE.

Внимание! По умолчанию установлен параметр конфигурации xsvacer/webide/theia/default/docker/container/hostconfig/autoremove: true. Это означает, что при после остановки docker-контейнер будет автоматически удалён.
Чтобы изменить это поведение, настройка xsvacer/webide/theia/default/{id конфигурации}/container/hostconfig/autoremove должна быть установлена в false на момент запуска docker-контейнера IDE. Это можно сделать, например, установив значение переменной окружения XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_CONTAINER_HOSTCONFIG_AUTOREMOVE=false.
!!!Сейчас установка autoremove: false вызывает ошибку запуска svacer!!! Не используйте данную настройку до исправления

Примечание! При корректной остановке (например SIGTERM) svacer автоматически остановит все запущенные docker-контейнеры IDE

Подключение к IDE после некорректного завершениея svacer

При запуске svacer осуществляет поиск запущенных docker-контейнеров IDE на доступных docker-хостах.

При восстановлении связи с запущенными docker-контейнерами IDE и последующей корректной остановке svacer'а, все docker-контейнеры IDE будут остановлены.

REST API для работы с IDE

Внимание! На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!

После активации функциональности становятся доступны http-ресурсы для управления IDE снимками:

REST API управления IDE
Ресурс	Описание
GET /xsvacer/webide/api/ide	Получение списка доступных для запуска IDE. Ответ: [ { "id": "string", "name": "string", "order": 0 } ] `id` - идентификатор IDE `name` - название IDE `order` - порядковый номер IDE в списке
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{ide_id}	Запрос описания экземпляра IDE, запущенного для снимка. Параметры: `snapshot_id` - идентификатор снимка `ide_id` - идентификатор IDE Ответ: { "id": { "ide_id": { "ide_type": "string" "config_id": "string", }, "snapshot_id": "string" }, "properties": { "url": "string" }, "start_args": { "snapshot_id": "string", "user": "string", "user_id": "string" } }
POST /xsvacer/webide/api/snapshots/{snapshot_id}/ide	Запуск IDE для просмотра исходных кодов снимка Параметры: `snapshot_id` - идентификатор снимка Запрос: { "ideId": "string" } `ideId` - идентификатор IDE Ответ: { "ideId": "string" } `ideId` - идентификатор IDE
PUT /api/snapshots/{snapshot_id}/ide	Команда управления экземпляром IDE снимка Доступные действия: `update_markup` - обновление предупреждений и разметки (sarif-файла) Параметры: `snapshot_id` - идентификатор снимка Запрос: { "action": "string", "ideId": "string" } `action` - действие `ideId` - идентификатор IDE Ответ: пустой
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide	Остановка экземпляра IDE снимка Параметры: `snapshot_id` - идентификатор снимка Запрос: { "ideId": "string" } `ideId` - идентификатор IDE Ответ: пустой
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/*	Прокси для запросов экземпляра IDE снимка

Формат идентификатора IDE

{тип ide}__{идентификатор конфигурации}

Например для default-конфигурации Theia IDE: theia__default

Конфигурация

Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла svacer.cfg.

Раздел конфигурации для управления функциональностью - xsvacer/webide.

Раздел содержит перечисление настроек доступных конфигураций для запуска экземпляров Theia IDE xsvacer/webide/theia. При наличии нескольких активных конфигураций запуска Theia IDE пользователь сможет выбрать какую из них использовать при запуске IDE с исходными файлами снимка.

xsvacer:
  webide:
    theia:
      config1:
        ...
      config2:
        ...

Внимание! Запуск IDE основывается на запуске docker-контейнеров, содержащих соответствующие сборки IDE. Поэтому помимо настройки функциональности в разделе xsvacer/webide необходимо также настроить доступ к docker-хосту в разделе xsvacer/docker (Help:XSvacer:Docker). В противном случае функциональность webide не сможет работать корректно.

Примечание: в случае отсутствия файла svacer.cfg или отсутствии раздела xsvacer/webide, будет использоваться конфигурация по умолчанию

Конфигурация запуска Theia IDE

Внимание! На этапе внедрения расширений XSvacer конфигурация функциональностей может меняться. Следите за анонсами!

Конфигурации запуска Theia IDE добавляются в виде полей в разделе xsvacer/webide. Название поля является идентификатором конфигурации запуска. Например идентификатор по номеру используемой версии IDE:

xsvacer:
  webide:
    theia:
      1-46-0:
        name: Theia blueprint web IDE (v1.46.0)
        ...

Базовые параметры конфигурации запуска


Название	Тип данных	Описание	Значение в конфигурации по умолчанию
disabled	bool	Конфигурация запуска неактивна. Неактивная конфигурация не доступна для запуска экземпляра IDE	true (переопределяется в конфигурации `default`)
order	int	Порядковый номер в списке выбора конфигурации запуска	0
name	string	Название конфигурации	Theia blueprint web IDE (v1.46.0)
sourcesroot	string	Путь к папке содержащей исходные коды снимков на машине со svacer'ом	${USER_CACHE_DIR}/svacer-snapshot-sources
dockerhostsourcesroot	string	Путь к папке содержащей исходные коды снимков на хосте docker'а. Нужен при использовании удалённого docker-хоста, т.к. в таком случае папка с исходными кодами скорее всего будет доступна по адресу, отличающемуся от `sourcesroot`
dockerhostpathseparator	string	Разделитель пути на хосте docker'а. По умолчанию `"/"`.
sariffiletemplate	golang template string	Шаблон названия sarif-файла с предупреждениями анализатора. В шаблон передаётся структура sarifFileContext	"{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"

Параметры менеджера запуска IDE

Конфигурация менеджера запуска IDE. На данный момент доступен только "стандартный" менеджер (type: default)


Название	Тип данных	Описание	Значение в конфигурации по умолчанию
manager	map	Конфигурация менеджера запуска IDE
manager/type	enum: default	Тип менеджера запуска IDE	default

Параметры запуска docker-контейнеров с IDE

Данные параметры используются для настройки запуска docker-контейнеров с IDE


Название	Тип данных	Описание	Значение в конфигурации по умолчанию
docker/	map	Настройки создания docker-контейнера с IDE
docker/hostid	string	Идентификатор хоста docker'а, описанного в `xsvacer/docker/hosts`. Запуск docker-контейнера с IDE будет выполнен на этом хосте	default
docker/containernametemplate	golang template string	Шаблон для формирования названия контейнера IDE для выбранного снимка. В шаблон передаётся структура TheiaDockerContainerStartContext	"theia-1-46-{{.StartArgs.SnapshotID}}"
docker/containerconfiglabels	[]map	Список "меток" docker-контейнера. Дополняет список меток в `docker/container/config/labels`	- "com.docker.compose.project": svacer
docker/image/	map	Параметры docker-образа из которого будет запущен контейнер
docker/image/name	string	Название образа	theia-blueprint
docker/image/tag	string	Тег образа	1.46.0.sarif.clang
docker/image/sourcetype	enum: repository/file	Тип источника для загрузки образа в docker-хост. `repository` - будет вызван `docker pull` образа `{image/name}:{image/tag}` `file` - будет вызван `docker load` с url'ом `image/sourcefileurl`	file
docker/image/sourcefileurl	url	Url откуда будет загружен docker-образ если `image/sourcetype == "file"` Url может содержать: - путь к локальному файлу: схема `file://` - http/https-адрес: схема `http://` или `https://`	https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar
docker/container/	map	Свойства docker-контейнера
docker/container/config	map	Конфигурация контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/config.go#L70
docker/container/config/env	[]string	Список переменных среды, которые будут установлены в контейнере	- THEIA_WEBVIEW_EXTERNAL_ENDPOINT={{hostname}}
docker/container/hostconfig/	map	Параметры хостинга контейнера. Соответствует структуре https://github.com/moby/moby/blob/v24.0.7/api/types/container/hostconfig.go#L379
docker/container/hostconfig/autoremove	bool		true
docker/container/hostconfig/portbindings	map		"3000/tcp": - hostport: 0
docker/container/networkconfig/	map	Сетевые настройки контейнера. Соответствуют структуре https://github.com/moby/moby/blob/v24.0.7/api/types/network/network.go#L104

Параметры проверки доступности healthcheck

Данные параметры используются для проверки доступности IDE после запуска docker-контейнера


Название	Тип данных	Описание	Значение в конфигурации по умолчанию
healthcheck	map	Параметры проверки доступности IDE
healthcheck/starttoreadyretries	int	Количества попыток проверки до ошибки доступности	10
healthcheck/starttoreadyperiod	golang duration string	Интервал проверки	200ms

Структуры передаваемые в поля с golang-шаблонами строк

sarifFileContext {
    Time    time.Time
	Context: {
        ProjectID  *string
        BranchID   *string
        SnapshotID *string
        MarkerID   *string

        ProjectName  *string
        BranchName   *string
        SnapshotName *string
        MarkerName   *string
        CreatedBy    null.String
        CreatedByID  null.String
        CreateTs     null.Time
    }
}

TheiaDockerContainerStartContext {
	IdeID: {
        IdeType  string
        ConfigID string
    },
	StartArgs: {
        SnapshotID string
        UserID     string
        User       string
    },
	Context: {
        ProjectID  *string
        BranchID   *string
        SnapshotID *string
        MarkerID   *string

        ProjectName  *string
        BranchName   *string
        SnapshotName *string
        MarkerName   *string
        CreatedBy    null.String
        CreatedByID  null.String
        CreateTs     null.Time
    }
}

Конфигурация по умолчанию используемая в svacer

Данная настройка применяется по умолчанию для запуска Theia IDE, если в конфигурационном файле svacer.cfg отсутствует раздел xsvacer/webide:

xsvacer:
  docker:
    hosts:
      default: # конфигурация docker-хоста
        type: external
      ...

  webide:
    theia:
      1-46-0: &1-46-0
        disabled: true
        order: 0
        name: Theia blueprint web IDE (v1.46.0)
        sourcesroot: ${USER_CACHE_DIR}/svacer-snapshot-sources
        sariffiletemplate: "{{.Context.ProjectName}}.{{.Context.BranchName}}.sarif"
        manager:
          type: default
        docker:
          hostid: default # идентификатор используемого docker-хоста
          containernametemplate: "theia-1-46-{{.StartArgs.SnapshotID}}"
          image:
            name: theia-blueprint
            tag: 1.46.0.sarif.clang
            sourcetype: file
            sourcefileurl: https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar
          containerconfiglabels:
            - "com.docker.compose.project": svacer
          container:
            config:
              env:
                - THEIA_WEBVIEW_EXTERNAL_ENDPOINT={{hostname}}
            hostconfig:
              autoremove: true
              portbindings:
                "3000/tcp":
                  - hostport: 0
            networkconfig:
        healthcheck:
          starttoreadyretries: 10
          starttoreadyperiod: 200ms
      default:
        <<: *1-46-0
        order: 0
        disabled: false

Внимание! По умолчанию используется docker-хост с идентификатором default. Согласно настройке этого хоста, по умолчанию предполагается взаимодействие с докером через unix-сокет unix:///var/run/docker.sock. Соответственно пользователь, под которым запускается svacer должен иметь доступ к этому сокету (https://docs.docker.com/engine/install/linux-postinstall/).

Внимание! При наличии раздела xsvacer/webide в конфигурационном файле svacer.cfg, будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.

Изменение конфигурационных параметров с помощью переменных окружения

Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения XSVACER_WEBIDE_THEIA_{id конфигурации ide}[_параметр]={значение параметра}

Например, для активации rootless-хоста xsvacer/hosts/local и переключения запуска IDE с идентификатором default на этот хост, можно указать такие значения переменных окружения при запуске svacer'а:

XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false
XSVACER_WEBIDE_THEIA_DEFAULT_DOCKER_HOSTID=local

Очистка системы: удаление артефактов функциональности

В процессе использования функциональности IDE создаются следующие артефакты:

Исходные файлы снимков скачиваются в "корневые папки" заданные в параметре xsvacer/webide/theia/{id конфигурации}/sourcesroot
Артефакты docker:
- образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов, указанных в xsvacer/webide/theia/{id конфигурации}/docker/hostid
- названия docker-образов будут соответствовать параметрам в xsvacer/webide/theia/{id конфигурации}/docker/image
- названия docker-контейнеров будут соответствовать параметру xsvacer/webide/theia/{id конфигурации}/docker/containernametemplate
- наборы меток doker-контейнеров будут содержать:
  метки перечисленные в xsvacer/webide/theia/{id конфигурации}/docker/containerconfiglabels
  
  метки перечисленные в xsvacer/webide/theia/{id конфигурации}/docker/container/config/labels
  
  метки с названиями svacer.service.id, svacer.service.type, svacer.theia.start_args
При использовании rootless-хоста docker'а будут созданы папки, согласно Help:XSvacer:Docker#Специфичные настройки для rootless-хоста

Информация о docker-образе Theia IDE

Docker-образ, используемый по умолчанию, построен на базе Eclipse Theia IDE версии [[1]]

При этом была изменена компоновка расширений theia (результат выполнения git diff):

diff --git a/browser.Dockerfile b/browser.Dockerfile
index efe591e..a4ebb6a 100644
--- a/browser.Dockerfile
+++ b/browser.Dockerfile
@@ -42,7 +42,7 @@ RUN chmod g+rw /home && \
 RUN apt-get update && apt-get install -y wget apt-transport-https && \
     wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | tee /usr/share/keyrings/adoptium.asc && \
     echo "deb [signed-by=/usr/share/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | tee /etc/apt/sources.list.d/adoptium.list && \
-    apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 temurin-17-jdk maven && \
+    apt-get update && apt-get install -y git openssh-client openssh-server bash libsecret-1-0 clangd && \
     apt-get purge -y wget && \
     apt-get clean

diff --git a/package.json b/package.json
index 9044595..9d0dcc8 100644
--- a/package.json
+++ b/package.json
@@ -54,10 +54,8 @@
   "theiaPluginsDir": "plugins",
   "theiaPlugins": {
     "eclipse-theia.builtin-extension-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.83.1/file/eclipse-theia.builtin-extension-pack-1.83.1.vsix",
-    "ms-vscode.js-debug": "https://open-vsx.org/api/ms-vscode/js-debug/1.83.1/file/ms-vscode.js-debug-1.83.1.vsix",
-    "ms-vscode.js-debug-companion": "https://open-vsx.org/api/ms-vscode/js-debug-companion/1.1.2/file/ms-vscode.js-debug-companion-1.1.2.vsix",
-    "vscjava.vscode-java-pack": "https://open-vsx.org/api/vscjava/vscode-java-pack/0.25.11/file/vscjava.vscode-java-pack-0.25.11.vsix",
-    "vscjava.vscode-java-dependency": "https://open-vsx.org/api/vscjava/vscode-java-dependency/0.21.2/file/vscjava.vscode-java-dependency-0.21.2.vsix"
+    "llvm-vs-code-extensions.vscode-clangd": "https://open-vsx.org/api/llvm-vs-code-extensions/vscode-clangd/0.1.26/file/llvm-vs-code-extensions.vscode-clangd-0.1.26.vsix",
+    "ms-sarifvscode.sarif-viewer": "https://open-vsx.org/api/MS-SarifVSCode/sarif-viewer/3.4.2/file/MS-SarifVSCode.sarif-viewer-3.4.2.vsix"
   },
   "theiaPluginsExcludeIds": [
     "ms-vscode.js-debug-companion",

Команда построения docker-образа:

docker build -t theia-blueprint:1.46.0.sarif.clang -f browser.Dockerfile .

Команда экспорта docker-образа:

docker image save theia-blueprint:1.46.0 > /path/to/tar/theia-blueprint.1.46.0.docker.command.tar

Известные проблемы

Список известных проблем и их решение

При открытии sarif-файла в IDE открывается пустая панель "SARIF Results"

Для просмотра sarif-файла содержащего предупреждения анализатора и разметку используется плагин SARIF Viewer. При просмотре sarif-файла открывается webview плагина, со списком предупреждений анализатора.

В Theia IDE для открытия webview применяется Service Worker API. В целях обеспечения безопасности применение Service Worker API [2], чтобы доступ к web-приложению осуществлялся по HTTPS, либо приложение размещалось на localhost.

Поэтому для решения данной проблемы svacer должен открываться по https, либо быть доступен по адресу http://localhost:...

Help:XSvacer:Webide: Difference between revisions