backend

type ActivityExecutor interface {
	ExecuteActivity(ctx context.Context, iid api.InstanceID, e *protos.HistoryEvent, opts ExecuteOptions) (*protos.HistoryEvent, error)
}

type ActivityRequest = protos.ActivityRequest

type ActivityWorkItem struct {
	SequenceNumber int64
	InstanceID     api.InstanceID
	NewEvent       *HistoryEvent
	Result         *HistoryEvent
	LockedBy       string
	Properties     map[string]interface{}
	// receive from caller
	IncomingHistory *protos.PropagatedHistory
}

type Backend interface {
	// CreateTaskHub creates a new task hub for the current backend. Task hub creation must be idempotent.
	//
	// If the task hub for this backend already exists, an error of type [ErrTaskHubExists] is returned.
	CreateTaskHub(context.Context) error

	// DeleteTaskHub deletes an existing task hub configured for the current backend. It's up to the backend
	// implementation to determine how the task hub data is deleted.
	//
	// If the task hub for this backend doesn't exist, an error of type [ErrTaskHubNotFound] is returned.
	DeleteTaskHub(context.Context) error

	// Start starts any background processing done by this backend.
	Start(context.Context) error

	// Stop stops any background processing done by this backend.
	Stop(context.Context) error

	// CreateWorkflowInstance creates a new workflow instance with a request that
	// wraps an ExecutionStarted history event.
	CreateWorkflowInstance(context.Context, *CreateWorkflowInstanceRequest) error

	// AddNewEvent adds a new workflow event to the specified workflow instance.
	AddNewWorkflowEvent(context.Context, api.InstanceID, *HistoryEvent) error

	// NextWorkflowWorkItem blocks and returns the next workflow work
	// item from the task hub. Should only return an error when shutting down.
	NextWorkflowWorkItem(context.Context) (*WorkflowWorkItem, error)

	// GetWorkflowRuntimeState gets the runtime state of a workflow instance.
	GetWorkflowRuntimeState(context.Context, *WorkflowWorkItem) (*WorkflowRuntimeState, error)

	// WatchWorkflowRuntimeStatus is a streaming API to watch for changes to
	// the OrchestrtionMetadata, receiving events as and when the state changes.
	// When the given condition is true, returns.
	// Used over polling the metadata.
	// A nil router or one whose TargetAppID is empty or the local app watches
	// the local instance. A foreign TargetAppID delegates the watch to the
	// owning app; backends without cross-app support return an error.
	WatchWorkflowRuntimeStatus(ctx context.Context, id api.InstanceID, router *protos.TaskRouter, condition func(*WorkflowMetadata) bool) error

	// GetWorkflowMetadata gets the metadata associated with the given workflow instance ID.
	// A nil router or one whose TargetAppID is empty or the local app reads the
	// local instance. A foreign TargetAppID delegates the read to the owning
	// app; backends without cross-app support return an error.
	//
	// Returns [api.ErrInstanceNotFound] if the workflow instance doesn't exist.
	GetWorkflowMetadata(ctx context.Context, id api.InstanceID, router *protos.TaskRouter) (*WorkflowMetadata, error)

	// CompleteWorkflowWorkItem completes a work item by saving the updated runtime state to durable storage.
	//
	// Returns [ErrWorkItemLockLost] if the work-item couldn't be completed due to a lock-lost conflict (e.g., split-brain).
	CompleteWorkflowWorkItem(context.Context, *WorkflowWorkItem) error

	// AbandonWorkflowWorkItem undoes any state changes and returns the work item to the work item queue.
	//
	// This is called if an internal failure happens in the processing of a workflow work item. It is
	// not called if the workflow work item is processed successfully (note that a workflow that
	// completes with a failure is still considered a successfully processed work item).
	AbandonWorkflowWorkItem(context.Context, *WorkflowWorkItem) error

	// NextActivityWorkItem blocks and returns the next activity work item from
	// the task hub. Should only return an error when shutting down.
	NextActivityWorkItem(context.Context) (*ActivityWorkItem, error)

	// CompleteActivityWorkItem sends a message to the parent workflow indicating activity completion.
	//
	// Returns [ErrWorkItemLockLost] if the work-item couldn't be completed due to a lock-lost conflict (e.g., split-brain).
	CompleteActivityWorkItem(context.Context, *ActivityWorkItem) error

	// AbandonActivityWorkItem returns the work-item back to the queue without committing any other chances.
	//
	// This is called when an internal failure occurs during activity work-item processing.
	AbandonActivityWorkItem(context.Context, *ActivityWorkItem) error

	// PurgeWorkflowState deletes saved workflow state. When router is nil or
	// targets the local app, this is a single-instance purge of id (recursive
	// is ignored, the driver walks children itself) and the returned count is 1
	// on success. When router carries a foreign TargetAppID the backend is
	// expected to delegate the purge to the target app and return the number of
	// instances purged on the remote side: recursively for the whole subtree
	// when recursive is true (always the case for cross-app children reached by
	// the recursive purge driver), or just the single instance otherwise.
	// [api.ErrInstanceNotFound] is returned if the specified workflow instance doesn't exist.
	// [api.ErrNotCompleted] is returned if the specified workflow instance is still running.
	PurgeWorkflowState(ctx context.Context, id api.InstanceID, router *protos.TaskRouter, recursive bool, force bool) (int, error)

	// CompleteWorkflowTask completes the workflow task by saving the updated runtime state to durable storage.
	CompleteWorkflowTask(context.Context, *protos.WorkflowResponse) error

	// CancelWorkflowTask cancels the workflow task so instances of WaitForWorkflowTaskCompletion will return an error.
	CancelWorkflowTask(context.Context, api.InstanceID) error

	// WaitForWorkflowTaskCompletion blocks until the workflow completes and returns the final response.
	//
	// [api.ErrTaskCancelled] is returned if the task was cancelled.
	WaitForWorkflowTaskCompletion(*protos.WorkflowRequest) func(context.Context) (*protos.WorkflowResponse, error)

	// CompleteActivityTask completes the activity task by saving the updated runtime state to durable storage.
	CompleteActivityTask(context.Context, *protos.ActivityResponse) error

	// CancelActivityTask cancels the activity task so instances of WaitForActivityCompletion will return an error.
	CancelActivityTask(context.Context, api.InstanceID, int32) error

	// WaitForActivityCompletion blocks until the activity completes and returns the final response.
	//
	// [api.ErrTaskCancelled] is returned if the task was cancelled.
	WaitForActivityCompletion(*protos.ActivityRequest) func(context.Context) (*protos.ActivityResponse, error)

	// ListInstanceIDs lists workflow instance IDs based on the provided
	// query parameters.
	ListInstanceIDs(ctx context.Context, req *protos.ListInstanceIDsRequest) (*protos.ListInstanceIDsResponse, error)

	// GetInstanceHistory returns the full current history of a workflow instance.
	GetInstanceHistory(ctx context.Context, req *protos.GetInstanceHistoryRequest) (*protos.GetInstanceHistoryResponse, error)
}

