items.proto

syntax = "proto3";

import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "responses.proto";

// _____/\\\\\\\\\\\____/\\\\\\\\\\\\_____/\\\\\\\\\\\\\___
//  ___/\\\/////////\\\_\/\\\////////\\\__\/\\\/////////\\\_
//   __\//\\\______\///__\/\\\______\//\\\_\/\\\_______\/\\\_
//    ___\////\\\_________\/\\\_______\/\\\_\/\\\\\\\\\\\\\/__
//     ______\////\\\______\/\\\_______\/\\\_\/\\\/////////____
//      _________\////\\\___\/\\\_______\/\\\_\/\\\_____________
//       __/\\\______\//\\\__\/\\\_______/\\\__\/\\\_____________
//        _\///\\\\\\\\\\\/___\/\\\\\\\\\\\\/___\/\\\_____________
//         ___\///////////_____\////////////_____\///______________
option go_package = "github.com/overmindtech/sdp-go;sdp";

// Represents the health of something, the meaning of each state may depend on
// the context in which it is used but should be reasonably obvious
enum Health {
  HEALTH_UNKNOWN = 0; // The health could not be determined
  HEALTH_OK = 1; // Functioning normally
  HEALTH_WARNING = 2; // Functioning, but degraded
  HEALTH_ERROR = 3; // Not functioning
  HEALTH_PENDING = 4; // Health state is transitioning, such as when something is first provisioned
}

// This message stores additional information on Edges (and edge-like constructs) to determine how configuration changes can impact
// the linked items.
//
//  Blast Propagation options:
// |-------|-------|----------------------
// |   in  |  out  | result
// |-------|-------|----------------------
// | false | false | no change in any item can affect the other
// | false | true  | a change to this item can affect its linked items
// |       |       | example: a change to an EC2 instance can affect its DNS name (in the sense that other items depending on that DNS name will see the impact)
// | true  | false | a change to linked items can affect this item
// |       |       | example: changing the KMS key used by a DynamoDB table can impact the table, but no change to the table can impact the key
// | true  | true  | changes on both sides of the link can affect the other
// |       |       | example: changes to both EC2 Instances and their volumes can affect the other side of the relation.
message BlastPropagation {
  // is true if changes on linked items can affect this item
  bool in = 1;
  // is true if changes on this item can affect linked items
  bool out = 2;
}

// An annotated query to indicate potential linked items.
message LinkedItemQuery {
  // the query that would find linked items
  Query query = 1;

  // how configuration changes (i.e. the "blast") propagates over this link
  BlastPropagation blastPropagation = 2;
}

// An annotated reference to list linked items.
message LinkedItem {
  // the linked item
  Reference item = 1;

  // how configuration changes (i.e. the "blast") propagates over this link
  BlastPropagation blastPropagation = 2;
}

// This is the same as Item within the package with a couple of exceptions, no
// real reason why this whole thing couldn't be modelled in protobuf though if
// required. Just need to decide what if anything should remain private
message Item {
  string type = 1;
  string uniqueAttribute = 2;
  ItemAttributes attributes = 3;
  Metadata metadata = 4;

  // The scope within which the item is unique. Item uniqueness is determined
  // by the combination of type and uniqueAttribute value. However it is
  // possible for the same item to exist in many scopes. There is not formal
  // definition for what a scope should be other than the fact that it should
  // be somewhat descriptive and should ensure item uniqueness
  string scope = 5;

  // Not all items will have relatedItems we are are using a two byte
  // integer to save one byte integers for more common things
  repeated LinkedItemQuery linkedItemQueries = 16;

  // Linked items
  repeated LinkedItem linkedItems = 17;

  // (optional) Represents the health of the item. Only items that have a
  // clearly relevant health attribute should return a value for health
  optional Health health = 18;

  // Arbitrary key-value pairs that can be used to store additional information.
  // These tags are retrieved from the source and map to the target's definition
  // of a tag (e.g. AWS tags, Kubernetes labels, etc.)
  map<string, string> tags = 19;
}

// ItemAttributes represents the known attributes for an item. These are likely
// to be common to a given type, but even this is not guaranteed. All items must
// have at least one attribute however as it needs something to uniquely
// identify it
message ItemAttributes {
  google.protobuf.Struct attrStruct = 1;
}

