account.proto

syntax = "proto3";

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

package account;

option go_package = "github.com/overmindtech/sdp-go;sdp";

//                            _
//       .::::::::::.        -(_)====u         .::::::::::.
//     .::::''''''::::.                      .::::''''''::::.
//   .:::'          `::::....          ....::::'          `:::.
//  .::'             `:::::::|        |:::::::'             `::.
// .::|               |::::::|_ ___ __|::::::|               |::.
// `--'               |::::::|_()__()_|::::::|               `--'
//  :::               |::-o::|        |::o-::|               :::
//  `::.             .|::::::|        |::::::|.             .::'
//   `:::.          .::\-----'        `-----/::.          .:::'
//     `::::......::::'                      `::::......::::'
//       `::::::::::'                          `::::::::::'
// Credit: https://www.asciiart.eu/

// The admin service allows users with Admin privileges to any account. Many of
// the RPCs in this service mirror RPCs in the ManagementService, but allow the
// user to specify an account to operate on, rather than using the account that
// the user belongs to.
service AdminService {
    // Lists the details of all NATS Accounts
    rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
    // Creates a new account, public_nkey will be autogenerated
    rpc CreateAccount(CreateAccountRequest) returns (CreateAccountResponse);
    // Updates account details, returns the account
    rpc UpdateAccount(AdminUpdateAccountRequest) returns (UpdateAccountResponse);
    // Get the details of a given account
    rpc GetAccount(AdminGetAccountRequest) returns (GetAccountResponse);
    // Completely deletes an account. This includes all of the data in that
    // account, bookmarks, changes etc. It also deletes all users from Auth0
    // that are associated with this account
    rpc DeleteAccount(AdminDeleteAccountRequest) returns (AdminDeleteAccountResponse);

    // Lists all sources within the chosen account
    rpc ListSources(AdminListSourcesRequest) returns (ListSourcesResponse);
    // Creates a new source within the chosen account
    rpc CreateSource(AdminCreateSourceRequest) returns (CreateSourceResponse);
    // Get the details of a source within the chosen account
    rpc GetSource(AdminGetSourceRequest) returns (GetSourceResponse);
    // Update the details of a source within the chosen account
    rpc UpdateSource(AdminUpdateSourceRequest) returns (UpdateSourceResponse);
    // Deletes a source from a chosen account
    rpc DeleteSource(AdminDeleteSourceRequest) returns (DeleteSourceResponse);

    // Updates sources to keep them running in the background. This can be used
    // to add explicit action, when the built-in keepalives are not sufficient.
    rpc KeepaliveSources(AdminKeepaliveSourcesRequest) returns (KeepaliveSourcesResponse);

    // Create a new NATS token for a given public NKey. The user requesting must
    // control the associated private key also in order to connect to NATS as
    // the token is not enough on its own
    rpc CreateToken(AdminCreateTokenRequest) returns (CreateTokenResponse);
}

// TODO: Decide if I should have the admin requests return the exact same
// responses as the non-admin ones or should I change it?

message ListAccountsRequest {}
message ListAccountsResponse {
    repeated Account accounts = 1;
}

message CreateAccountRequest {
    AccountProperties properties = 1;
}
message CreateAccountResponse {
    Account account = 1;
}

message UpdateAccountRequest {
    AccountProperties properties = 1;
}
message UpdateAccountResponse {
    Account account = 1;
}
message AdminUpdateAccountRequest {
    // The name of the account to update
    string name = 1;
    UpdateAccountRequest request = 2;
}

message AdminGetAccountRequest {
    // The name of the account to get
    string name = 1;
}

message AdminDeleteAccountRequest {
    // The name of the account to delete
    string name = 1;
}
message AdminDeleteAccountResponse {}

