interface.go

package worker

import (
	"context"
	"time"

	"github.com/google/uuid"
	"go.opentelemetry.io/otel/metric"
)

// Service is an interface for a task manager.
type Service interface {
	workerOperations
	taskOperations
	durableOperations
	metricsOperations
	retentionOperations
	hooksOperations
	tracerOperations
}

type workerOperations interface {
	// RegisterTask registers a new task to the worker.
	RegisterTask(ctx context.Context, task *Task) error
	// RegisterTasks registers multiple tasks to the worker.
	RegisterTasks(ctx context.Context, tasks ...*Task) error
	// StartWorkers starts the task manager's workers (idempotent).
	StartWorkers(ctx context.Context)
	// SetMaxWorkers adjusts the worker pool size.
	SetMaxWorkers(n int)
	// Wait waits for all tasks to finish or context cancellation.
	Wait(ctx context.Context) error
	// StopGraceful stops accepting new tasks and waits for completion.
	StopGraceful(ctx context.Context) error
	// StopNow cancels running tasks and stops workers immediately.
	StopNow()
}

type taskOperations interface {
	// CancelAll cancels all tasks.
	CancelAll()
	// CancelTask cancels a task by its ID.
	CancelTask(id uuid.UUID) error
	// GetActiveTasks returns the number of running tasks.
	GetActiveTasks() int
	// GetResults returns a results channel (compatibility shim for legacy API).
	GetResults() <-chan Result
	// SubscribeResults returns a results channel and unsubscribe function.
	SubscribeResults(buffer int) (<-chan Result, func())
	// SetResultsDropPolicy configures how full subscriber buffers are handled.
	SetResultsDropPolicy(policy ResultDropPolicy)
	// GetTask gets a task by its ID.
	GetTask(id uuid.UUID) (task *Task, err error)
	// GetTasks gets all tasks.
	GetTasks() []*Task
	// ExecuteTask executes a task given its ID and returns the result.
	ExecuteTask(ctx context.Context, id uuid.UUID, timeout time.Duration) (any, error)
}

type durableOperations interface {
	// RegisterDurableTask registers a durable task in the configured backend.
	RegisterDurableTask(ctx context.Context, task DurableTask) error
	// RegisterDurableTasks registers multiple durable tasks.
	RegisterDurableTasks(ctx context.Context, tasks ...DurableTask) error
}

type metricsOperations interface {
	// GetMetrics returns a snapshot of task metrics.
	GetMetrics() MetricsSnapshot
	// SetMeterProvider enables OpenTelemetry metrics collection.
	SetMeterProvider(provider metric.MeterProvider, opts ...OTelMetricsOption) error
}

type retentionOperations interface {
	// SetRetentionPolicy configures task registry retention.
	SetRetentionPolicy(policy RetentionPolicy)
}

type hooksOperations interface {
	// SetHooks configures task lifecycle hooks.
	SetHooks(hooks TaskHooks)
}

type tracerOperations interface {
	// SetTracer configures task tracing.
	SetTracer(tracer TaskTracer)
}

// Middleware describes a generic middleware.
type Middleware[T any] func(T) T

// RegisterMiddleware registers middlewares to the provided service.
func RegisterMiddleware[T any](svc T, mw ...Middleware[T]) T {
	for _, m := range mw {
		svc = m(svc)
	}

	return svc
}