Revision as of 13:02, 5 June 2024

Поддержка среды разработки 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 снимков:

Ресурс	Описание
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 Ответ: `"string"` - идентификатор IDE
PUT /api/snapshots/{snapshot_id}/ide	Команда управления экземпляром IDE снимка Доступные действия: `update_markup` - обновление предупреждений и разметки (sarif-файла) Параметры: `snapshot_id` - идентификатор снимка Запрос: { "action": "string", "ideId": "string" } `action` - действие `ideId` - идентификатор IDE Ответ: `"string"` - идентификатор IDE
DELETE /api/snapshots/{snapshot_id}/ide	Остановка экземпляра IDE снимка
/snapshots/{snapshot_id}/ide/{ide_id}/*	Прокси экземпляра IDE снимка

Формат идентификатора IDE {тип ide}__{идентификатор конфигурации}. Например для default-конфигурации Theia IDE: theia__default

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

Запуск 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

Help:XSvacer:Webide: Difference between revisions