type BackendWorkflowStateMetadata = protos.BackendWorkflowStateMetadata

type CreateWorkflowInstanceRequest = protos.CreateWorkflowInstanceRequest

type DurableTimer = protos.DurableTimer

type ExecuteOptions struct {
	PropagatedHistory *protos.PropagatedHistory
}

type Executor interface {
	ExecuteWorkflow(ctx context.Context, iid api.InstanceID, oldEvents []*protos.HistoryEvent, newEvents []*protos.HistoryEvent, opts ExecuteOptions) (*protos.WorkflowResponse, error)
	ExecuteActivity(ctx context.Context, iid api.InstanceID, e *protos.HistoryEvent, opts ExecuteOptions) (*protos.HistoryEvent, error)
	Shutdown(ctx context.Context) error
}

type GetInstanceHistoryRequest = protos.GetInstanceHistoryRequest

type GetInstanceHistoryResponse = protos.GetInstanceHistoryResponse

type HistoryEvent = protos.HistoryEvent

type ListInstanceIDsRequest = protos.ListInstanceIDsRequest

type ListInstanceIDsResponse = protos.ListInstanceIDsResponse

type Logger interface {
	// Debug logs a message at level Debug.
	Debug(v ...any)
	// Debugf logs a message at level Debug.
	Debugf(format string, v ...any)
	// Info logs a message at level Info.
	Info(v ...any)
	// Infof logs a message at level Info.
	Infof(format string, v ...any)
	// Warn logs a message at level Warn.
	Warn(v ...any)
	// Warnf logs a message at level Warn.
	Warnf(format string, v ...any)
	// Error logs a message at level Error.
	Error(v ...any)
	// Errorf logs a message at level Error.
	Errorf(format string, v ...any)
}