message AdminListSourcesRequest {
    string account = 1;
    ListSourcesRequest request = 2;
}
message AdminCreateSourceRequest {
    string account = 1;
    CreateSourceRequest request = 2;
}
message AdminGetSourceRequest {
    string account = 1;
    GetSourceRequest request = 2;
}
message AdminUpdateSourceRequest {
    string account = 1;
    UpdateSourceRequest request = 2;
}
message AdminDeleteSourceRequest {
    string account = 1;
    DeleteSourceRequest request = 2;
}
message AdminKeepaliveSourcesRequest {
    string account = 1;
    KeepaliveSourcesRequest request = 2;
}
message AdminCreateTokenRequest {
    string account = 1;
    CreateTokenRequest request = 2;
}

// RPCs to manage the user's account, sources etc. All requests to this API are
// scoped to that user's account via the
// `https://api.overmind.tech/account-name` claim in the supplied token
service ManagementService {
    // Get the details of the account that this user belongs to
    rpc GetAccount(GetAccountRequest) returns (GetAccountResponse);
    // Completely deletes the user's account. This includes all of the data in
    // that account, bookmarks, changes etc. It also deletes the current user,
    // and all other users in that account from Auth0
    rpc DeleteAccount(DeleteAccountRequest) returns (DeleteAccountResponse);

    // Lists all sources within the user's account
    rpc ListSources(ListSourcesRequest) returns (ListSourcesResponse);
    // Creates a new source within the user's account
    rpc CreateSource(CreateSourceRequest) returns (CreateSourceResponse);
    // Get the details of a source
    rpc GetSource(GetSourceRequest) returns (GetSourceResponse);
    // Update the details of a source
    rpc UpdateSource(UpdateSourceRequest) returns (UpdateSourceResponse);
    // Deletes a source from a user's account
    rpc DeleteSource(DeleteSourceRequest) returns (DeleteSourceResponse);

    // Sources heartbeat and health
    // List of all recently active sources and their health, includes information from srcman
    // meaning that it can show the status of managed sources that have not started and
    // connected yet
    rpc ListAllSourcesStatus(ListAllSourcesStatusRequest) returns (ListAllSourcesStatusResponse);
    // Lists all active sources and their health. This should be used to determine
    // what types, scopes etc are available rather than `ListAllSourcesStatus` since
    // this endpoint only include running, available sources
    rpc ListActiveSourcesStatus(ListAllSourcesStatusRequest) returns (ListAllSourcesStatusResponse);
    // Heartbeat from a source to keep it registered and healthy
    rpc SubmitSourceHeartbeat(SubmitSourceHeartbeatRequest) returns (SubmitSourceHeartbeatResponse);

    // Updates sources to keep them running in the background. This can be used
    // to add explicit action, when the built-in keepalives are not sufficient.
    rpc KeepaliveSources(KeepaliveSourcesRequest) returns (KeepaliveSourcesResponse);

    // Create a new NATS token for a given public NKey. The user requesting must
    // control the associated private key also in order to connect to NATS as
    // the token is not enough on its own
    rpc CreateToken(CreateTokenRequest) returns (CreateTokenResponse);

    // Ensure that all reverse links are populated. This does internal debouncing
    // so the actual logic does only run when required.
    rpc RevlinkWarmup(RevlinkWarmupRequest) returns (stream RevlinkWarmupResponse);

    rpc GetTrialEnd(GetTrialEndRequest) returns (GetTrialEndResponse);

    // Lists all the available item types that can be discovered by sources that are running and healthy
    rpc ListAvailableItemTypes(ListAvailableItemTypesRequest) returns (ListAvailableItemTypesResponse);
}

enum SourceStatus {
    STATUS_UNSPECIFIED = 0;
    // The source is starting or updating. This is only applicable to managed
    // sources where Overmind manages the source's lifecycle
    STATUS_PROGRESSING = 1;
    // The source is healthy
    STATUS_HEALTHY = 2;
    // The source is unhealthy
    STATUS_UNHEALTHY = 3;
    // The source is sleeping due to inactivity. It will be woken up before it
    // is needed. This is only applicable to managed sources where Overmind
    // manages the source's lifecycle
    STATUS_SLEEPING = 4;
    // The source is disconnected and therefore not able to handle requests.
    // This will only be returned for non-managed sources that have recently
    // stopped sending heartbeats such as a user running the CLI that has
    // recently disconnected
    STATUS_DISCONNECTED = 5;
}

