Markup2

Public REST API для экспорта, импорта и копирования разметки

Релиз 10.х Svacer включает новый API предназначенный для экспорта, импорта и копирования разметки. API доступен по endpoint-ам

POST /api/public/markup/import
POST /api/public/markup/export
POST /api/public/markup/copy

Разметка описывается посредством protobuf схемы:

// Represents exported review (review itself + comments)
// Review is associated with invariant and has list of locations
message Review { 
  
  // Defines model for concrete location of the review
  message Location {            
    string warnClass = 1;
    string file = 2;
    uint32 line = 3;
    string details = 4;
    string mtid = 5;
    string function = 10;
    bytes content_hash = 6;
    bytes trace_hash = 7;
    bytes marker_hash = 8;
    bytes line_hash = 9;    
    string tool = 11;
    string lang = 12;
  }  
  // Defines model for comment
  message Comment {      
    string text = 1;
    optional string format = 2;
    google.protobuf.Timestamp create_ts = 3;
    optional google.protobuf.Timestamp update_ts = 4;
    string createdBy = 5;      
    string origin_id = 6;   
    optional uint64 review_id = 7; // refers to Review.id field
    optional string created_by_id = 8;
  }
  // Defines model for review itself
  message ReviewData {
    string status = 1;
    string severity = 2;
    string action = 3;
    string origin_id = 4;
    google.protobuf.Timestamp create_ts = 5;
    string created_by = 6;
    optional string created_by_id = 7;
    optional string created_from = 8;
  }  
  // Invariant of the marker
  string invariant = 1; 
  // Review information associated with markers having given invariant
  optional ReviewData review_data = 2;  
  // List of comments associated with all markers having given invariant
  repeated Comment comments = 3; 
  // List of locations associated with given invariant. Locations can be used to apply fuzzy matching of review with existing data when there is no invariant match  
  repeated Location locations = 4;
  // Export-specific ID, comments can refer to this id if comment is associated with review operation
  uint64 id = 5;
  // Meta-information about export, when exporting to file field is initialized only for the first element
  optional ReviewExportMeta meta = 6;
}

// Defines meta-information about exported review
message ReviewExportMeta {
  message Container {
    string id = 1;
    string name = 2;
  }  
  google.protobuf.Timestamp create_ts = 1; // timestamp when export was produced (UTC)
  string created_by = 2; // user who triggered export
  string svacer_version = 3;  // svacer version
  optional Container project = 4; // source container (project)
  optional Container branch = 5; // source container (branch)
  map<string,string> properties = 6; // extra properties
}

Актуальную версию схемы можно получить из Svacer по API: GET /api/public/markup/schema

Svacer поддерживает два формата для экспортирования/импортирования разметки:

• json с разделением по newline-ам. Каждая строка представляет собой объект типа Review (указано выше) сериализованный в JSON
• бинарный формат: последовательность блоков [lenght little endian][proto] , где первый блок содержит длину следующего блока в формате u32 little endian , а второй блок содержит proto-сериализацию объекта Review

В обоих случаях при выгрузке разметки первый элемент типа Review будет содержать мета-информацию об исходном контексте, откуда была выгружена разметка

Разметка привязывается к инварианту маркера и может содержать собственно разметку (статус маркера) и совокупность комментариев, связанных с данным маркером. При выгрузке разметки так же добавляется информация о конкретных локациях предупреждений, ассоциированных с инвариантом. В будущих версиях данная информация будет использоваться для переноса разметки при отсутствии прямого совпадения инвариантов.

Экспорт разметки

POST  /api/public/markup/export

• параметры передаются в body запроса
• запрос должен иметь токен аутентификации
• пользователь должен иметь доступы на Public API и экспорт разметки из ветки, откуда производится экспорт

Формат body:

{
    "source": ["<project name>","<branch name>"],
    "source_id": "<branch id>",
    "skip_comments": <true|false>,
    "skip_review": <true|false>,
    "format": "<json|proto>"
}

Пользователь должен указать либо source элемент, либо source_id.

Опция skip_comments позволяет игнорировать комментарии при выгрузке разметки.

Опция skip_review позволяет игнорировать статусы маркеров при выгрузке разметки (т.е выгружать только комментарии).

Метод возвращает gzipped файл содержащий разметку в указанном формате.

Импорт разметки

POST  /api/public/markup/import

• параметры передаются в query запроса
• запрос должен быть формата multipart/form-data, поле file должно содержать файл с разметкой
• запрос должен иметь токен аутентификации
• пользователь должен иметь доступы на Public API, импорт разметки или снэпшота и разрешения Update any reviewиUpdate any comment

Query параметры:

project - <project name> - имя проекта
branch - <branch name> - имя бранча
target_id - <branch id> - id бранча. Должно быть либо id бранча, либо имя проекта + имя бранча. Приоритет - id бранча
format - <proto|json> - формат импортируемой разметки, если не указан - будет определяться автоматически
overwrite - <none|force|last> - контролирует логику применения разметки к бранчу при импорте
skip_comments - <true|false> - игнорировать комментарии
skip_review - <true|false> - игнорировать статус разметки (импорт только комментариев)
response_with_result - <true|false> - вернуть детальный список разметок, какие были применены в формате json с newline 
                                      разделителями. Если не указан, то возвращается краткий статус
compressed - <true|false> - формат файла с разметкой, если true то файл подразумевается gzip-compressed

В случае успеха, метод возвращает Body со следующими данными

{"total":<total number of loaded reviews>,"applied_reviews":<applied reviews>,"applied_comments":<applied comments>,"skipped_reviews":<skipped reviews>,"duplicate_reviews":<duplicate reviews>,"duplicate_comments":<duplicate comments}
<json representation of applied review>*

Первая строка Body содержит JSON с информацией о выполненных действиях. Если бы указан параметр response_with_resultто дальше будут идти newline-separated JSON представления примененных review.

Алгоритм импорта

• Блокируются операции по разметки и импорту на целевой бранч
• Выгружается текущая разметка бранча с комментариями
• Загруженная разметка сопоставляется с текущей и формируется список разметки для применения. Дублирующая разметка и комментарии игнорируются. Перезапись разметки контролируется параметрами overwrite. Если значение none, то разметка не перезаписывается при наличии разметки в целевом бранче. Если значение force, то разметка будет перезаписана. Если значение last, то разметка будет перезаписана если загруженная разметка имеет более новую дату.
• Сформированный список применяется к бранчу. При выборе маркера, куда добавлять комментарий, выбирается маркер из наиболее раннего снимка, где маркер с соответствующим инвариантом появился.