oncetask

type ContextHandler struct {
	// contains filtered or unexported fields
}

type Data[TaskKind comparable] interface {
	GetType() TaskKind

	// Generate a deterministic, idempotent ID based on the task's natural key.
	// This ensures that reprocessing the same task produces the same task ID,
	// allowing for safe overwrites instead of creating duplicates.
	GenerateIdempotentID() string
}

type ExponentialBackoffPolicy struct {
	MaxAttempts int           // Maximum attempts (0 = unlimited)
	BaseDelay   time.Duration // Initial delay (default: 1 second)
	MaxDelay    time.Duration // Maximum delay cap (default: 5 minutes)
	Multiplier  float64       // Multiplier per attempt (default: 2.0)
}

type FixedDelayPolicy struct {
	MaxAttempts int           // Maximum attempts (0 = unlimited)
	Delay       time.Duration // Delay between retries
}

type Handler[TaskKind ~string] func(ctx context.Context, task *OnceTask[TaskKind]) (any, error)

type HandlerOption func(*handlerConfig)

type Manager[TaskKind ~string] interface {
	// CreateTask creates a once task to Firestore.
	// The task parameter should be created using fs_models/once.NewOnceTask().
	// If a task with the same ID already exists, logs and returns nil (idempotent).
	// Returns true if the task was created, false if it already existed.
	// Returns false if a task with the same ID already exists or error.
	CreateTask(ctx context.Context, taskData Data[TaskKind]) (bool, error)

	// CreateTasks creates multiple once tasks using Firestore BulkWriter.
	//
	// This method is NON-ATOMIC: individual task creations can succeed or fail independently.
	// This is intentional - it allows partial success when some tasks already exist or fail,
	// rather than failing the entire batch.
	//
	// Idempotency: Tasks that already exist (same ID) are silently skipped and do not
	// contribute to the returned error. This makes it safe to retry the entire batch.
	//
	// Returns:
	//   - (created count, nil) if all tasks were created or already existed
	//   - (created count, error) if at least one task failed for a reason other than already-existing
	//
	// The returned error aggregates all non-AlreadyExists failures using errors.Join.
	CreateTasks(ctx context.Context, taskDataList []Data[TaskKind]) (int, error)

	// RegisterTaskHandler listens for new tasks and executes the handler function for each task.
	// Handler returns (result, nil) on success or (nil, error) on failure.
	// Use NoResult() adapter for handlers that don't produce a result.
	//
	// Configuration options (see HandlerOption for details and examples):
	//   - WithRetryPolicy: Configure retry behavior for task execution
	//   - WithCancellationHandler: Register a cleanup handler for cancelled tasks (optional)
	//   - WithCancellationRetryPolicy: Configure retry behavior for cancellation handlers
	//   - WithLeaseDuration: Set how long a task is leased during execution
	//   - WithConcurrency: Set number of concurrent workers
	RegisterTaskHandler(taskType TaskKind, handler Handler[TaskKind], opts ...HandlerOption) error

	// RegisterResourceKeyHandler listens for new tasks and executes the handler for all tasks with the same resource key.
	// All pending tasks with the same resource key are grouped together and ordered by WaitUntil.
	// The handler is responsible for any additional ordering logic.
	// If the handler returns nil, all tasks for that resource key are marked as done.
	// If the handler returns an error, all tasks for that resource key will be retried.
	// Tasks without a resource key are processed individually.
	// Handler returns (result, nil) on success or (nil, error) on failure.
	// Use NoResultResourceKey() adapter for handlers that don't produce a result.
	//
	// Configuration options (see HandlerOption for details and examples):
	//   - WithRetryPolicy: Configure retry behavior for task execution
	//   - WithCancellationHandler: Register a cleanup handler for cancelled tasks (optional)
	//   - WithCancellationRetryPolicy: Configure retry behavior for cancellation handlers
	//   - WithLeaseDuration: Set how long a task is leased during execution
	//   - WithConcurrency: Set number of concurrent workers
	RegisterResourceKeyHandler(taskType TaskKind, handler ResourceKeyHandler[TaskKind], opts ...HandlerOption) error

	// GetTasksByResourceKey retrieves all tasks with the given resource key.
	// Returns tasks ordered by CreatedAt (oldest first).
	// The tasks must belong to the current environment (from ONCE_TASK_ENV).
	GetTasksByResourceKey(ctx context.Context, resourceKey string) ([]OnceTask[TaskKind], error)

	// GetTasksByIds retrieves tasks by their IDs.
	// Returns tasks in no guaranteed order.
	// Tasks not found are omitted from the result (no error).
	// The tasks must belong to the current environment (from ONCE_TASK_ENV).
	GetTasksByIds(ctx context.Context, ids []string) ([]OnceTask[TaskKind], error)

	// CancelTask marks a single task as cancelled.
	// Idempotent: no-op if task is already done or cancelled.
	// Sets isCancelled=true, cancelledAt=now, waitUntil=NoWait (immediate execution).
	CancelTask(ctx context.Context, taskID string) error

	// CancelTasksByResourceKey marks all non-done tasks with resourceKey as cancelled.
	// Returns count of tasks cancelled.
	CancelTasksByResourceKey(ctx context.Context, taskType TaskKind, resourceKey string) (int, error)

	// CancelTasksByIds marks multiple tasks as cancelled (bulk operation via BulkWriter).
	// Returns count of tasks cancelled. Partial failures return both count and aggregated error.
	// Returns error if task belongs to a different environment.
	// Idempotent: Tasks already done or cancelled are skipped (no-op).
	CancelTasksByIds(ctx context.Context, taskIDs []string) (int, error)

	// DeleteTask permanently removes a single task from Firestore.
	// Returns error if task belongs to a different environment.
	// Idempotent: no error if task doesn't exist.
	// WARNING: If the task is currently being executed (leased), the handler will
	// continue running but fail when attempting to update task status on completion.
	DeleteTask(ctx context.Context, taskID string) error

	// DeleteTasksByIds permanently removes multiple tasks from Firestore (bulk operation via BulkWriter).
	// Returns count of tasks deleted. Partial failures return both count and aggregated error.
	// Returns error if task belongs to a different environment.
	// Idempotent: non-existent tasks are silently skipped.
	// WARNING: Deleting leased tasks will cause running handlers to fail on completion.
	DeleteTasksByIds(ctx context.Context, taskIDs []string) (int, error)

	// ResetTask resets a single task back to pending state for re-execution.
	// Only applies to tasks in terminal states (doneAt != "").
	// Returns error if task belongs to a different environment.
	// Idempotent: no-op if task is already pending/running.
	// Clears all execution state (Attempts, Errors, Result) and cancellation state (IsCancelled).
	// Sets WaitUntil=NoWait for immediate execution.
	ResetTask(ctx context.Context, taskID string) error

	// ResetTasksByIds resets multiple tasks back to pending state (bulk operation via BulkWriter).
	// Returns count of tasks reset. Partial failures return both count and aggregated error.
	// Only resets tasks in terminal states (doneAt != "").
	// Returns error if task belongs to a different environment.
	// Idempotent: Tasks already in non-terminal states are skipped (no-op).
	ResetTasksByIds(ctx context.Context, taskIDs []string) (int, error)
}

