// Package port defines interface contracts for external adapters.
package port

import (
	"context"
	"time"

	"github.com/orchard9/rdev/internal/domain"
)

// WorkerRegistry manages the lifecycle of workers in the pool.
// It handles registration, heartbeats, status updates, and health monitoring.
type WorkerRegistry interface {
	// Register adds a worker to the pool.
	// If a worker with the same ID already exists, it is re-registered.
	Register(ctx context.Context, worker *domain.Worker) error

	// Heartbeat updates the worker's last_heartbeat timestamp.
	// Returns ErrWorkerNotFound if the worker does not exist or is offline.
	Heartbeat(ctx context.Context, workerID string) error

	// UpdateStatus changes a worker's status and optionally assigns a task.
	// Pass empty taskID to clear the current task assignment.
	UpdateStatus(ctx context.Context, workerID string, status domain.WorkerStatus, taskID string) error

	// Deregister removes a worker from the pool.
	Deregister(ctx context.Context, workerID string) error

	// Get retrieves a specific worker by ID.
	// Returns ErrWorkerNotFound if the worker does not exist.
	Get(ctx context.Context, workerID string) (*domain.Worker, error)

	// List returns all workers matching the filter.
	List(ctx context.Context, filter WorkerFilter) ([]*domain.Worker, error)

	// MarkStaleOffline marks workers without a recent heartbeat as offline.
	// Returns the number of workers marked offline.
	MarkStaleOffline(ctx context.Context, threshold time.Duration) (int, error)
}

// WorkerFilter specifies criteria for listing workers.
type WorkerFilter struct {
	// Status filters workers by status. Nil means all statuses.
	Status *domain.WorkerStatus

	// HasCapability filters workers that have a specific capability.
	HasCapability string

	// Limit is the maximum number of workers to return. Zero means no limit.
	Limit int
}