message Source {
    SourceMetadata metadata = 1;
    SourceProperties properties = 2;
}

message SourceMetadata {
    bytes UUID = 1; // TODO: Change to ID along with everything else

    // The name of the NATS JWT that has been generated for this source
    string TokenName = 2;

    // When the NATS JWT expires (unix time)
    google.protobuf.Timestamp TokenExpiry = 4;

    // The public NKey associated with the NATS JWT
    string PublicNkey = 5;

    // Status of the source
    SourceStatus Status = 9;

    // The error message if the source is unhealthy
    string Error = 10;

}

// A source that is capable of discovering items
message SourceProperties {
    // The descriptive name of the source
    string DescriptiveName = 1;

    // What source to configure. Currently either "stdlib" or "aws"
    string Type = 2;

    // Config for this source. See the source documentation for what
    // source-specific config is available/required. This will be supplied
    // directly to viper via a config file at `/etc/srcman/config/source.yaml`
    google.protobuf.Struct Config = 3;

    // Additional config options that should be passed to the source. The keys
    // of this object should be file names, and the values should be their
    // content. These files will be made available to the source at runtime.
    // Check the source's documentation for what to configure here if required
    google.protobuf.Struct AdditionalConfig = 4;
}

message Account {
    AccountMetadata metadata = 1;
    AccountProperties properties = 2;
}

message AccountMetadata {
    // The public Nkey which signs all NATS "user" tokens
    string PublicNkey = 2;
}

message AccountProperties {
    // The name of the account
    string Name = 1;
    // The Customer ID within Stripe
    string StripeCustomerID = 2;
}

message GetAccountRequest {}
message GetAccountResponse {
   Account account = 1;
}

message DeleteAccountRequest {
    // Set to true to confirm that the user is sure they want to delete their
    // account. This is to prevent accidental deletions
    bool iAmSure = 1;
}
message DeleteAccountResponse {}

message ListSourcesRequest {}
message ListSourcesResponse {
    repeated Source Sources = 1;
}

message CreateSourceRequest {
    SourceProperties properties = 1;
}

message CreateSourceResponse {
    Source source = 1;
}

message GetSourceRequest {
    bytes UUID = 1;
}

message GetSourceResponse {
    Source source = 1;
}

message UpdateSourceRequest {
    // ID of the source to update
    bytes UUID = 1;
    // Properties to update
    SourceProperties properties = 2;
}

message UpdateSourceResponse {
    Source source = 1;
}

message DeleteSourceRequest {
    // ID if the source to delete
    bytes UUID = 1;
}

message DeleteSourceResponse {}

message SourceKeepaliveResult {
    // The UUID of the source that was kept alive
    bytes UUID = 1;
    // The status of the source
    SourceStatus Status = 2;
    // The error message if the source is unhealthy
    string Error = 3;
}

message ListAllSourcesStatusRequest {}

// Whether the source is managed by srcman or was created by the user locally
enum SourceManaged {
    LOCAL = 0; // Local is the default
    MANAGED = 1;
}

