provider

type AWSRoleAuth struct {
	RoleARN string
	// Region is where GetAuthorizationToken is called: the REGISTRY's region, not where the
	// workload runs. Required, and stated rather than parsed out of the image reference: the
	// ECR host encodes a region, but a pull-through or replicated reference makes that a
	// guess, and the guess is only discovered wrong as an opaque auth failure.
	Region string
}

type BasicAuth struct {
	Username string
	Password string
}

type BlockScope struct {
	// Accelerator: nil => not applicable (CPU-only Pod, or DenyAll); &"" => every
	// accelerator; &"H100:8" => that one pool. The value is the request's POOL identity
	// (type:count), not the provider's SKU id, so a block stays confined to what ran out:
	// an L4:8 shortage must not exclude L4:1. It also stays stable when a launch spans
	// several interchangeable instance types. Filled in by the vnode handler, since the
	// adapter classifies from the error alone and cannot know it.
	Accelerator *string
	// CapacityType empty => blocks all capacity types.
	CapacityType nebulav1alpha1.CapacityType
	// Region: nil => the provider has no region axis (Modal/RunPod, whose candidates
	// carry an empty region too); &"us-east-1" => that region only, so a shortage there
	// does not disqualify us-west-2.
	Region *string
	// DenyAll true => block everything on this provider (auth/quota errors), ignoring the
	// fields above. Still scoped to this one provider; it never spans providers.
	DenyAll bool
}

type Capabilities struct {
	// SupportsStop is true if instances can be stopped/resumed (RunPod: false —
	// lifecycle is create/terminate only).
	SupportsStop bool
	// SupportsSpot is true if the provider offers interruptible capacity.
	SupportsSpot bool
	// SupportsEgressPolicy is true if the provider can enforce NodePoolSpec.Egress on the
	// instances it creates. False means placement SKIPS this provider for any pool that
	// restricts egress, rather than provisioning something with open internet access under
	// a policy that says otherwise (AWS: false — its instances land in the default VPC, so
	// enforcement needs security-group egress rules and no NAT, not one API field).
	SupportsEgressPolicy bool
	// NativeTags is true if the provider has real instance tags/labels; when
	// false, identity is encoded in the instance name (RunPod: false).
	NativeTags bool
	// PreemptionNotice is the advance warning before a spot reclaim; zero means
	// none (RunPod: 0 — abrupt, detected only by polling).
	PreemptionNotice time.Duration
	// PollInterval is how often the virtual node re-lists this provider to catch
	// changes nobody pushes: Pending→Running, preemption, external teardown. Per
	// provider because a spot-heavy backend wants reclaims noticed fast while an
	// OnDemand-only one can poll lazily. Zero means the vnode default (15s).
	PollInterval time.Duration
	// ProvisionTimeout bounds a single Provision call end to end, so a provider that
	// retries across capacity pools internally (AWS tries each AZ) gives up in time for
	// the outer region failover to run. It bounds the launch attempt, not "the workload
	// became healthy" — that stays the poll loop's job. Zero means no deadline beyond
	// the caller's context; single-pool providers (Modal) leave it zero.
	ProvisionTimeout time.Duration
}

type ExecOptions struct {
	// TTY asks for a pseudo-terminal, so the command believes it is interactive and line
	// editing works (`kubectl exec -it`). A provider that cannot allocate one still runs
	// the command: a shell without a TTY beats no shell.
	TTY bool
}

type Executor interface {
	Exec(ctx context.Context, instanceID string, cmd []string, opts ExecOptions) (Process, error)
}

type Instance struct {
	ID        string
	ClaimName string // recovered from the naming scheme (for tag-less providers)
	State     InstanceState
	// CapacityType reflects how the instance was provisioned, when known.
	CapacityType nebulav1alpha1.CapacityType
	// Region is where the instance actually lives, in the provider's own
	// vocabulary. Empty for region-simple providers that do not report one.
	Region string
	// Endpoint is the reachable address once ready (e.g. SSH host:port). It is not
	// secret, so unlike the connect credential it rides the level-triggered read path
	// and is re-reported on every tick.
	Endpoint string
}

