task

type Client interface {
	/*
		DefineAndRunImmediateOneShotTask define and submit an immediate one-shot class task.

		The task entry is defined in a database transaction, then submitted to the scheduler for
		execution. The submit happens after the entry is persisted and is not part of that
		transaction. On error, inspect the returned error with `errors.As`: a
		`models.PersistenceError` means the database operation failed and no task was created; a
		`models.IPCMessageQueueError` means the task was created but could not be submitted to the
		scheduler.

			@param ctx context.Context - execution context
			@param params DefineTaskParams - the task definition parameters
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the newly defined task entry
	*/
	DefineAndRunImmediateOneShotTask(
		ctx context.Context,
		params DefineTaskParams,
		activeDBClient db.Database,
	) (models.Task, error)

	/*
		DefineAndRunScheduledOneShotTask define and submit a scheduled one-shot class task.

		The task entry is defined in a database transaction, then submitted to the scheduler for
		execution. The submit happens after the entry is persisted and is not part of that
		transaction. On error, inspect the returned error with `errors.As`: a
		`models.PersistenceError` means the database operation failed and no task was created; a
		`models.IPCMessageQueueError` means the task was created but could not be submitted to the
		scheduler.

			@param ctx context.Context - execution context
			@param params DefineTaskParams - the task definition parameters
			@param targetRuntime time.Time - target time when the task should run
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the newly defined task entry
	*/
	DefineAndRunScheduledOneShotTask(
		ctx context.Context,
		params DefineTaskParams,
		targetRuntime time.Time,
		activeDBClient db.Database,
	) (models.Task, error)

	/*
		DefineImmediateOneShotTask define (but do NOT submit) an immediate one-shot class task.

		This is the define-only half of DefineAndRunImmediateOneShotTask: it persists the task
		entry and returns it, without poking the scheduler. The caller is responsible for calling
		SubmitTask afterwards to actually dispatch it. This split lets a caller commit its own
		additional state between the define and the submit - e.g. the workflow scheduler links the
		step to this task and marks the step RUNNING in the same transaction, then submits only
		after that commits (state-before-poke). On error the returned error `errors.As` a
		`models.PersistenceError`: the DB define failed and no task was created.

			@param ctx context.Context - execution context
			@param params DefineTaskParams - the task definition parameters
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the newly defined task entry
	*/
	DefineImmediateOneShotTask(
		ctx context.Context,
		params DefineTaskParams,
		activeDBClient db.Database,
	) (models.Task, error)

	/*
		DefineScheduledOneShotTask define (but do NOT submit) a scheduled one-shot class task.

		The define-only half of DefineAndRunScheduledOneShotTask; see DefineImmediateOneShotTask
		for the define/submit split rationale. On error the returned error `errors.As` a
		`models.PersistenceError`: the DB define failed and no task was created.

			@param ctx context.Context - execution context
			@param params DefineTaskParams - the task definition parameters
			@param targetRuntime time.Time - target time when the task should run
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the newly defined task entry
	*/
	DefineScheduledOneShotTask(
		ctx context.Context,
		params DefineTaskParams,
		targetRuntime time.Time,
		activeDBClient db.Database,
	) (models.Task, error)

	/*
		SubmitTask submit an already-defined task to the scheduler for execution.

		This is the submit-only half of the DefineAndRun* methods: it pokes the scheduler queue for
		a task whose entry has already been persisted (via DefineImmediateOneShotTask /
		DefineScheduledOneShotTask). It runs no database work. A failed submit `errors.As` a
		`models.IPCMessageQueueError`: the task entry still exists and the scheduler's own
		maintenance will eventually pick it up, so a caller following state-before-poke may treat a
		submit failure as a lost poke rather than a lost task.

			@param ctx context.Context - execution context
			@param taskID string - ID of the already-defined task to submit
	*/
	SubmitTask(ctx context.Context, taskID string) error

	/*
		CancelTask request scheduler cancel a task

		The task is read in a database transaction to confirm it exists and that this client's
		creator owns it (see the Client doc), then a cancel request is submitted to the scheduler.
		The submit happens after the read and is not part of that transaction. On error, inspect the
		returned error with `errors.As`: a `models.PersistenceError` means the task could not be
		read; a `goutils.NotFoundError` means the task does not exist or belongs to another creator;
		a `models.IPCMessageQueueError` means the cancel request could not be submitted to the
		scheduler.

			@param ctx context.Context - execution context
			@param taskID string - ID of task to cancel
			@param activeDBClient db.Database - an existing open data base transaction to continue in
	*/
	CancelTask(ctx context.Context, taskID string, activeDBClient db.Database) error

	/*
		ListTasks list tasks belonging to this client's creator.

		The query is creator-scoped (see the Client doc): when `filters.Creators` is empty it is
		filled in with the client's DefaultCreator; when the caller sets it explicitly that set is
		used verbatim. A client with neither a DefaultCreator nor an explicit `filters.Creators`
		has no scope to apply and the call is rejected with a `goutils.BadInputError` rather than
		silently listing every creator's tasks. A failed read `errors.As` a
		`models.PersistenceError`.

			@param ctx context.Context - execution context
			@param filters db.TaskQueryFilter - query filtering conditions
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the matching task entries
	*/
	ListTasks(
		ctx context.Context, filters db.TaskQueryFilter, activeDBClient db.Database,
	) ([]models.Task, error)

	/*
		GetTask fetch a task by ID.

		Creator-scoped (see the Client doc): a task belonging to another creator `errors.As` a
		`goutils.NotFoundError`, indistinguishable from a task which does not exist. Any other
		read failure `errors.As` a `models.PersistenceError`.

			@param ctx context.Context - execution context
			@param taskID string - task ID
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the task entry
	*/
	GetTask(ctx context.Context, taskID string, activeDBClient db.Database) (models.Task, error)

	/*
		DeleteTask delete a task and its execution history.

		Creator-scoped (see the Client doc). Only a terminal task (COMPLETE / FAILED / TIMED_OUT /
		CANCELLED) may be deleted; a live one must be cancelled first. A task executing a workflow
		step is refused outright - it is the workflow's execution history and leaves only with its
		workflow. Both refusals `errors.As` a `goutils.ConsistencyError`; a task belonging to
		another creator `errors.As` a `goutils.NotFoundError`.

			@param ctx context.Context - execution context
			@param taskID string - task ID
			@param activeDBClient db.Database - an existing open data base transaction to continue in
	*/
	DeleteTask(ctx context.Context, taskID string, activeDBClient db.Database) error

	/*
		ListTaskExecutions list the execution instances (attempts) of one task.

		The parent task is read first and creator-scoped (see the Client doc), so a task belonging
		to another creator `errors.As` a `goutils.NotFoundError` and no execution history is
		disclosed. `filters.ParentTaskID` is not consulted; the parent is the `taskID` argument.

			@param ctx context.Context - execution context
			@param taskID string - the parent task ID
			@param filters db.TaskExecutionQueryFilter - query filtering conditions
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the matching task execution instances
	*/
	ListTaskExecutions(
		ctx context.Context,
		taskID string,
		filters db.TaskExecutionQueryFilter,
		activeDBClient db.Database,
	) ([]models.TaskExecution, error)

	/*
		GetTaskExecution fetch a task execution instance by ID.

		The instance is read, then its parent task is read and creator-scoped (see the Client
		doc); an instance whose parent belongs to another creator `errors.As` a
		`goutils.NotFoundError`.

			@param ctx context.Context - execution context
			@param instanceID string - task execution instance ID
			@param activeDBClient db.Database - an existing open data base transaction to continue in
			@return the task execution instance entry
	*/
	GetTaskExecution(
		ctx context.Context, instanceID string, activeDBClient db.Database,
	) (models.TaskExecution, error)
}