message SourceHealth {
    // The UUID of the source
    bytes UUID = 1;
    // The version of the source
    string version  = 2;
    // The name of the source
    string name = 3;
    // The error message if the source is unhealthy
    optional string error = 4;
    // The status of the source, this is calculated based on the last heartbeat received and if there is an error
    SourceStatus status = 5;
    // Created at time
    google.protobuf.Timestamp createdAt = 6;
    // The last time we received a heartbeat from the source
    google.protobuf.Timestamp lastHeartbeat = 7;
    // The next time we expect to receive a heartbeat from the source
    google.protobuf.Timestamp nextHeartbeat = 8;
    // The type of the source, AWS or Stdlib or Kubernetes
    string type = 9;
    // Whether the source is managed, or local
    SourceManaged managed = 10;
    // The types of sources that this source can discover
    repeated string availableTypes = 11;
    // The scopes that this source can discover
    repeated string availableScopes = 12;
    // AdapterMetadata is a map of metadata that the source can send to the API
    repeated AdapterMetadata adapterMetadata = 13;
}

message ListAllSourcesStatusResponse {
    repeated SourceHealth sources = 1;
}

// The source sends a heartbeat to the API to let it know that it is still alive, note it does not give a status.
message SubmitSourceHeartbeatRequest {
    // The UUID of the source that is sending the heartbeat
    bytes UUID = 1;
    // The version of the source
    string version = 2;
    // The name of the source
    string name = 3;
    // The error message if the source is unhealthy
    optional string error = 4;
    // The maximum time between heartbeats that the source can send to the api-server. Otherwise, the source will be marked as unhealthy. eg 30s
    google.protobuf.Duration nextHeartbeatMax = 5;
    // The type of the source, AWS or Stdlib or Kubernetes
    string type = 6;
    // Whether the source is managed, or local
    SourceManaged managed = 7;
    // 8 is no longer used
    reserved 8;
    // The scopes that this source can discover
    repeated string availableScopes = 9;
    // AdapterMetadata is a map of metadata that the source can send to the API
    repeated AdapterMetadata adapterMetadata = 10;
}

message AdapterMetadata {
    // The type of item that this adapter returns e.g. eks-cluster
    string type = 1;
    // The category that these items fall under
    AdapterCategory category = 2;
    // The list of other types that this can be linked to, eg eks-cluster ->
    // eks-node-group
    repeated string potentialLinks = 3;
    // A descriptive name of the types of items that are returned by this
    // adapter e.g. "EKS Cluster"
    string descriptiveName = 4;
    // The supported query methods for this adapter
    AdapterSupportedQueryMethods supportedQueryMethods = 5;
    // The terraform mappings for this adapter, this is optional
    repeated TerraformMapping terraformMappings = 6;
}

enum AdapterCategory {
    // Fall-back category for resources that do not fit into any other category
    ADAPTER_CATEGORY_OTHER = 0;

    // This category includes resources that provide processing power and host
    // applications or services. Examples are virtual machines, containers,
    // serverless functions, and application hosting platforms. If the primary
    // purpose of a resource is to execute workloads, run code, or host
    // applications, it should belong here.
    ADAPTER_CATEGORY_COMPUTE_APPLICATION = 1;

    // Encompassing resources designed to store, archive, and manage data, this
    // category includes object storage, block storage, file storage, and data
    // backup solutions. Select this category when the core function of a
    // resource is persistent data storage or management
    ADAPTER_CATEGORY_STORAGE = 2;

    // This category covers resources that facilitate connectivity and
    // communication within cloud environments. Typical resources include
    // virtual networks, load balancers, VPNs, and DNS services. Assign
    // resources here if their primary role is related to communication,
    // connectivity, or traffic management
    ADAPTER_CATEGORY_NETWORK = 3;

    // Resources in this category focus on safeguarding data, applications, and
    // cloud infrastructure. Examples include firewalls, identity and access
    // management, encryption services, and security monitoring tools. Choose
    // this category if a resource's main function is security, access control,
    // or compliance
    ADAPTER_CATEGORY_SECURITY = 4;

    // This category includes resources aimed at monitoring, tracing, and
    // logging applications and cloud infrastructure. Examples are monitoring
    // tools, logging services, and performance management solutions. Use this
    // category for resources that provide insights into system performance and
    // health
    ADAPTER_CATEGORY_OBSERVABILITY = 5;