type InstanceState string

type LogStreamer interface {
	Logs(ctx context.Context, instanceID string) (io.ReadCloser, error)
}

type Offering struct {
	AcceleratorType string
	CapacityType    nebulav1alpha1.CapacityType
	PricePerHour    float64
	Available       bool
	// Region is the provider region this row prices, in the provider's own
	// vocabulary (e.g. AWS "us-east-1"). Empty for region-simple providers whose
	// catalog is not region-partitioned (Modal, RunPod); a region-aware provider
	// emits one row per {accelerator, capacityType, region}.
	Region string
	// AcceleratorID is this provider's own name for what serves the canonical
	// AcceleratorType (AWS "p5.48xlarge" for H100) — the lookup data MapAccelerator
	// returns. Unset when the mapping is identity (Modal names its GPUs like the
	// canonical types) and catalog.Base's default MapAccelerator is used.
	AcceleratorID string
	// GPUCount is how many accelerators the AcceleratorID provides. It matters where the
	// count is baked into the offering: on AWS you pick an instance type with a fixed GPU
	// count (T4x1 = g4dn.xlarge, T4x8 = g4dn.metal), so the mapping key is
	// (AcceleratorType, GPUCount) and each accelerator appears once per count. Left 0 by
	// providers that take the count as a parameter (Modal).
	GPUCount int32
}

type Process interface {
	// Stdin is the command's input; closing it is how the command sees EOF. Nil when the
	// provider cannot write stdin, which makes the exec output-only.
	Stdin() io.WriteCloser
	// Stdout is the command's output — under a TTY, everything it writes.
	Stdout() io.Reader
	// Stderr is separate error output, or nil when there is none to separate. Nil is the
	// normal case under a TTY, where one terminal carries both.
	Stderr() io.Reader
	// Wait blocks until the command exits and returns its exit code. A non-zero code is
	// the command's own answer, NOT a failure — err is for "we could not find out".
	Wait(ctx context.Context) (int, error)
	// Close releases the streams and whatever connection carried them. It must unblock a
	// parked Read/Write, so a disconnected client cannot leave the transport running.
	Close() error
}