type NewTaskWorkerOptions func(*WorkerOptions)

type OrchestrationStatus = protos.OrchestrationStatus

type TaskFailureDetails = protos.TaskFailureDetails

type TaskHubClient interface {
	ScheduleNewWorkflow(ctx context.Context, workflow interface{}, opts ...api.NewWorkflowOptions) (api.InstanceID, error)
	FetchWorkflowMetadata(ctx context.Context, id api.InstanceID, opts ...api.FetchWorkflowMetadataOptions) (*WorkflowMetadata, error)
	WaitForWorkflowStart(ctx context.Context, id api.InstanceID, opts ...api.FetchWorkflowMetadataOptions) (*WorkflowMetadata, error)
	WaitForWorkflowCompletion(ctx context.Context, id api.InstanceID, opts ...api.FetchWorkflowMetadataOptions) (*WorkflowMetadata, error)
	TerminateWorkflow(ctx context.Context, id api.InstanceID, opts ...api.TerminateOptions) error
	RaiseEvent(ctx context.Context, id api.InstanceID, eventName string, opts ...api.RaiseEventOptions) error
	SuspendWorkflow(ctx context.Context, id api.InstanceID, reason string, opts ...api.SuspendOptions) error
	ResumeWorkflow(ctx context.Context, id api.InstanceID, reason string, opts ...api.ResumeOptions) error
	PurgeWorkflowState(ctx context.Context, id api.InstanceID, opts ...api.PurgeOptions) error
}

type TaskHubWorker interface {
	// Start starts the backend and the configured internal workers.
	Start(context.Context) error

	// Shutdown stops the backend and all internal workers.
	Shutdown(context.Context) error
}

type TaskProcessor[T WorkItem] interface {
	Name() string
	ProcessWorkItem(context.Context, T) error
	NextWorkItem(context.Context) (T, error)
	AbandonWorkItem(context.Context, T) error
	CompleteWorkItem(context.Context, T) error
}

type TaskWorker[T WorkItem] interface {
	// Start starts background polling for the activity work items.
	Start(context.Context)

	// StopAndDrain stops the worker and waits for outstanding work items until
	// the context expires.
	StopAndDrain(context.Context) error
}

type WorkItem interface {
	fmt.Stringer
	IsWorkItem() bool
}

type WorkerOptions struct {
	MaxParallelWorkItems *int32
}

type WorkflowExecutor interface {
	ExecuteWorkflow(
		ctx context.Context,
		iid api.InstanceID,
		oldEvents []*protos.HistoryEvent,
		newEvents []*protos.HistoryEvent,
		opts ExecuteOptions) (*protos.WorkflowResponse, error)
}

type WorkflowMetadata = protos.WorkflowMetadata

type WorkflowRuntimeState = protos.WorkflowRuntimeState

type WorkflowRuntimeStateMessage = protos.WorkflowRuntimeStateMessage

type WorkflowState = protos.WorkflowState

type WorkflowWorkItem struct {
	InstanceID api.InstanceID
	NewEvents  []*HistoryEvent
	LockedBy   string
	RetryCount int32
	State      *protos.WorkflowRuntimeState
	Properties map[string]interface{}
	// receive from caller
	IncomingHistory *protos.PropagatedHistory
	// sent to each activity (child wf use state.PendingMessages)
	OutgoingHistory map[int32]*protos.PropagatedHistory
}

type WorkflowWorkerOptions struct {
	Backend   Backend
	Executor  WorkflowExecutor
	Logger    Logger
	AppID     string
	Namespace string
	// InProcessExecutor is used to dispatch work items whose workflow name has
	// InProcessNamePrefix as a prefix. This is how internal dapr-side workflows
	// (e.g. dapr.internal.mcp.*) run inside the sidecar instead of being shipped
	// to an external SDK via the gRPC work-item stream.
	InProcessExecutor WorkflowExecutor
	// InProcessNamePrefix is the workflow-name prefix that selects InProcessExecutor.
	// Empty string disables prefix-based dispatch.
	InProcessNamePrefix string
}