package provider

import (
	"context"
	"time"
)

// Reasons shared by every Checker, so a listing reads the same across
// providers. Providers add their own for failures only they can tell
// apart (KVM's SSHHandshakeFailed or PoolNotActive, say).
const (
	ReasonReachable    = "Reachable"
	ReasonTimeout      = "Timeout"
	ReasonUnreachable  = "Unreachable"
	ReasonUnauthorized = "Unauthorized"
	ReasonForbidden    = "Forbidden"
	ReasonAPIError     = "APIError"
)

// TargetStatus is one target's verdict from a Checker.
type TargetStatus struct {
	// Name identifies the target within its provider: a KVM host name,
	// "apiserver", a GCP project.
	Name string
	// Address is what the check connected to, for humans.
	Address string
	Ready   bool
	// Reason is ReasonReachable when Ready, otherwise why not.
	Reason string
	// Message is human-readable detail, usually the error.
	Message string
	Latency time.Duration
	// Details are provider-specific facts gathered by the check.
	Details map[string]string
}

// Checker is the optional interface of a provider that can verify its
// backend is reachable and usable without touching any instance. The
// provider health monitor type-asserts for it on the unwrapped providers,
// so it stays out of the Provider contract.
type Checker interface {
	// Check returns one verdict per target, in a stable order. It never
	// fails as a whole — a failure is a verdict — and must return promptly
	// once ctx ends.
	Check(ctx context.Context) []TargetStatus
}