type Provider interface {
	// Name is the stable identifier, e.g. "runpod".
	Name() string

	// Capabilities declares provider quirks so the control plane can behave
	// generically instead of branching on provider name.
	Capabilities() Capabilities

	// Provision creates exactly one external instance for the Pod, which is the source of
	// truth for the whole workload shape: the implementation reads
	// image/command/env/ports/cpu/memory off pod.Spec, and the accelerator type+count via
	// util.AcceleratorRequest (then MapAccelerator). The request carries only what the Pod
	// cannot express: the chosen capacity tier and the claim identity.
	//
	// It returns the instance id, whether capacity is RESERVED, and any minted connect
	// credential. Reserved means the provider committed real capacity, not merely accepted
	// the request — two different guarantees an id alone cannot express:
	//
	//   - AWS reserves: an *instant* CreateFleet is synchronous, so an id means EC2 found
	//     capacity and the instance is booting; a shortfall is an error.
	//   - Modal does not: Create returns once the control plane accepts the sandbox, and
	//     the GPU may stay queued for minutes on a large shape.
	//
	// Callers use it for honest status: an unreserved instance is not yet initializing, so
	// its Pod stays at the provisioning reason. It says nothing about readiness, which is
	// observed later through List/Get. reserved=false still carries the full teardown
	// obligation; a provider that cannot tell the two apart returns true.
	//
	// Idempotency: if an instance already exists for req.ClaimName (encoded in the
	// provider's naming scheme, since most lack tags), return that id rather than creating
	// a second. Such a call returns NO credential — the original cannot be re-read.
	Provision(ctx context.Context, pod *corev1.Pod, req ProvisionRequest) (ProvisionResult, error)

	// Terminate destroys the instance by id. Must be idempotent — terminating an
	// already-gone instance returns nil, so the finalizer that guarantees no paid instance
	// leaks can retry safely.
	//
	// region is needed for providers that cannot infer it from the instance id (AWS) only.
	Terminate(ctx context.Context, instanceID, region string) error

	// Get returns the current state of one instance, or (nil, nil) if it no
	// longer exists (treat absence as terminated).
	//
	// region is as in Terminate, and matters more here: absence is read as terminated, so a
	// provider that had to search and searched the wrong place reports a live instance dead.
	Get(ctx context.Context, instanceID, region string) (*Instance, error)

	// List returns every instance Nebula owns on this provider, in as few API calls as
	// possible (ideally one). This is the engine of the poll loop: since no provider pushes
	// events, preemption and termination are detected by an instance disappearing or
	// changing state here.
	List(ctx context.Context) ([]Instance, error)

	// Offerings returns the price/availability rows this provider can serve, feeding the
	// optimizer's {provider,accelerator,capacityType} -> {price,avail} table. The caller
	// caches and refreshes it; an implementation may combine a static catalog with a live
	// availability probe.
	Offerings(ctx context.Context) ([]Offering, error)

	// MapAccelerator translates a canonical accelerator request (type + count) into the
	// provider ids that can serve it: the PRIMARY first, then interchangeable alternates.
	//
	// Count is part of the key because on some providers the GPU count is baked into the
	// offering: on AWS (L4, 1) and (L4, 8) are different instance types (g6.xlarge vs
	// g6.48xlarge) and so distinct capacity pools. A provider that attaches an arbitrary
	// count to one offering (Modal) ignores count. ok=false means no id for that pair.
	//
	// Most of the system uses ids[0], the PRIMARY, because failover keys a capacity block
	// on it: requests sharing a capacity pool must return the same primary, and ones that
	// do not must differ. The alternates broaden a SINGLE launch (AWS's fleet spans
	// instance types so EC2 lands on whichever has capacity) but never widen the
	// blocklist — an alternate running dry does not disable the primary.
	MapAccelerator(canonical string, count int32) (providerAcceleratorIDs []string, ok bool)

	// ExpandRegions resolves a pool's declared region constraint (ProviderSpec.Regions)
	// into the concrete regions placement may walk, in this provider's own vocabulary —
	// only the provider knows its geography:
	//
	//   - nil/empty  => unconstrained: every region this provider serves.
	//   - a GROUP token ("us", "eu", "ap") => that geography's regions.
	//   - anything else => a literal region name, passed through UNVALIDATED.
	//
	// That last case is deliberate: region names change faster than this code, so an
	// unrecognized one is forwarded and a genuinely bad name fails at provision time with
	// the provider's own error. Better than refusing a region that shipped last week.
	//
	// Expanding HERE, at the pool boundary, keeps everything downstream single-valued —
	// NodeClaimSpec.Region, ProvisionRequest.Region and the blocklist key — so a capacity
	// failure blocks the one candidate that failed, not the group it came from.
	//
	// How many candidates a declaration becomes depends on whether the provider can FAIL
	// OVER between regions. One that reports a shortage synchronously (AWS) returns one
	// candidate per region, so the next is tried. One that just queues the request with no
	// error (Modal) must not: nothing would re-drive placement, so only the first
	// candidate would ever be tried. It returns ONE opaque candidate carrying the whole
	// set and lets its own scheduler choose.
	//
	// Pure (no API calls, no ctx), because the result feeds both placement's candidate walk
	// and the List/Offerings fan-out, and those MUST agree: a region provisioned into but
	// not swept is absent from List, which reports a live instance as Terminated.
	ExpandRegions(declared []string) []string

	// ClassifyProvisionError maps a Provision error to the granularity at which
	// the failing placement should be blocklisted. This keeps failover precise:
	// a "no H100 capacity" error blocks only {provider, H100, capacityType, region},
	// while an auth/quota error blocks the whole provider. See BlockScope.
	//
	// accelerator and region are the two request facts the error does not carry, both ""
	// when absent (a CPU-only Pod, a region-simple provider). The provider returns the
	// COMPLETE scope; no caller assembles one piecemeal afterwards.
	ClassifyProvisionError(err error, accelerator, region string) BlockScope
}