type DefineTaskParams struct {
	// Name the task name. This is used to match the task with the appropriate task execution
	// processor to run the task.
	Name string `validate:"required"`
	// Parameters task processing parameters
	Parameters any
	// Metadata associated metadata
	Metadata any
	// Creator optional per-task creator override; nil uses the client's DefaultCreator. The
	// resolved value must be non-empty or the submit fails validation.
	Creator *string
	// Deadline if specified, the task must complete by this dead line.
	Deadline *time.Time
	// Retry optional per-task retry policy, carried in full (Factor included). When nil the client
	// resolves retry the usual way (the by-task-name policy from the client config, else the
	// default). When non-nil it is used verbatim, overriding both. This is the escape hatch for
	// callers whose retry policy is per-submission rather than a static property of the task name -
	// e.g. the workflow engine, where every step task shares the one name __EXECUTE_WORKFLOW_STEP__
	// but each step carries its own TaskRetryParameters.
	Retry *models.TaskRetryParameters
}

type ExecutionCompleteCallback func(
	ctx context.Context, instanceID string, err error, timestamp time.Time,
)

type Executor interface {
	/*
		ProcessExecutionInstance submit a new task execution instance for processing

			@param ctx context.Context - execution context
			@param instanceID string - execution instance ID
	*/
	ProcessExecutionInstance(ctx context.Context, instanceID string) error

	/*
		Stop the queue executor

			@param ctx context.Context - execution context
	*/
	Stop(ctx context.Context) error
}

