syntax = "proto3";

package hipcheck.v1;

service PluginService {
    /**
    * Get schemas for all supported queries by the plugin.
    *
    * This is used by Hipcheck to validate that:
    *
    * - The plugin supports a default query taking a `target` type if used
    *   as a top-level plugin in the user's policy file.
    * - That requests sent to the plugin and data returned by the plugin
    *   match the schema during execution.
    */
    rpc GetQuerySchemas (GetQuerySchemasRequest)
        returns (stream GetQuerySchemasResponse);

    /**
     * Hipcheck sends all child nodes for the plugin from the user's policy
     * file to configure the plugin.
     */
    rpc SetConfiguration (SetConfigurationRequest)
        returns (SetConfigurationResponse);

    /**
     * Get the default policy for a plugin, which may additionally depend on
     * the plugin's configuration.
     */
    rpc GetDefaultPolicyExpression (GetDefaultPolicyExpressionRequest)
        returns (GetDefaultPolicyExpressionResponse);

    /**
     * Get an explanation of what the default query returns, to use when
     * reporting analysis results to users.
     *
     * Note that, because users can specify their own policy expression, this
     * explanation *should not* assume the user has used the default policy
     * expression, if one is provided by the plugin.
     */
    rpc ExplainDefaultQuery (ExplainDefaultQueryRequest)
        returns (ExplainDefaultQueryResponse);

    /**
     * Open a bidirectional streaming RPC to enable a request/response
     * protocol between Hipcheck and a plugin, where Hipcheck can issue
     * queries to the plugin, and the plugin may issue queries to _other_
     * plugins through Hipcheck.
     *
     * Queries are cached by the publisher name, plugin name, query name,
     * and key, and if a match is found for those four values, then
     * Hipcheck will respond with the cached result of that prior matching
     * query rather than running the query again.
     */
    rpc InitiateQueryProtocol (stream InitiateQueryProtocolRequest)
        returns (stream InitiateQueryProtocolResponse);
}

/*===========================================================================
 * GetQuerySchemas RPC Types
 */

message GetQuerySchemasRequest {
    Empty empty = 1;
}

message GetQuerySchemasResponse {
    // The name of the query being described by the schemas provided.
    //
    // If either the key and/or output schemas result in a message which is
    // too big, they may be chunked across multiple replies in the stream.
    // Replies with matching query names should have their fields concatenated
    // in the order received to reconstruct the chunks.
    string query_name = 1;

    // The key schema, in JSON Schema format.
    string key_schema = 2;

    // The output schema, in JSON Schema format.
    string output_schema = 3;
}

/*===========================================================================
 * SetConfiguration RPC Types
 */

message SetConfigurationRequest {
    // JSON string containing configuration data expected by the plugin,
    // pulled from the user's policy file.
    string configuration = 1;
}

message SetConfigurationResponse {
    // The status of the configuration call.
    ConfigurationStatus status = 1;
    // An optional error message, if there was an error.
    string message = 2;
}

enum ConfigurationStatus {
    // An unknown error occured.
    CONFIGURATION_STATUS_UNSPECIFIED = 0;
    // No error; the operation was successful.
    CONFIGURATION_STATUS_NONE = 1;
    // The user failed to provide a required configuration item.
    CONFIGURATION_STATUS_MISSING_REQUIRED_CONFIGURATION = 2;
    // The user provided a configuration item whose name was not recognized.
    CONFIGURATION_STATUS_UNRECOGNIZED_CONFIGURATION = 3;
    // The user provided a configuration item whose value is invalid.
    CONFIGURATION_STATUS_INVALID_CONFIGURATION_VALUE = 4;
}

/*===========================================================================
 * GetDefaultPolicyExpression RPC Types
 */

message GetDefaultPolicyExpressionRequest {
    Empty empty = 1;
}

message GetDefaultPolicyExpressionResponse {
    // A policy expression, if the plugin has a default policy.
    // This MUST be filled in with any default values pulled from the plugin's
    // configuration. Hipcheck will only request the default policy _after_
    // configuring the plugin.
    string policy_expression = 1;
}

/*===========================================================================
 * ExplainDefaultQuery RPC Types
 */

message ExplainDefaultQueryRequest {
    Empty empty = 1;
}

message ExplainDefaultQueryResponse {
    string explanation = 1;
}

/*===========================================================================
 * Query Protocol RPC Types
 */

message InitiateQueryProtocolRequest {
    Query query = 1;
}

message InitiateQueryProtocolResponse {
    Query query = 1;
}

message Query {
    // The ID of the request, used to associate requests and replies.
    // Odd numbers = initiated by `hc`.
    // Even numbers = initiated by a plugin.
    int32 id = 1;

    // The state of the query, indicating if this is a request or a reply,
    // and if it's a reply whether it's the end of the reply.
    QueryState state = 2;

    // Publisher name and plugin name, when sent from Hipcheck to a plugin
    // to initiate a fresh query, are used by the receiving plugin to validate
    // that the query was intended for them.
    //
    // When a plugin is making a query to another plugin through Hipcheck, it's
    // used to indicate the destination plugin, and to indicate the plugin that
    // is replying when Hipcheck sends back the reply.
    string publisher_name = 3;
    string plugin_name = 4;

    // The name of the query being made, so the responding plugin knows what
    // to do with the provided data.
    string query_name = 5;

    // The key for the query, as a JSON object. This is the data that Hipcheck's
    // incremental computation system will use to cache the response.
    string key = 6;

    // The response for the query, as a JSON object. This will be cached by
    // Hipcheck for future queries matching the publisher name, plugin name,
    // query name, and key.
    string output = 7;

	// An unstructured concern raised during the query that will be raised
	// in the final Hipcheck report.
	repeated string concern = 8;
}

enum QueryState {
    // Something has gone wrong.
    QUERY_STATE_UNSPECIFIED = 0;

    // We are submitting a new query.
    QUERY_STATE_SUBMIT = 1;

    // We are replying to a query and expect more chunks.
    QUERY_STATE_REPLY_IN_PROGRESS = 2;

    // We are closing a reply to a query. If a query response is in one chunk,
    // just send this. If a query is in more than one chunk, send this with
    // the last message in the reply. This tells the receiver that all chunks
    // have been received.
    QUERY_STATE_REPLY_COMPLETE = 3;
}

/*===========================================================================
 * Helper Types
 */

message Empty {}