bookmarks.proto

syntax = "proto3";

package bookmarks;

import "google/protobuf/timestamp.proto";
import "items.proto";

//  _________________________________________________________
// ||-------------------------------------------------------||
// ||.--.    .-._                        .----.             ||
// |||==|____| |H|___            .---.___|""""|_____.--.___ ||
// |||  |====| | |xxx|_          |+++|=-=|_  _|-=+=-|==|---|||
// |||==|    | | |   | \         |   |   |_\/_|Black|  | ^ |||
// |||  |    | | |   |\ \   .--. |   |=-=|_/\_|-=+=-|  | ^ |||
// |||  |    | | |   |_\ \_( oo )|   |   |    |Magus|  | ^ |||
// |||==|====| |H|xxx|  \ \ |''| |+++|=-=|""""|-=+=-|==|---|||
// ||`--^----'-^-^---'   `-' ""  '---^---^----^-----^--^---^||
// ||-------------------------------------------------------||
// ||-------------------------------------------------------||
// ||               ___                   .-.__.-----. .---.||
// ||              |===| .---.   __   .---| |XX|<(*)>|_|^^^|||
// ||         ,  /(|   |_|III|__|''|__|:x:|=|  |     |=| Q |||
// ||      _a'{ / (|===|+|   |++|  |==|   | |  |Illum| | R |||
// ||      '/\\/ _(|===|-|   |  |''|  |:x:|=|  |inati| | Y |||
// ||_____  -\{___(|   |-|   |  |  |  |   | |  |     | | Z |||
// ||       _(____)|===|+|[I]|DK|''|==|:x:|=|XX|<(*)>|=|^^^|||
// ||              `---^-^---^--^--'--^---^-^--^-----^-^---^||
// ||-------------------------------------------------------||
// ||_______________________________________________________||
// Credit: https://www.asciiart.eu/
option go_package = "github.com/overmindtech/sdp-go;sdp";

service BookmarksService {
    // ListBookmarks returns all bookmarks of the current user. note that this does not include the actual bookmark data, use GetBookmark for that
    rpc ListBookmarks(ListBookmarksRequest) returns (ListBookmarkResponse);
    // CreateBookmark creates a new bookmark
    rpc CreateBookmark(CreateBookmarkRequest) returns (CreateBookmarkResponse);
    // GetBookmark returns the bookmark with the given UUID. This can also return snapshots as bookmarks and will strip the stored items from the response.
    rpc GetBookmark(GetBookmarkRequest) returns (GetBookmarkResponse);
    rpc UpdateBookmark(UpdateBookmarkRequest) returns (UpdateBookmarkResponse);
    rpc DeleteBookmark(DeleteBookmarkRequest) returns (DeleteBookmarkResponse);

    // a helper method to find all affected apps for a given blast radius snapshot
    rpc GetAffectedBookmarks(GetAffectedBookmarksRequest) returns (GetAffectedBookmarksResponse);
}

///////////////////////////////////////////////////////////////////////////////
// bookmark handling
//
// the gateway can store, retrieve, list and delete bookmarks of queries
///////////////////////////////////////////////////////////////////////////////

// a complete Bookmark with user-supplied and machine-supplied values
message Bookmark {
    BookmarkMetadata metadata = 1;
    BookmarkProperties properties = 2;
}

// The user-editable parts of a Bookmark
message BookmarkProperties {
    // user supplied name of this bookmark
    string name = 1;
    // user supplied description of this bookmark
    string description = 2;
    // queries that make up the bookmark
    repeated Query queries = 3;
    // Items that should be excluded from the bookmark's results
    repeated Reference excludedItems = 4;
    // Whether this bookmark is a system bookmark. System bookmarks are hidden
    // from list results and can therefore only be accessed by their UUID.
    // Bookmarks created by users are not system bookmarks.
    bool isSystem = 5;
}

// Descriptor for a bookmark
message BookmarkMetadata {
    // unique id to identify this bookmark
    bytes UUID = 1;
    // timestamp when this bookmark was created
    google.protobuf.Timestamp created = 2;
}

////////////////////////////
// Requests and Responses //
////////////////////////////

// list all bookmarks
message ListBookmarksRequest {
    // TODO: pagination
}

message ListBookmarkResponse {
    repeated Bookmark bookmarks = 3;
}

// creates a new bookmark
message CreateBookmarkRequest {
    BookmarkProperties properties = 1;
}

message CreateBookmarkResponse {
    Bookmark bookmark = 1;
}

// gets a specific bookmark
message GetBookmarkRequest {
    bytes UUID = 1;
}

message GetBookmarkResponse {
    Bookmark bookmark = 1;
}

// updates an existing bookmark
message UpdateBookmarkRequest {
    // unique id to identify this bookmark
    bytes UUID = 1;
    // new attributes for this bookmark
    BookmarkProperties properties = 2;
}

message UpdateBookmarkResponse {
    Bookmark bookmark = 3;
}

// Delete the bookmark with the specified ID.
message DeleteBookmarkRequest {
    // unique id of the bookmark to delete
    bytes UUID = 1;
}

message DeleteBookmarkResponse {
}

message GetAffectedBookmarksRequest {
    // the snapshot to consider
    bytes snapshotUUID = 1;
    // the bookmarks to filter
    repeated bytes bookmarkUUIDs = 2;
}

message GetAffectedBookmarksResponse {
    // the bookmarks that intersected with the snapshot
    repeated bytes bookmarkUUIDs = 1;
}