syntax = "proto3";
package io.axoniq.axonserver.grpc.command;
import "common.proto";
option java_multiple_files = true;

/* The CommandService defines the gRPC requests necessary for subscribing command handlers, and dispatching commands. */
service CommandService {

    /* Opens a stream allowing clients to register command handlers and receive commands. */
    rpc OpenStream (stream CommandProviderOutbound) returns (stream CommandProviderInbound) {
    }

    /* Dispatches the given command, returning the result of command execution */
    rpc Dispatch (Command) returns (CommandResponse) {
    }
}

/* An instruction from the components that provides the Command Handler towards AxonServer. */
message CommandProviderOutbound {

    /* The instruction for AxonServer */
    oneof request {

        /* Instruction to subscribe this component as handler of a specific type of command */
        CommandSubscription subscribe = 1;

        /* Instruction to unsubscribe this component as handler of a specific type of command */
        CommandSubscription unsubscribe = 2;

        /* Instruction to increase the number of instructions AxonServer may send to this component */
        common.FlowControl flow_control = 3;

        /* Sends a result of Command processing */
        CommandResponse command_response = 4;

        /* Acknowledgement of previously sent instruction via inbound stream */
        common.InstructionAck ack = 5;
    }

    /* Instruction identifier. If this identifier is set, this instruction will be acknowledged via inbound stream */
    string instruction_id = 6;
}

/* An instruction or confirmation from AxonServer towards the component that provides the Command Handler */
message CommandProviderInbound {
    /* The instruction from AxonServer for this component */
    oneof request {

        /* Acknowledgement of previously sent instruction via outbound stream */
        common.InstructionAck ack = 1;

        /* A command for this component to process */
        Command command = 2;
    }

    /* Instruction identifier. If this identifier is set, this instruction will be acknowledged via outbound stream */
    string instruction_id = 3;
}

/* A message representing a Command that needs to be routed to a component capable of handling it */
message Command {

    /* The unique identifier of the Command Message */
    string message_identifier = 1;

    /* The name of the command, used for routing it to a destination capable of handling it */
    string name = 2;

    /* The time at which the command was dispatched */
    int64 timestamp = 3;

    /* The payload of the Command, providing details on the instructions for the recipient */
    common.SerializedObject payload = 4;

    /* Meta Data entries of the Command Message, providing contextual information to the recipient */
    map<string, common.MetaDataValue> meta_data = 5;

    /* Instructions for AxonServer when routing this Command Message */
    repeated common.ProcessingInstruction processing_instructions = 6;

    /* The unique identifier of the component dispatching this message */
    string client_id = 7;

    /* The name/type of the component dispatching this message */
    string component_name = 8;
}

/* Message representing the result of Command Handler execution */
message CommandResponse {

    /* The unique identifier of the response message */
    string message_identifier = 1;

    /* An error code describing the error, if any */
    string error_code = 2;

    /* A detailed description of the error */
    common.ErrorMessage error_message = 3;

    /* The payload to provide as a result to the dispatcher */
    common.SerializedObject payload = 4;

    /* Any meta data entries providing contextual information back to the dispatcher */
    map<string, common.MetaDataValue> meta_data = 5;

    /* Instructions for AxonServer when routing this Command Response Message */
    repeated common.ProcessingInstruction processing_instructions = 6;

    /* The unique identifier of the Command Message for which this is the response */
    string request_identifier = 7;
}

/* Message describing a component's capability of handling a command type */
message CommandSubscription {
    /* A unique identifier for this subscription. This identifier is returned in Acknowledgements to allow
    pipelining of subscription messages */
    string message_id = 1;

    /* The name of the command the component can handle */
    string command = 2;

    /* The name/type of the component handling the command */
    string component_name = 3;

    /* The unique identifier of the component instance subscribing */
    string client_id = 4;

    /* A number that represents the client's relative load capacity compared to other clients.
       This information is interpreted by Axon Server in relation to the other connected nodes' values.
       Used to balance the dispatching of commands. If set to 0, Axon Server consider 100 as default value.*/
    int32 load_factor = 5;
}