// Metadata about the item. Where it came from, how long it took, etc.
message Metadata {
  // This is the name of the source that was used to find the item.
  string sourceName = 2;

  // The query that caused this item to be found. This is for gateway-internal use and will not be exposed to the frontend.
  Query sourceQuery = 3;

  // The time that the item was found
  google.protobuf.Timestamp timestamp = 4;

  // How long the source took to execute in total when processing the
  // Query
  google.protobuf.Duration sourceDuration = 5;

  // How long the source took to execute per item when processing the
  // Query
  google.protobuf.Duration sourceDurationPerItem = 6;

  // Whether the item should be hidden/ignored by user-facing things such as
  // GUIs and databases.
  //
  // Some types of items are only relevant in calculating higher-layer
  // abstractions and are therefore always hidden. A good example of this would
  // be the output of a command. This could be used by a remote source to gather
  // information, but we don't actually want to show the user all the commands
  // that were run, just the final item returned by the source
  bool hidden = 7;

  // The UUID of the QUERY that caused this item to be found
  bytes sourceQueryUUID = 8 [deprecated = true];
}

// This is a list of items, like a List() would return
message Items {
  repeated Item items = 1;
}

// Query represents a query for an item or a list of items.
message Query {
  // The type of item to search for. "*" means all types
  string type = 1;

  // Which method to use when looking for it
  QueryMethod method = 2;

  // What query should be passed to that method
  string query = 3;

  // Defines how this query should behave when finding new items
  message RecursionBehaviour {
    // How deeply to link items. A value of 0 will mean that items are not linked.
    // To resolve linked items "infinitely" simply set this to a high number, with
    // the highest being 4,294,967,295. While this isn't truly *infinite*, chances
    // are that it is effectively the same, think six degrees of separation etc.
    uint32 linkDepth = 1;

    // set to true to only follow links that propagate configuration change impact
    bool followOnlyBlastPropagation = 2;
  }

  // Defines how this query should behave when finding new items
  RecursionBehaviour recursionBehaviour = 4;

  // The scope for which we are requesting. To query all scopes use the the
  // wildcard '*'
  string scope = 5;

  // Whether to ignore the cache and execute the query regardless.
  //
  // By default sources will implement some level of caching, this is
  // particularly important for linked items as a single query with a large link
  // depth may result in the same item being queried many times as links are
  // resolved and more and more items link to each other. However if required
  // this caching can be turned off using this parameter
  bool ignoreCache = 6;

  // A UUID to uniquely identify the query. This should be stored by the
  // requester as it will be needed later if the requester wants to cancel a
  // query. It should be stored as 128 bytes, as opposed to the textual
  // representation
  bytes UUID = 7;

  reserved 8;

  // The deadline for this query. When the deadline elapses, results become
  // irrelevant for the sender and any processing can stop. The deadline gets
  // propagated to all related queries (e.g. for linked items) and processes.
  // Note: there is currently a migration going on from timeouts to durations,
  // so depending on which service is hit, either one is evaluated.
  google.protobuf.Timestamp deadline = 9;
}

message QueryResponse {
  oneof response_type {
    Item newItem = 2; // A new item that has been discovered
    Response response = 3; // Status update
    QueryError error = 4; // An error has been encountered
  }
}

// QueryStatus informs the client of status updates of all queries running in this session.
message QueryStatus {
  // UUID of the query
  bytes UUID = 1;

  // The error type. Any types in here will be gracefully handled unless the
  // type os "OTHER"
  enum Status {
    // the status has not been specified
    UNSPECIFIED = 0;

    // the query has been started
    STARTED = 1;

    // TODO: add more detailed progress information here (number of items sent? number of sub-queries triggered and their status?)
    // the query is progressing
    // PROGRESSING = 2;
    reserved 2;

    // the query has been cancelled.
    // This is a final state.
    CANCELLED = 3;

    // the query has finished with an error status. expect a separate QueryError describing that.
    // This is a final state.
    // TODO: fold the error details into this message
    ERRORED = 4;

    // The query has finished and all results have been sent over the wire
    // This is a final state.
    FINISHED = 5;
  }
  Status status = 2;
}

