client

type AgentKey struct {
	// MachineID is the permanent host identifier the record is keyed by.
	MachineID string
	// Hostname is the hostname recorded at acceptance. A response claiming
	// a different hostname is not this agent's to answer for.
	Hostname string
	// PublicKey is the key recorded at acceptance.
	PublicKey ed25519.PublicKey
	// SupersededKey is the key a rotation replaced, kept acceptable until
	// SupersededUntil so a message signed moments before the rotation is not
	// rejected for arriving late. Absent outside a rotation window.
	SupersededKey ed25519.PublicKey
	// SupersededUntil is the instant the superseded key stops being accepted.
	SupersededUntil time.Time
}

type AgentKeyStore interface {
	LookupAgentKey(
		ctx context.Context,
		machineID string,
	) (*AgentKey, error)
}

type Client struct {

	// JSONMarshalFn is the function used to marshal JSON. Defaults to json.Marshal.
	// Exported for testing.
	JSONMarshalFn func(v any) ([]byte, error)
	// contains filtered or unexported fields
}

type CreateJobResult struct {
	JobID     string `json:"job_id"`
	Status    string `json:"status"`
	Revision  uint64 `json:"revision"`
	Timestamp string `json:"timestamp"`
}

type JobClient interface {
	// Generic dispatch operations — used by API handlers to submit jobs
	// without importing typed wrapper methods.
	Query(
		ctx context.Context,
		target string,
		category string,
		operation job.OperationType,
		data any,
	) (string, *job.Response, error)
	QueryBroadcast(
		ctx context.Context,
		target string,
		category string,
		operation job.OperationType,
		data any,
	) (string, map[string]*job.Response, error)
	Modify(
		ctx context.Context,
		target string,
		category string,
		operation job.OperationType,
		data any,
	) (string, *job.Response, error)
	ModifyBroadcast(
		ctx context.Context,
		target string,
		category string,
		operation job.OperationType,
		data any,
	) (string, map[string]*job.Response, error)

	// Job queue management operations
	GetQueueSummary(
		ctx context.Context,
	) (*job.QueueStats, error)
	GetJobStatus(
		ctx context.Context,
		jobID string,
	) (*job.QueuedJob, error)
	ListJobs(
		ctx context.Context,
		statusFilter string,
		limit int,
		offset int,
	) (*ListJobsResult, error)

	// Agent discovery
	ListAgents(
		ctx context.Context,
	) ([]job.AgentInfo, error)
	GetAgent(
		ctx context.Context,
		hostname string,
	) (*job.AgentInfo, error)

	// Agent timeline
	WriteAgentTimelineEvent(
		ctx context.Context,
		hostname, event, message string,
	) error
	GetAgentTimeline(
		ctx context.Context,
		hostname string,
	) ([]job.TimelineEvent, error)

	// Agent drain flag
	CheckDrainFlag(
		ctx context.Context,
		hostname string,
	) bool
	SetDrainFlag(
		ctx context.Context,
		hostname string,
	) error
	DeleteDrainFlag(
		ctx context.Context,
		hostname string,
	) error

	// Job deletion
	DeleteJob(
		ctx context.Context,
		jobID string,
	) error

	// Job retry
	RetryJob(
		ctx context.Context,
		jobID string,
		targetHostname string,
	) (*CreateJobResult, error)

	// Agent operations - used by agents for processing
	// HasJobResponse reports whether this agent has already recorded a
	// response for the given job. Used to detect a redelivered message
	// for a job this agent has already executed, so the operation is not
	// run a second time.
	HasJobResponse(
		ctx context.Context,
		jobID string,
		hostname string,
	) (bool, error)
	WriteStatusEvent(
		ctx context.Context,
		jobID string,
		event string,
		hostname string,
		data map[string]interface{},
	) error
	WriteJobResponse(
		ctx context.Context,
		jobID string,
		hostname string,
		responseData []byte,
		status string,
		errorMsg string,
		changed *bool,
	) error
	ConsumeJobs(
		ctx context.Context,
		streamName string,
		consumerName string,
		handler func(jetstream.Msg) error,
		opts *natsclient.ConsumeOptions,
	) error
	GetJobData(
		ctx context.Context,
		jobKey string,
	) ([]byte, error)
	CreateOrUpdateConsumer(
		ctx context.Context,
		streamName string,
		consumerConfig jetstream.ConsumerConfig,
	) error

	// SetPKISigner wires the signer used to sign outgoing job and response
	// payloads and to verify incoming ones. The keypair a signer needs is
	// not always available at client construction time, so this is called
	// once one is: on the controller when the enrollment watcher loads the
	// controller keypair, and on the agent when PKI enrollment loads the
	// agent keypair. Passing nil disables signing and verification.
	SetPKISigner(
		signer PKISigner,
	)

	// SetAgentKeyStore wires the store used to verify agent responses. Like
	// the signer, it is not available at construction: on the controller it
	// arrives with the enrollment watcher. Passing nil leaves responses
	// unverified, which is the behaviour before this feature.
	SetAgentKeyStore(
		store AgentKeyStore,
	)

	// SetMachineID records the identity stamped on payloads this client
	// signs, so the verifier knows which stored key to check them against.
	// Set on the agent once its identity is resolved; empty on the
	// controller, whose payloads agents verify against the controller key.
	SetMachineID(
		machineID string,
	)
}

type ListJobsResult struct {
	Jobs         []*job.QueuedJob
	TotalCount   int
	StatusCounts map[string]int
}

type NATSClient interface {
	Publish(
		ctx context.Context,
		subject string,
		data []byte,
	) error
	GetStreamInfo(
		ctx context.Context,
		streamName string,
	) (*jetstream.StreamInfo, error)
	KVPut(
		bucket string,
		key string,
		value []byte,
	) error
	ConsumeMessages(
		ctx context.Context,
		streamName string,
		consumerName string,
		handler natsclient.JetStreamMessageHandler,
		opts *natsclient.ConsumeOptions,
	) error
	CreateOrUpdateConsumerWithConfig(
		ctx context.Context,
		streamName string,
		consumerConfig jetstream.ConsumerConfig,
	) error
}

type Options struct {
	// Timeout for waiting for job responses (default: 30s)
	Timeout time.Duration
	// KVBucket for job storage (required)
	KVBucket jetstream.KeyValue
	// RegistryKV is the KV bucket for agent registry (optional).
	RegistryKV jetstream.KeyValue
	// FactsKV is the KV bucket for agent facts (optional).
	FactsKV jetstream.KeyValue
	// StateKV is the KV bucket for persistent agent state (drain flags, timeline).
	StateKV jetstream.KeyValue
	// StreamName is the JetStream stream name (used to derive DLQ name).
	StreamName string
	// PKISigner signs job payloads when PKI is enabled. Nil when disabled.
	PKISigner PKISigner
	// TargetResolver resolves hostname targets to machine IDs for NATS
	// subject routing. When nil, targets are used as-is.
	TargetResolver func(string) string
}

type PKISigner interface {
	// Sign signs the given data with the signer's private key.
	Sign(data []byte) []byte
	// Fingerprint returns the SHA256 fingerprint of the signer's public key.
	Fingerprint() string
	// ControllerPublicKey returns the controller's public key for verifying
	// controller-signed messages. Returns nil if not set.
	ControllerPublicKey() ed25519.PublicKey
}