// Copyright (c) 2019 Temporal Technologies, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.

syntax = "proto3";

package temporal.server.api.historyservice.v1;
option go_package = "go.temporal.io/server/api/historyservice/v1;historyservice";

import "temporal/server/api/historyservice/v1/request_response.proto";

// HistoryService provides API to start a new long running workflow instance, as well as query and update the history
// of workflow instances already created.
service HistoryService {

    // StartWorkflowExecution starts a new long running workflow instance.  It will create the instance with
    // 'WorkflowExecutionStarted' event in history and also schedule the first WorkflowTask for the worker to produce the
    // initial list of commands for this instance.  It will return 'WorkflowExecutionAlreadyStartedError', if an instance already
    // exists with same workflowId.
    rpc StartWorkflowExecution (StartWorkflowExecutionRequest) returns (StartWorkflowExecutionResponse) {
    }

    // Returns the information from mutable state of workflow execution.
    // It fails with 'EntityNotExistError' if specified workflow execution in unknown to the service.
    // It returns CurrentBranchChangedError if the workflow version branch has changed.
    rpc GetMutableState (GetMutableStateRequest) returns (GetMutableStateResponse) {
    }

    // Returns the information from mutable state of workflow execution.
    // It fails with 'EntityNotExistError' if specified workflow execution in unknown to the service.
    // It returns CurrentBranchChangedError if the workflow version branch has changed.
    rpc PollMutableState (PollMutableStateRequest) returns (PollMutableStateResponse) {
    }

    // Reset the sticky task queue related information in mutable state of a given workflow.
    // Things cleared are:
    // 1. StickyTaskQueue
    // 2. StickyScheduleToStartTimeout
    rpc ResetStickyTaskQueue (ResetStickyTaskQueueRequest) returns (ResetStickyTaskQueueResponse) {
    }

    // RecordWorkflowTaskStarted is called by the Matchingservice before it hands a workflow task to the application worker in response to
    // a PollWorkflowTaskQueue call. It records in the history the event that the workflow task has started. It will return 'TaskAlreadyStartedError',
    // if the workflow's execution history already includes a record of the event starting.
    rpc RecordWorkflowTaskStarted (RecordWorkflowTaskStartedRequest) returns (RecordWorkflowTaskStartedResponse) {
    }

    // RecordActivityTaskStarted is called by the Matchingservice before it hands a workflow task to the application worker in response to
    // a PollActivityTaskQueue call. It records in the history the event that the workflow task has started. It will return 'TaskAlreadyStartedError',
    // if the workflow's execution history already includes a record of the event starting.
    rpc RecordActivityTaskStarted (RecordActivityTaskStartedRequest) returns (RecordActivityTaskStartedResponse) {
    }

    // RespondWorkflowTaskCompleted is called by application worker to complete a WorkflowTask handed as a result of
    // 'PollWorkflowTaskQueue' API call.  Completing a WorkflowTask will result in new result in new commands for the
    // workflow execution and potentially new ActivityTasks created for correspondent commands. It will also create a
    // WorkflowTaskCompleted event in the history for that session.  Use the 'taskToken' provided as response of
    // PollWorkflowTaskQueue API call for completing the WorkflowTask.
    rpc RespondWorkflowTaskCompleted (RespondWorkflowTaskCompletedRequest) returns (RespondWorkflowTaskCompletedResponse) {
    }

    // RespondWorkflowTaskFailed is called by application worker to indicate failure.  This results in
    // WorkflowTaskFailedEvent written to the history and a new WorkflowTask created.  This API can be used by client to
    // either clear sticky task queue or report ny panics during WorkflowTask processing.
    rpc RespondWorkflowTaskFailed (RespondWorkflowTaskFailedRequest) returns (RespondWorkflowTaskFailedResponse) {
    }

    // RecordActivityTaskHeartbeat is called by application worker while it is processing an ActivityTask.  If worker fails
    // to heartbeat within 'heartbeatTimeoutSeconds' interval for the ActivityTask, then it will be marked as timedout and
    // 'ActivityTaskTimedOut' event will be written to the workflow history.  Calling 'RecordActivityTaskHeartbeat' will
    // fail with 'EntityNotExistsError' in such situations.  Use the 'taskToken' provided as response of
    // PollActivityTaskQueue API call for heartbeating.
    rpc RecordActivityTaskHeartbeat (RecordActivityTaskHeartbeatRequest) returns (RecordActivityTaskHeartbeatResponse) {
    }

    // RespondActivityTaskCompleted is called by application worker when it is done processing an ActivityTask.  It will
    // result in a new 'ActivityTaskCompleted' event being written to the workflow history and a new WorkflowTask
    // created for the workflow so new commands could be made.  Use the 'taskToken' provided as response of
    // PollActivityTaskQueue API call for completion. It fails with 'EntityNotExistsError' if the taskToken is not valid
    // anymore due to activity timeout.
    rpc RespondActivityTaskCompleted (RespondActivityTaskCompletedRequest) returns (RespondActivityTaskCompletedResponse) {
    }

    // RespondActivityTaskFailed is called by application worker when it is done processing an ActivityTask.  It will
    // result in a new 'ActivityTaskFailed' event being written to the workflow history and a new WorkflowTask
    // created for the workflow instance so new commands could be made.  Use the 'taskToken' provided as response of
    // PollActivityTaskQueue API call for completion. It fails with 'EntityNotExistsError' if the taskToken is not valid
    // anymore due to activity timeout.
    rpc RespondActivityTaskFailed (RespondActivityTaskFailedRequest) returns (RespondActivityTaskFailedResponse) {
    }

    // RespondActivityTaskCanceled is called by application worker when it is successfully canceled an ActivityTask.  It will
    // result in a new 'ActivityTaskCanceled' event being written to the workflow history and a new WorkflowTask
    // created for the workflow instance so new commands could be made.  Use the 'taskToken' provided as response of
    // PollActivityTaskQueue API call for completion. It fails with 'EntityNotExistsError' if the taskToken is not valid
    // anymore due to activity timeout.
    rpc RespondActivityTaskCanceled (RespondActivityTaskCanceledRequest) returns (RespondActivityTaskCanceledResponse) {
    }

    // SignalWorkflowExecution is used to send a signal event to running workflow execution.  This results in
    // WorkflowExecutionSignaled event recorded in the history and a workflow task being created for the execution.
    rpc SignalWorkflowExecution (SignalWorkflowExecutionRequest) returns (SignalWorkflowExecutionResponse) {
    }

    // (-- api-linter: core::0136::prepositions=disabled
    //     aip.dev/not-precedent: "With" is needed here. --)
    // SignalWithStartWorkflowExecution is used to ensure sending a signal event to a workflow execution.
    // If workflow is running, this results in WorkflowExecutionSignaled event recorded in the history
    // and a workflow task being created for the execution.
    // If workflow is not running or not found, it will first try start workflow with given WorkflowIdResuePolicy,
    // and record WorkflowExecutionStarted and WorkflowExecutionSignaled event in case of success.
    // It will return `WorkflowExecutionAlreadyStartedError` if start workflow failed with given policy.
    rpc SignalWithStartWorkflowExecution (SignalWithStartWorkflowExecutionRequest) returns (SignalWithStartWorkflowExecutionResponse) {
    }

    // RemoveSignalMutableState is used to remove a signal request Id that was previously recorded.  This is currently
    // used to clean execution info when signal workflow task finished.
    rpc RemoveSignalMutableState (RemoveSignalMutableStateRequest) returns (RemoveSignalMutableStateResponse) {
    }

    // TerminateWorkflowExecution terminates an existing workflow execution by recording WorkflowExecutionTerminated event
    // in the history and immediately terminating the execution instance.
    rpc TerminateWorkflowExecution (TerminateWorkflowExecutionRequest) returns (TerminateWorkflowExecutionResponse) {
    }

    // ResetWorkflowExecution reset an existing workflow execution by a firstEventId of a existing event batch
    // in the history and immediately terminating the current execution instance.
    // After reset, the history will grow from nextFirstEventId.
    rpc ResetWorkflowExecution (ResetWorkflowExecutionRequest) returns (ResetWorkflowExecutionResponse) {
    }

    // RequestCancelWorkflowExecution is called by application worker when it wants to request cancellation of a workflow instance.
    // It will result in a new 'WorkflowExecutionCancelRequested' event being written to the workflow history and a new WorkflowTask
    // created for the workflow instance so new commands could be made. It fails with 'EntityNotExistsError' if the workflow is not valid
    // anymore due to completion or doesn't exist.
    rpc RequestCancelWorkflowExecution (RequestCancelWorkflowExecutionRequest) returns (RequestCancelWorkflowExecutionResponse) {
    }

    // ScheduleWorkflowTask is used for creating a workflow task for already started workflow execution.  This is mainly
    // used by transfer queue processor during the processing of StartChildWorkflowExecution task, where it first starts
    // child execution without creating the workflow task and then calls this API after updating the mutable state of
    // parent execution.
    rpc ScheduleWorkflowTask (ScheduleWorkflowTaskRequest) returns (ScheduleWorkflowTaskResponse) {
    }

    // RecordChildExecutionCompleted is used for reporting the completion of child workflow execution to parent.
    // This is mainly called by transfer queue processor during the processing of DeleteExecution task.
    rpc RecordChildExecutionCompleted (RecordChildExecutionCompletedRequest) returns (RecordChildExecutionCompletedResponse) {
    }

    // DescribeWorkflowExecution returns information about the specified workflow execution.
    rpc DescribeWorkflowExecution (DescribeWorkflowExecutionRequest) returns (DescribeWorkflowExecutionResponse) {
    }

    rpc ReplicateEventsV2 (ReplicateEventsV2Request) returns (ReplicateEventsV2Response) {
    }

    // SyncShardStatus sync the status between shards.
    rpc SyncShardStatus (SyncShardStatusRequest) returns (SyncShardStatusResponse) {
    }

    // SyncActivity sync the activity status.
    rpc SyncActivity (SyncActivityRequest) returns (SyncActivityResponse) {
    }

    // DescribeMutableState returns information about the internal states of workflow mutable state.
    rpc DescribeMutableState (DescribeMutableStateRequest) returns (DescribeMutableStateResponse) {
    }

    // DescribeHistoryHost returns information about the internal states of a history host.
    rpc DescribeHistoryHost (DescribeHistoryHostRequest) returns (DescribeHistoryHostResponse) {
    }

    // CloseShard close the shard.
    rpc CloseShard (CloseShardRequest) returns (CloseShardResponse) {
    }

    // RemoveTask remove task based on type, taskid, shardid.
    rpc RemoveTask (RemoveTaskRequest) returns (RemoveTaskResponse) {
    }

    // GetReplicationMessages return replication messages based on the read level
    rpc GetReplicationMessages (GetReplicationMessagesRequest) returns (GetReplicationMessagesResponse) {
    }

    // GetDLQReplicationMessages return replication messages based on dlq info
    rpc GetDLQReplicationMessages(GetDLQReplicationMessagesRequest) returns(GetDLQReplicationMessagesResponse){
    }

    // QueryWorkflow returns query result for a specified workflow execution.
    rpc QueryWorkflow (QueryWorkflowRequest) returns (QueryWorkflowResponse) {
    }

    // ReapplyEvents applies stale events to the current workflow and current run.
    rpc ReapplyEvents (ReapplyEventsRequest) returns (ReapplyEventsResponse) {
    }

    // GetDLQMessages returns messages from DLQ.
    rpc GetDLQMessages(GetDLQMessagesRequest) returns (GetDLQMessagesResponse) {
    }

    // (-- api-linter: core::0165::response-message-name=disabled
    //     aip.dev/not-precedent:  --)
    // PurgeDLQMessages purges messages from DLQ.
    rpc PurgeDLQMessages(PurgeDLQMessagesRequest) returns (PurgeDLQMessagesResponse) {
    }

    // MergeDLQMessages merges messages from DLQ.
    rpc MergeDLQMessages(MergeDLQMessagesRequest) returns (MergeDLQMessagesResponse) {
    }

    // RefreshWorkflowTasks refreshes all tasks of a workflow.
    rpc RefreshWorkflowTasks(RefreshWorkflowTasksRequest) returns (RefreshWorkflowTasksResponse) {
    }
}