type NoRetryPolicy struct{}

type OnceTask[TaskKind ~string] struct {
	Id   string                 `json:"id" firestore:"id"` // Also the idempotency key.
	Type TaskKind               `json:"type" firestore:"type"`
	Data map[string]interface{} `json:"data" firestore:"data"`

	// Optional - identifies a resource that requires serialization (e.g., calendarId, conversationId)
	// When set, lease acquisition checks for active leases on other tasks with the same ResourceKey
	ResourceKey string `json:"resourceKey" firestore:"resourceKey"`

	// Environment identifier for logical separation of tasks (e.g., "dev", "staging", "prod")
	// Read from `EnvVariable` (ONCE_TASK_ENV) environment variable, defaults to "DEFAULT"
	Env string `json:"env" firestore:"env"`

	WaitUntil   string `json:"waitUntil" firestore:"waitUntil"`     // ISO 8601 - wait until this time to execute the task.
	LeasedUntil string `json:"leasedUntil" firestore:"leasedUntil"` // ISO 8601 - lease expiration for the task executor.
	CreatedAt   string `json:"createdAt" firestore:"createdAt"`     // ISO 8601
	DoneAt      string `json:"doneAt" firestore:"doneAt"`           // ISO 8601

	// Retry and result tracking fields
	Attempts int         `json:"attempts" firestore:"attempts"` // Number of execution attempts (incremented when lease is acquired)
	Errors   []TaskError `json:"errors" firestore:"errors"`     // Failure history (one entry per failed attempt)
	Result   any         `json:"result" firestore:"result"`     // Handler output (optional, can be nil on success)

	// Recurrence fields
	// For recurrence tasks (generators): Recurrence is set, ParentRecurrenceID is empty
	// For occurrence tasks (instances): Recurrence is nil, ParentRecurrenceID points to generator
	Recurrence          *Recurrence `json:"recurrence" firestore:"recurrence"`                   // Recurrence config (nil = one-time or occurrence task)
	ParentRecurrenceID  string      `json:"parentRecurrenceId" firestore:"parentRecurrenceId"`   // ID of parent recurrence task (empty = standalone or recurrence task)
	OccurrenceTimestamp string      `json:"occurrenceTimestamp" firestore:"occurrenceTimestamp"` // Scheduled time of this occurrence (ISO 8601)

	// Cancellation fields
	IsCancelled bool   `json:"isCancelled" firestore:"isCancelled"` // Cancellation flag (false = not cancelled)
	CancelledAt string `json:"cancelledAt" firestore:"cancelledAt"` // ISO 8601 timestamp when task was cancelled (audit trail)
}

type Recurrence struct {
	RRule   string   `json:"rrule" firestore:"rrule"`     // RFC 5545 rule, e.g., "FREQ=WEEKLY;BYDAY=MO"
	DTStart string   `json:"dtstart" firestore:"dtstart"` // Recurrence anchor time (ISO 8601)
	ExDates []string `json:"exdates" firestore:"exdates"` // Exception dates to skip
}

type RecurrenceProvider interface {
	GetRecurrence() *Recurrence
}

type ResourceKeyHandler[TaskKind ~string] func(ctx context.Context, tasks []OnceTask[TaskKind]) (any, error)

type ResourceKeyProvider interface {
	GetResourceKey() string
}

type RetryPolicy interface {
	// ShouldRetry returns true if the task should be retried after failure.
	// attempts is the current attempt count (1 = first attempt, 2 = first retry, etc.)
	ShouldRetry(attempts int, err error) bool

	// NextRetryDelay returns the duration to wait before the next retry.
	// attempts is the current attempt count.
	// err is the error returned by the handler, which can be used to determine the delay.
	NextRetryDelay(attempts int, err error) time.Duration
}

type ScheduledTask interface {
	GetScheduledTime() time.Time
}

type TaskError struct {
	At    string `json:"at" firestore:"at"`       // ISO 8601 timestamp of failure
	Error string `json:"error" firestore:"error"` // Failure reason
}

type TaskStatus string