type ExecutorFactoryCB func(
	parentCtx context.Context,
	taskQueue string,
	workerCount int,
	requestBufferLen int,
	support ExecutorSupport,
	processors map[string]models.TaskExecutionProcessor,
) (Executor, error)

type ExecutorSupport struct {
	// Persistence persistence client
	Persistence db.Client `validate:"required"`

	// OnCompleteCB completion callback
	OnCompleteCB ExecutionCompleteCallback `validate:"required"`
}

type IPCMsgReceiverFactoryCB func(
	ctx context.Context, queueName string, redis goutilsRedis.Client, reader string,
) (common.IPCMessageReceive, error)

type IPCMsgSenderFactoryCB func(
	ctx context.Context, queueName string, redis goutilsRedis.Client, sender string,
) (common.IPCMessageSend, error)

type NewClientParams struct {
	// Name of the client
	Name string `validate:"required"`
	// DefaultCreator opaque creator identity stamped on tasks submitted through this
	// client when the submit call does not provide a per-task override. tasking never
	// interprets it; it is the notification routing key (see notify/DESIGN.md).
	DefaultCreator string
	// Persistence persistence client
	Persistence db.Client `validate:"required"`
	// Config task client config
	Config models.TaskClientConfig `validate:"required"`
	// Redis REDIS client
	Redis goutilsRedis.Client `validate:"required"`
	// IPCSenderFactory factory function to define Redis based IPC message senders
	IPCSenderFactory IPCMsgSenderFactoryCB `validate:"required"`
}

type NewReceiverParams struct {
	// Persistence persistence client
	Persistence db.Client `validate:"required"`
	// Config task receiver config
	Config models.TaskReceiverConfig `validate:"required"`
	// ExecutorFactory factory function to define task executors
	ExecutorFactory ExecutorFactoryCB `validate:"required"`
	// Redis REDIS client
	Redis goutilsRedis.Client `validate:"required"`
	// IPCReceiverFactory factory function to define Redis based IPC message receivers
	IPCReceiverFactory IPCMsgReceiverFactoryCB `validate:"required"`
	// IPCSenderFactory factory function to define Redis based IPC message senders
	IPCSenderFactory IPCMsgSenderFactoryCB `validate:"required"`
	// OnFatal, when set, is invoked (at most once) when a queue-processing goroutine hits an
	// unrecoverable fault instead of terminating the process. reporter identifies the faulting
	// queue thread; err carries the cause (with code position in its chain); timestamp is when it
	// was detected. When nil, the default logs and calls log.Fatal, preserving prior behavior. The
	// goroutine exits after the callback runs.
	OnFatal models.OnFatalCB
}

type NewSchedulerParams struct {
	// Persistence persistence client
	Persistence db.Client `validate:"required"`
	// Config task scheduler config
	Config models.TaskSchedulerConfig `validate:"required"`
	// Redis REDIS client
	Redis goutilsRedis.Client `validate:"required"`
	// IPCReceiverFactory factory function to define Redis based IPC message receivers
	IPCReceiverFactory IPCMsgReceiverFactoryCB `validate:"required"`
	// IPCSenderFactory factory function to define Redis based IPC message senders
	IPCSenderFactory IPCMsgSenderFactoryCB `validate:"required"`
	// OnFatal, when set, is invoked (at most once) when the processing goroutine hits an
	// unrecoverable fault instead of terminating the process. reporter identifies the faulting
	// thread; err carries the cause (with code position in its chain); timestamp is when it was
	// detected. When nil, the default logs and calls log.Fatal, preserving prior behavior. The
	// goroutine exits after the callback runs.
	OnFatal models.OnFatalCB
}

type Receiver interface {
	/*
		Initialize perform complete initialization of a task worker instance.
		It consist of several steps.

			@param ctx context.Context - execution context
			@param activeDBClient db.Database - active database client session
	*/
	Initialize(ctx context.Context, activeDBClient db.Database) error

	/*
		Start the task queue processing threads

			@param ctx context.Context - execution context
	*/
	Start(ctx context.Context) error

	/*
		Stop the task queue processing threads

			@param ctx context.Context - execution context
	*/
	Stop(ctx context.Context) error
}

type Scheduler interface {
	/*
		Start the scheduler processing units

			@param ctx context.Context - execution context
	*/
	Start(ctx context.Context) error

	/*
		Stop the task scheduler processing units

			@param ctx context.Context - execution context
	*/
	Stop(ctx context.Context) error
}