type ProvisionRequest struct {
	// ClaimName is the NodeClaim name; providers without native tags encode it
	// into the instance name so List/Terminate can find the instance later.
	ClaimName string
	// CapacityType is the tier the optimizer chose (Spot/OnDemand) — a decision that has
	// nowhere to live on the Pod.
	CapacityType nebulav1alpha1.CapacityType
	// Region is the ONE candidate placement chose, exactly as this provider's own
	// ExpandRegions minted it — already resolved (never a group token) and opaque to the
	// control plane. Usually one concrete region (AWS "us-east-1"), which is what lets a
	// capacity failure blocklist just that region; a provider that cannot fail over
	// (Modal) may encode several for its own scheduler, and only that adapter parses it.
	//
	// Empty means "no region constraint" — common, not a fallback: a pool declaring no
	// regions leaves it empty, which on Modal is the widest and cheapest option (pinning
	// costs 1.5-1.75x). AWS cannot honour it, but its ExpandRegions never produces it.
	Region string
	// Egress is the pool's outbound policy, or nil for Open. Placement has already checked
	// that this provider can enforce it (Capabilities.SupportsEgressPolicy), so an adapter
	// receiving a restrictive policy must apply it or fail the Provision — never silently
	// drop it, which would leave the workload on the open internet under a policy that says
	// otherwise. Resolved from the NodePool at provision time, never from the Pod, which
	// the workload's own owner can patch (see vnode.Handler.egressFor).
	Egress *nebulav1alpha1.EgressPolicy
	// Env is the container's environment, fully RESOLVED: literals plus everything
	// envFrom/valueFrom referenced, merged in kubelet precedence (envFrom in listed order,
	// then env overriding it). A provider forwards it and never re-reads the Pod's env,
	// which holds references it cannot follow.
	//
	// Resolved by the caller (pkg/vnode): reading a Secret needs cluster access an adapter
	// deliberately lacks, and kubelet precedence should be implemented once.
	//
	// SECRET-BEARING, and why this struct redacts itself — a secretKeyRef's value lands here
	// in the clear. Never log the map, never put it on the Pod, never in an error string,
	// the same rule as ProvisionResult.ConnectToken. Nil is normal: no env, or an
	// unresolving caller.
	Env map[string]string
	// RegistryAuth authenticates the pull of the container image, from the Pod's
	// imagePullSecrets; nil is an anonymous pull. Resolved by the caller (pkg/vnode) for the
	// same reason as Env — it names a Secret an adapter cannot read.
	RegistryAuth *RegistryAuth
}

type ProvisionResult struct {
	// InstanceID is the provider's id for the instance. Non-empty on success, and
	// carrying the full teardown obligation from that moment on.
	InstanceID string
	// Reserved is whether the provider committed actual capacity, as opposed to
	// merely accepting the request. See Provision.
	Reserved bool
	// ConnectURL and ConnectToken are the credential for reaching the instance — an address
	// plus the bearer token authenticating against it, which is all a consumer needs:
	//
	//	curl -H "Authorization: Bearer $token" $url
	//
	// Returned here and ONLY here: minting is one-shot with no read-back (Modal's
	// CreateConnectToken returns a DIFFERENT token each call). The caller must persist it
	// durably — the virtual kubelet writes both to a Secret — or it is gone. Empty when
	// the instance needs no credential, or on an idempotent re-Provision.
	//
	// The TOKEN is a SECRET: never log it, never put it on the Pod (annotations are
	// readable with `get pod` and unencrypted in etcd), never in an error string.
	//
	// ConnectURL is not secret, and is NOT Instance.Endpoint even when they agree: this is
	// the one-shot create path, while the endpoint is observed, so it is what reports an
	// address that only exists after boot and survives a manager restart.
	ConnectURL   string
	ConnectToken string
}

type RegistryAuth struct {
	// Registry is the host the credential applies to, from the image reference.
	Registry string
	// AWSRole authenticates by role assumption; see AWSRoleAuth.
	AWSRole *AWSRoleAuth
	// Basic authenticates with a username and password; see BasicAuth.
	Basic *BasicAuth
}