package schedulerclient

import "context"

// ── Client interface ────────────────────────────────────────────────────────

// Client provides read and write access to the scheduler cluster through a
// scheduler-agnostic unified resource model (URM).
//
// Implementations talk to the apiserver's REST API and authenticate via
// either a Bearer JWT token or an XCE API Key (xce_ak_ prefix).
type Client interface {
	// ── Jobs ──

	// ListJobs returns jobs matching the given filter.
	// An empty filter returns all visible jobs.
	ListJobs(ctx context.Context, filter JobFilter) ([]*URMJob, *Page, error)

	// GetJob returns a single job by its ID.
	GetJob(ctx context.Context, id string) (*URMJob, error)

	// GetJobLogs retrieves output logs for a job.
	GetJobLogs(ctx context.Context, id string, opts LogOpts) ([]string, error)

	// ── Queues ──

	// ListQueues returns all visible queues with their current state.
	ListQueues(ctx context.Context) ([]*URMQueue, error)

	// ── Nodes ──

	// ListNodes returns all visible compute nodes with resource usage.
	ListNodes(ctx context.Context) ([]*URMNode, error)

	// ── Metrics ──

	// GetClusterMetrics returns a snapshot of overall cluster resource usage.
	GetClusterMetrics(ctx context.Context) (*Metrics, error)

	// ── Write operations (Phase 1) ──

	// SubmitJob submits a job and returns its assigned ID.
	SubmitJob(ctx context.Context, spec JobSpec) (*SubmitJobResult, error)

	// CancelJob kills a job (action "kill", default SIGTERM).
	CancelJob(ctx context.Context, id string) error

	// HoldJob suspends a job (action "stop", default SIGTSTP).
	HoldJob(ctx context.Context, id string) error

	// ReleaseJob resumes a suspended job (action "resume", default SIGCONT).
	ReleaseJob(ctx context.Context, id string) error

	// CheckpointJob checkpoints a running job (action "checkpoint", CRIU).
	CheckpointJob(ctx context.Context, id string) error

	// RestartJob re-queues a finished job as a new job (resuming from its last
	// checkpoint when one exists) and returns the new job's identity.
	RestartJob(ctx context.Context, id string) (*RestartJobResult, error)

	// ── Event stream (Phase 2) ──

	// WatchJobs subscribes to the live job-event SSE stream and returns a
	// channel of lifecycle events (job.created / job.updated / job.deleted /
	// job.finished). The channel is closed when the context is cancelled or
	// the stream ends. The caller is responsible for cancelling ctx.
	WatchJobs(ctx context.Context) (<-chan JobEvent, error)
}