Help:XSvacer:Webide
Поддержка среды разработки Theia IDE
Примечание: данная функциональность входит в набор расширений XSvacer.
Данная функциональность даёт возможность просматривать исходный код снимка с предупреждениями анализатора во внешней IDE.
По умолчанию запускается IDE собранная на основе Theia IDE (https://theia-ide.org/).
Активация функциональности
Для активации функциональности необходимо указать флаг --xsvacer.features webide
при запуске svacer'а.
Примечание: при запуске функциональностиwebide
также будет запущена функциональностьdocker
.
Активации функциональности:
- становится доступным REST API управления IDE для просмотра снимков проектов;
- в пользовательском интерфейсе появляется кнопка "Открыть в IDE";
- устанавливается подключение к хосту docker'а, на котором будут запускаться контейнеры с экземплярами IDE.
REST API для работы с IDE
Внимание! На этапе внедрения расширений XSvacer REST API может меняться. Следите за анонсами!
После активации функциональности становятся доступны http-ресурсы для управления IDE снимками:
Ресурс | Описание |
---|---|
GET /xsvacer/webide/api/ide |
Получение списка доступных для запуска IDE.
Ответ: [ { "id": "string", "name": "string", "order": 0 } ]
|
GET /xsvacer/webide/api/snapshots/{snapshot_id}/ide/{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 для просмотра исходных кодов снимка
Параметры:
Запрос: { "ideId": "string" }
Ответ: { "ideId": "string" }
|
PUT /api/snapshots/{snapshot_id}/ide |
Команда управления экземпляром IDE снимка
Доступные действия:
Параметры:
Запрос: { "action": "string", "ideId": "string" }
Ответ: пустой |
DELETE /xsvacer/webide/api/snapshots/{snapshot_id}/ide |
Остановка экземпляра IDE снимка
Параметры:
Запрос: { "ideId": "string" }
Ответ: пустой |
/xsvacer/webide/snapshots/{snapshot_id}/ide/{ide_id}/* |
Прокси для запросов экземпляра IDE снимка |
Формат идентификатора IDE
{тип ide}__{идентификатор конфигурации}
Например для default
-конфигурации Theia IDE: theia__default
Принцип работы
Функциональность запуска 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 будет перезапущена;
- Если запущена: производится проверка: доступна ли IDE: отвечает на запросы;
- Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE
xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot
; - Исходный код снимка скачивается в "корневую папку снимка";
- Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE
xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate
; - Производится настройка и запуск docker-контейнера, в соответствии с настройками
xsvacer/webide/theia/{идентификатор конфигурации}/docker
;- Проверяется наличие на docker-хосте образа IDE, указанного в
xsvacer/webide/theia/{идентификатор конфигурации}/docker/image
;- Если docker-образ отсутствует - он будет загружен на хост;
- Проверяется наличие на docker-хосте контейнера с IDE для снимка;
- Если docker-контейнер не существует, то он будет создан и запущен;
- Если docker-контейнер существует и находится
- в статусе
running
- процесс запуска IDE продолжается; - в статусе
created
,exited
илиpaused
- контейнер будет запущен; - в других статусах - вернётся соответствующая ошибка и процесс запуска IDE прервётся;
- в статусе
- Проверяется наличие на docker-хосте образа 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 будут остановлены.
Конфигурация
Управление настройками функциональности осуществляется с помощью конфигурационного 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-хост.
|
file |
docker/image/sourcefileurl | url | Url откуда будет загружен docker-образ если image/sourcetype == "file"
Url может содержать:
- путь к локальному файлу: схема |
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
- метки перечисленные в
- образы и контейнеры создаются на хостах, указанных в конфигурации docker-хостов, указанных в
- При использовании rootless-хоста docker'а будут созданы папки, согласно Help:XSvacer:Docker#Специфичные настройки для rootless-хоста
Рекомендации
Предварительная загрузка docker-образа с IDE
По умолчанию параметр xsvacer/webide/theia/1-46-0/docker/image/sourcefileurl
содержит значение https://nextcloud.ispras.ru/index.php/s/gr7pa4RDJBBqAPy/download/theia-blueprint.1.46.0.sarif.clang.tar
. По этому адресу находится архив с docker-образом для Theia IDE.
Если docker-образ ещё не был загружен, то загрузка начнётся при первой попытке запуска IDE. Т.к. этот процесс занимает длительное время, то запрос запуска IDE тоже будет выполняться долго.
Для ускорения первого запуска IDE, докер образ можно загрузить на хост docker'а вручную. Для этого необходимо:
- Скачать файл архива;
- Выполнить команду
docker image load -i /path/to/tar/theia-blueprint.1.46.0.sarif.clang.tar
;
Информация о docker-образе Theia IDE
Docker-образ, используемый по умолчанию, построен на базе [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