extension_service.proto

/**
# Расширения (Extensions)

Расширения представляют собой отдельные сервисы предоставляющие дополнительные возможности для пользователей. Сервис
может предоставлять несколько расширений одновременно.

Для координации взаимодействия используется сервис менеджер расширений (Extension Manager). Для предоставления своих функций в систему сервис должен
зарегистрироваться на контроллере.

*/
syntax = "proto3";

option go_package = "git.perx.ru/perxis/perxis-go/proto/extensions;extensions";

package extensions;

import "references/references.proto";
import "common/operation.proto";
import "extensions/extension.proto";

// ExtensionService - API расширения
// Сервис должен реализовывать методы `common.OperationService` для работы операциями.
service ExtensionService {

  // Install выполняет установку указанных расширений. Если
  // расширение уже установлены выполняет процесс переустановки. Возвращает longtime операцию
  rpc Install(InstallRequest) returns (common.Operation) {}

  // Uninstall выполняет удаление указанных расширений.
  rpc Uninstall(UninstallRequest) returns (common.Operation) {}

  // Check выполняет проверку установки для расширения. При этом расширение проверяет наличие необходимых данных в
  // пространстве или наличие новой версии расширения и сообщает об этом. Никаких действий с данными пространства не
  // производится.
  rpc Check(CheckRequest) returns (common.Operation) {}

  // Пользовательские Действия (Actions)
  //
  // Пользовательские действия позволяют расширить функционал пользовательского интерфейса путем
  // добавления в интерфейс элементов взаимодействуя с которыми пользователь может вызывать реакцию на
  // сервере или переход в интерфейсе.
  //
  // Пользовательские действия добавляются при установке расширений в системную коллекции `System/Actions`.
  // Коллекция создается автоматически менеджером расширений. При установке так же отображается меню `Действия`
  // доступное для всех пользователей.
  //
  // Примеры пользовательских действий:
  // - "Собрать сайт" - добавляется Perxis.Web для сборки сайта, доступна пользователю через меню,
  //   параметры space_id, env_id. При вызове выполняется запрос на сервер ProcessAction.
  // - "Посмотреть задачи" - добавляется Tasks для перехода на коллекцию задач. Отображается в меню,
  //   параметры space_id, env_id.
  //
  // Приложения так же могут использовать действия для вызова обработки в других приложениях при
  // необходимости.
  rpc Action(ActionRequest) returns(ActionResponse) {} // Выполнить указанное действие
}


// InstallRequest - запрос на установку расширений
message InstallRequest {
  repeated string extensions = 10000; // Список расширений для установки
  string space_id = 10010; // Пространство для установки расширений
  string env_id = 10020; // Идентификатор окружения для установки (по умолчанию master)
  bool force = 10100; // Устанавливать расширения вне зависимости от возможных ошибок
  bool update = 10200; // Установить обновления расширений
}

// UninstallRequest - запрос на удаление расширений
message UninstallRequest {
  repeated string extensions = 10000; // Список расширений для удаления
  string space_id = 10010; // Пространство для удаления расширений
  string env_id = 10020; // Идентификатор окружения для установки (по умолчанию master)
  bool remove = 10100; // Удалить изменения сделанные расширением в пространстве, если возможно
  bool force = 10200; // Удалять расширения вне зависимости от возможных ошибок, без учета зависимостей
}


// CheckRequest - запрос на проверку статуса установки расширений
message CheckRequest {
  repeated string extensions = 10000; // Список расширений для удаления
  string space_id = 10010; // Пространство для удаления расширений
  string env_id = 10020; // Идентификатор окружения для установки (по умолчанию master)
}

message ActionResponse {
  enum State {
    DONE = 0; // Запрос завершен
    ERROR = 1; // Возникла ошибка
    PENDING = 2; // Запрос ожидает выполнения
    IN_PROGRESS = 3; // Запрос выполняется
    PARAMETERS_REQUIRED = 4; // Требуются дополнительные данные для выполнения запроса
  }

  enum Format {
    PLAIN = 0;
    HTML = 1;
    MARKDOWN = 2;
  }

  State state = 10000;  // Состояние расширение
  Target target = 10010; // Как открывать результат выполнения действия в пользовательском интерфейсе (переопределяет значение в Action)
  Format format = 10050; // Формат полей msg  и error
  string msg = 10100; // Сообщение о выполнении действия
  string title = 10110; // Текст для отображения в интерфейсе
  string image = 10140; // Изображение для отображения в интерфейсе (шапке окна)
  string error = 10200; // Сообщение в случае ошибки (дополнительно к msg)
  repeated Action next = 10300; // Следующие возможные действия. Интерфейс отображает как варианты дальнейших действий пользователя
  map<string,string>metadata = 10400; // Метаданные запроса
  repeated content.references.Reference refs = 10320; // Ссылки на записи (назначение ссылок зависит от действия и расширения)
}