    // Focused on structured data storage and management, this category includes
    // relational, NoSQL, and in-memory databases, along with data warehousing
    // solutions. Choose this category for resources specifically designed for
    // data querying, transaction processing, or complex data operations. This
    // differs from "storage" in that "databases" have compute associated with
    // them rather than just storing data.
    ADAPTER_CATEGORY_DATABASE = 6;

    // This category includes resources designed for managing configurations and
    // deployments. Examples are infrastructure as code tools, configuration
    // management services, and deployment orchestration solutions. Classify
    // resources here if they primarily handle configuration, environment
    // management, or automated deployment
    ADAPTER_CATEGORY_CONFIGURATION = 7;

    // This category is dedicated to resources for developing, training, and
    // deploying artificial intelligence models and machine learning
    // applications. Include machine learning platforms, AI services, and data
    // labeling tools here. Select this category if a resource's principal
    // function involves AI or machine learning processes
    ADAPTER_CATEGORY_AI = 8;
}

// The methods that this adapter supports, and the description of how to use
// them
message AdapterSupportedQueryMethods{
    // Whether or not the GET method is supported
    bool get = 1;
    // Description of the query that should be passed to the GET method
    string getDescription = 2;

    // Whether or not the LIST method is supported
    bool list = 3;
    // Description of how the LIST method works
    string listDescription = 4;

    // Whether or not the SEARCH method is supported
    bool search = 5;
    // Description of the query that should be passed to the SEARCH method
    string searchDescription = 6;
}

// When Overmind ingests Terraform changes, it needs to be able to map from a
// given Terraform resource, to that same resource in Overmind. This is achieved
// by using the TerraformMapping object. It translates the details of a Terraform
// resource into a query that Overmind can run.
//
// NOTE: The queries that are generated by this mapping use the wildcard scope
// `*` and therefore could return multiple items. Overmind will compare the
// attributes of these items to determine the most likely candidate for a mch
// and select that.
message TerraformMapping {
    // The method that the query should use
    QueryMethod terraformMethod = 1;

    // How to map data from the terraform resource to the "query" field in the
    // resulting mapping query. This uses HCL syntax  e.g.
    // resource_type.attribute_name
    //
    // Usually this will be the attribute that uniquely identifies the resource
    // such as `aws_instance.id` or `aws_iam_role.arn`. You can also index into
    // arrays e.g. `kubernetes_replication_controller.metadata[0].name`
    string terraformQueryMap = 2;

    reserved 3;
}

message SubmitSourceHeartbeatResponse {}

message KeepaliveSourcesRequest {
    // Set to true to have the API call wait until the source is up and healthy
    bool waitForHealthy = 1;
}
message KeepaliveSourcesResponse {
    // If the user requested to wait for the sources to be healthy, this will
    // contain information about the sources that came up. If the user did not
    // request to wait, this will be empty
    repeated SourceKeepaliveResult sources = 1;
}

message CreateTokenRequest {
    // The Public NKey of the user that is requesting a token
    string userPublicNkey = 1;

    // Friendly user name
    string userName = 2;
}

message CreateTokenResponse {
    // The JWT as a raw string
    string token = 1;
}

message RevlinkWarmupRequest {}

message RevlinkWarmupResponse {
    string status = 1;
    int32 items = 2;
    int32 edges = 3;
}

message GetTrialEndRequest {}

message GetTrialEndResponse {
    google.protobuf.Timestamp endsAt = 1;
}

message AvailableItemType {
    // The type of item that this adapter returns e.g. eks-cluster
    string type = 1;
    // The category that these items fall under
    AdapterCategory category = 2;
    // A descriptive name of the types of items that are returned by this
    // adapter e.g. "EKS Cluster"
    string descriptiveName = 3;
}

message ListAvailableItemTypesRequest {}

message ListAvailableItemTypesResponse {
    repeated AvailableItemType types = 1;
}