// QueryError is sent back when an item query fails
message QueryError {
  // UUID of the item query that this response is in relation to (in binary
  // format)
  bytes UUID = 1;

  // The error type. Any types in here will be gracefully handled unless the
  // type os "OTHER"
  enum ErrorType {
    // This should be used of all other failure modes, such as timeouts,
    // unexpected failures when querying state, permissions errors etc. Errors
    // that return this type should not be cached as the error may be transient.
    OTHER = 0;

    // NOTFOUND means that the item was not found. This is only returned as the
    // result of a GET query since all other queries would return an empty
    // list instead
    NOTFOUND = 1;

    // NOSCOPE means that the item was not found because we don't have
    // access to the requested scope. This should not be interpreted as "The
    // item doesn't exist" (as with a NOTFOUND error) but rather as "We can't
    // tell you whether or not the item exists"
    NOSCOPE = 2;

    // TIMEOUT means that the source times out when trying to query the item.
    // The timeout is provided in the original query
    TIMEOUT = 3;
  }
  ErrorType errorType = 2;

  // The string contents of the error
  string errorString = 3;

  // The scope from which the error was raised
  string scope = 4;

  // The name of the source which raised the error (if relevant)
  string sourceName = 5;

  // The type of item that we were looking for at the time of the error
  string itemType = 6;

  // The name of the responder that this error was raised from
  string responderName = 7;
}

// QueryMethod represents the available query methods. The details of these
// methods are:
//
// GET: This takes a single unique query and should only return a single item.
//      If an item matching the parameter passed doesn't exist the server should
//      fail
//
// LIST: This takes no query (or ignores it) and should return all items that it
//       can find
//
// SEARCH: This takes a non-unique query which is designed to be used as a
//         search term. It should return some number of items (or zero) which
//         match the query
enum QueryMethod {
  GET = 0;
  LIST = 1;
  SEARCH = 2;
}

// The message signals that the Query with the corresponding UUID should
// be cancelled. Work should stop immediately, and a final response should be
// sent with a state of CANCELLED to acknowledge that the query has ended due
// to a cancellation
message CancelQuery {
  // UUID of the Query to cancel
  bytes UUID = 1;
}

// This message is sent to the gateway to instruct it to "undo" a query. This
// means that the query will be removed from the session, along with all items
// and edges that were a result of that query. If these items have already
// been sent to the client, the gateway will send `deleteItem` messages instructing
// the client to delete them
message UndoQuery {
  // UUID of the Query to cancel
  bytes UUID = 1;
}

// This requests that the gateway "expands" an item. This involves executing all
// linked item queries within the session and sending the results to the
// client. It is recommended that this be used rather than simply sending each
// linked item request. Using this request type allows the Gateway to save the
// session more intelligently so that it can be bookmarked and used later.
// "Expanding" an item will mean an item always acts the same, even if its
// linked item queries have changed
message Expand {
  // The item that should be expanded
  Reference item = 1;
  // How many levels of expansion should be run
  uint32 linkDepth = 2;

  // A UUID to uniquely identify the request. This should be stored by the
  // requester as it will be needed later if the requester wants to cancel a
  // request. It should be stored as 128 bytes, as opposed to the textual
  // representation
  bytes UUID = 3;
  // The time at which the gateway should stop processing the queries spawned by this request
  google.protobuf.Timestamp deadline = 4;
}

// This message is sent to the gateway to instruct it to "undo" an Expand. This
// means that the expansion will be removed from the session, along with all items
// and edges that were a result of that request. If these items have already
// been sent to the client, the gateway will send `deleteItem` messages instructing
// the client to delete them
message UndoExpand {
  // UUID of the Expand to cancel
  bytes UUID = 1;
}

// Reference to an item
//
// The uniqueness of an item is determined by the combination of:
//
//   * Type
//   * UniqueAttributeValue
//   * Scope
//
message Reference {
  string type = 1;
  string uniqueAttributeValue = 2;
  string scope = 3;

  bool isQuery = 4;
  string query = 5;
  QueryMethod method = 6;
}

// Edge Represents a link between two items, it is not used in regular SDP
// queries as it's up to the client to infer the edges from the LinkedItems
// field, however request managed by the gateway will explicitly send edges to
// reduce the processing burden on the client side
message Edge {
  Reference from = 1;
  Reference to = 2;

  BlastPropagation blastPropagation = 3;
}