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

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

REST API управления IDE

Ресурс	Описание
GET /api/ide	Получение списка доступных для запуска IDE. Ответ: [ { "id": "string", "name": "string", "order": 0 } ] id - идентификатор IDE name - название IDE order - порядковый номер IDE в списке
GET /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 /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 /api/snapshots/{snapshot_id}/ide	Остановка экземпляра IDE снимка Параметры: snapshot_id - идентификатор снимка Запрос: { "ideId": "string" } ideId - идентификатор IDE Ответ: пустой
/snapshots/{snapshot_id}/ide/{ide_id}/*	Прокси для запросов экземпляра IDE снимка

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

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

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

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

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

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

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

Запуск IDE

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

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

1. Производится проверка: была ли уже запущена указанная IDE для указанного снимка;
   • Если запущена: производится проверка: доступна ли IDE: отвечает на запросы;
     • Если IDE доступна: действие не требуется. Процесс запуска завершается;
     • Если IDE не доступна: продолжается процесс запуска. IDE будет перезапущена;
2. Создаётся "корневая папка снимка", предназначенная для хранения исходного кода снимка и предупреждений анализатора с разметкой в виде sarif-файла. Название папки соответствует id снимка. Папка создаётся по пути заданному в параметре конфигурации IDE xsvacer/webide/theia/{идентификатор конфигурации}/sourcesroot;
3. Исходный код снимка скачивается в "корневую папку снимка";
4. Производится экспорт маркеров и разметки в виде sarif-файла в "корневую папку снимка". Название sarif-файла формируется с помощью шаблона, заданного в параметре конфигурации IDE xsvacer/webide/theia/{идентификатор конфигурации}/sariffiletemplate;
5. Производится настройка и запуск 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 прервётся;
6. После успешного запуска 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

При повторном запуске IDE либо при поступлении запроса, который должен быть спроксирован к docker-контейнеру IDE, проверяется её доступность. В случае потери соединения с IDE производится попытка её перезапуска. В этом случае происходит та же последовательность действий, что и при первоначальном запуске 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-хост. 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

Рекомендации

Предварительная загрузка 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'а вручную. Для этого необходимо:

1. Скачать файл архива;
2. Выполнить команду docker image load -i /path/to/tar/theia-blueprint.1.46.0.sarif.clang.tag;