cluster

type Agent struct {
	// contains filtered or unexported fields
}

type Client interface {
	// SelfNodeID returns this node's stable cluster identifier.
	SelfNodeID() string
	// SelfAPIURL returns this node's externally-reachable API base URL.
	SelfAPIURL() string

	// OwnerOf returns the node currently owning sandboxID, or
	// ErrUnknownSandbox if no placement record exists.
	OwnerOf(sandboxID string) (OwnerInfo, error)

	// OwnerOfName resolves a cluster-wide sandbox name to its sandbox ID and
	// current owner. Names are indexed from replicated specs and exist for
	// facade APIs that accept either ID or name. Returns ErrUnknownSandbox if
	// no placement record claims name.
	OwnerOfName(name string) (string, OwnerInfo, error)

	// SelectPlacement chooses a node to host a new sandbox with the given
	// resource request. In single-node mode it always returns self.
	SelectPlacement(req capacity.Request) (PlacementTarget, error)

	// RecordPlacement commits sandboxID -> self into the FSM along with the
	// (optional) creation spec used to re-materialize the sandbox after a
	// failover. Idempotent — re-recording with the same owner is a no-op, and
	// passing spec=nil preserves any spec that was previously replicated for
	// this id (so a boot-time replay can't erase a richer record written by
	// the original CreateSandbox call).
	//
	// spec MUST be redacted (no plaintext credentials) before being passed in;
	// secrets is the provider handle produced by the service layer. Passing an
	// empty handle preserves any previously replicated ref (mirrors the
	// spec-preservation rule — a boot-time replay that has the spec but not
	// the secrets can't erase the original create's recoverability handle).
	RecordPlacement(ctx context.Context, sandboxID string, spec *models.CreateSandboxRequest, secrets PlacementSecrets) error

	// ClaimOrphan promotes an orphaned placement back to self. It succeeds
	// only when the placement is currently orphaned and either has no recorded
	// previous owner (legacy row) or was orphaned from this node. It preserves
	// any replicated spec/secrets when the caller passes nil.
	ClaimOrphan(ctx context.Context, sandboxID string, spec *models.CreateSandboxRequest, secrets PlacementSecrets) error

	// UpsertSpec replaces the replicated spec for sandboxID without touching
	// ownership. Mutating handlers (resize, lifecycle) call this after a
	// successful local mutation so the FSM stays current — otherwise a
	// failover-recreated sandbox would revert to its create-time shape.
	//
	// spec MUST be redacted. An empty secrets handle preserves the previously
	// replicated ref — resize/lifecycle never touch credentials, so passing an
	// empty handle is the right choice for those callers; the "real" secrets
	// are only re-shipped when the user re-runs create or rotates them
	// explicitly.
	UpsertSpec(ctx context.Context, sandboxID string, spec *models.CreateSandboxRequest, secrets PlacementSecrets) error

	// SpecOf returns the most-recently-replicated CreateSandboxRequest for
	// sandboxID, or nil if no spec is recorded (pre-cluster sandbox, or no
	// placement). The returned spec is REDACTED — no plaintext secrets. Use
	// SecretsOf to retrieve the matching provider handle if you need to
	// reconstruct the full spec for a recreate.
	SpecOf(sandboxID string) *models.CreateSandboxRequest

	// SecretsOf returns the secret provider handle paired with SpecOf's spec.
	// Empty when the sandbox was created without any private-registry / mount
	// credentials, or when the placement predates secret replication.
	SecretsOf(sandboxID string) PlacementSecrets

	// AddExposedPort records intent that sandboxID has port exposed. Raw TCP
	// routes include HostPort so every ingress node can bind/proxy the same
	// cluster-wide endpoint. Idempotent when the route metadata is unchanged.
	AddExposedPort(ctx context.Context, sandboxID string, port int, route ExposedPortRoute) error

	// RemoveExposedPort drops a port intent from the placement. Idempotent.
	RemoveExposedPort(ctx context.Context, sandboxID string, port int) error

	// ExposedPortsOf returns a copy of the replicated port route map for
	// sandboxID, or nil if none. Used by the recreator and ingress reconciler.
	ExposedPortsOf(sandboxID string) map[int]ExposedPortRoute

	// AddCustomDomain records intent that sandboxID owns hostname (already
	// canonicalized lower-case) cluster-wide. Returns ErrCustomHostnameConflict
	// when a different sandbox already holds it. Idempotent for the same
	// (sandbox, hostname) pair so retries are safe.
	AddCustomDomain(ctx context.Context, sandboxID, hostname string) error

	// RemoveCustomDomain drops hostname from sandboxID's set. No-op when the
	// hostname isn't claimed by this sandbox (the local row may already be
	// gone after a Delete) so callers can retry without special-casing.
	RemoveCustomDomain(ctx context.Context, sandboxID, hostname string) error

	// CustomDomainsOf returns a copy of the replicated hostname set for
	// sandboxID, or nil when no placement exists or the set is empty. The
	// ingress reconciler uses it to populate Caddy matchers on every node.
	CustomDomainsOf(sandboxID string) []string

	// ResolveCustomDomain answers "which sandbox owns this hostname?" from
	// the local FSM in O(1). Used by the TLS-ask handler on ingress nodes
	// that may not own the sandbox row themselves. hostname is matched
	// case-insensitively. Returns sandboxID, true when known.
	ResolveCustomDomain(hostname string) (string, bool)

	// DeletePlacement removes sandboxID from the FSM. Idempotent.
	DeletePlacement(ctx context.Context, sandboxID string) error

	// ReserveOnTarget writes opReserve into the FSM holding capacity + name
	// for target before the body is forwarded to it. The reservation carries
	// the redacted spec + secret ref so the target's RecordPlacement promote
	// step can run with nil Spec/empty Secrets and inherit them
	// atomically. ttl bounds how long the reservation can hold capacity if
	// the target never promotes (the leader's GC sweep cancels expired rows
	// at ~5s tick cadence). Spec MUST already be redacted — the raft log
	// must NOT carry plaintext credentials.
	ReserveOnTarget(ctx context.Context, sandboxID string, target PlacementTarget, redacted *models.CreateSandboxRequest, secrets PlacementSecrets, ttl time.Duration) error

	// CancelReservation drops a pending reservation from the FSM. No-op on
	// missing or already-promoted (Placed) rows, so router rollback / TTL GC
	// / late successful promote can race harmlessly.
	CancelReservation(ctx context.Context, sandboxID string) error

	// SetNodeDrainState marks nodeID as drained (excluded from
	// SelectPlacement) or restores it to the candidate pool. Idempotent on
	// both edges. The mark lives in the FSM and survives the drained node
	// going away — the operator's intent must outlast the process they're
	// about to stop.
	SetNodeDrainState(ctx context.Context, nodeID string, drained bool) error

	// ReassignPlacement moves sandboxID to target without touching the
	// replicated spec or port intents. Used by WASM live migration once the
	// receiving node has imported a §4.8.1 checkpoint.
	ReassignPlacement(ctx context.Context, sandboxID string, target PlacementTarget) error

	// Platform-volume metadata replication. These keep a Daytona volume's
	// id/name/source consistent cluster-wide so get/list/delete-by-id survive the
	// tenant's API ownership moving between nodes. The data itself is
	// deterministic in S3/NFS and is never replicated.
	//
	// VolumeUpsert is an idempotent get-or-create: a duplicate (tenant, name)
	// converges on the existing row. It returns the canonical row and whether
	// this call created it, or ErrVolumeQuotaExceeded.
	VolumeUpsert(ctx context.Context, v models.Volume, maxPerTenant int) (models.Volume, bool, error)
	// VolumeDelete removes the (tenant, id) row, or returns ErrUnknownVolume.
	VolumeDelete(ctx context.Context, tenant, id string) error
	// VolumeByID / VolumeByName resolve a single row or return ErrUnknownVolume.
	VolumeByID(ctx context.Context, tenant, id string) (models.Volume, error)
	VolumeByName(ctx context.Context, tenant, name string) (models.Volume, error)
	// VolumesForTenant lists the tenant's rows, newest first.
	VolumesForTenant(ctx context.Context, tenant string) ([]models.Volume, error)
	// VolumeExistsForSource reports whether any replicated row points at source
	// (the reclaim worker's cluster-wide live-data guard).
	VolumeExistsForSource(ctx context.Context, source string) (bool, error)
	// VolumeAttachmentCount returns the cluster-wide live attachment count for a
	// volume. Put/Delete keep this index in the same raft log as volume metadata
	// so Daytona delete cannot miss a sandbox that lives on another worker.
	VolumeAttachmentCount(ctx context.Context, tenant, id string) (int, error)
	PutVolumeAttachments(ctx context.Context, attachments []models.VolumeAttachment) error
	DeleteVolumeAttachmentsForSandbox(ctx context.Context, sandboxID string) error

	// RemoveMember explicitly removes nodeID from the raft configuration after
	// marking it drained and orphaning any placements it owned. Unknown raft
	// members return ErrUnknownMember. Live members require force=true so an
	// operator cannot accidentally cut out a healthy server by typo.
	RemoveMember(ctx context.Context, nodeID string, force bool) error

	// IsNodeDrained reports whether nodeID is currently marked drained.
	// Reads the local FSM (no network hop). Used by observability endpoints
	// — placement scoring uses an internal accessor that takes one lock for
	// the whole sweep.
	IsNodeDrained(nodeID string) bool

	// ApplyEncoded is the receiving end of leader-forwarded raft writes. The
	// internal API endpoint pipes the request body through here on the leader
	// so any owner-side mutating call (Record/Upsert/Add/Remove/Delete) made on
	// a follower can transparently land on the leader's raft. Returns
	// ErrNotLeader if leadership has shifted; the forwarder retries.
	ApplyEncoded(ctx context.Context, payload []byte) error

	// AssertOwnership ensures the FSM lists self as owner for every entry in
	// local, and backfills any missing Spec / ExposedPorts so failover-recreate
	// works for sandboxes that pre-date the spec-replication features. Used at
	// boot. Idempotent.
	AssertOwnership(ctx context.Context, local []LocalSandboxState) error

	// ForwardHTTP reverse-proxies r to the given peer, copying response back to
	// w. Used by the API layer when OwnerOf != self. When target.InternalURL is
	// non-empty AND this node has its own TLS material loaded, the proxy rides
	// the cert-pinned mTLS channel; otherwise it falls back to target.APIURL
	// with PAT-only auth (the legacy public-API path).
	ForwardHTTP(target Endpoint, w http.ResponseWriter, r *http.Request)

	// AttachInternalHandler wires the API server's HTTP handler into the
	// cluster-internal mTLS listener so peers can reverse-proxy owner API calls
	// over the cert-pinned channel (not just leader-forwarded raft applies).
	// No-op for Noop and for Cluster instances with SB_CLUSTER_TLS_DIR unset.
	// Safe to call exactly once after construction; subsequent calls overwrite.
	AttachInternalHandler(h http.Handler)

	// Members returns a snapshot of all known cluster members.
	Members() []Member

	// IngressTargets aggregates live ingress-role nodes' gossiped PublicHost
	// values into the set of public addresses users must point DNS at for
	// custom domains. Hostnames and raw IPs are partitioned via net.ParseIP;
	// duplicates are removed; output ordering is stable so the API response
	// is byte-identical across calls when membership is unchanged. Source
	// reflects whether the cluster published a hostname, IPs, both, or
	// nothing usable (see models.IngressTargetSource*). Service-layer
	// IngressDNSTarget wraps this; clients hit GET /v1/ingress/dns.
	IngressTargets() models.IngressTarget

	// Placements returns the local FSM's hot placement snapshot. Recovery
	// payloads (Spec/secrets) are omitted; use PlacementOf/SpecOf for point
	// lookups that need them.
	Placements() []Placement

	// PlacementsForShards returns only placements whose sandbox ID belongs to
	// one of the requested placement shards. Ingress nodes use this instead of
	// pulling the full global placement map; server nodes serve it from the
	// FSM shard index and agent nodes delegate it to a server-role control
	// plane peer. Empty Shards means "all placements." Returned rows are hot
	// rows without Spec/secrets.
	PlacementsForShards(filter PlacementShardFilter) []Placement

	// PlacementPage returns a bounded global placement-index page sorted by
	// sandbox ID. It is the scalable read path for operators/control planes
	// that need to enumerate large clusters without asking every worker for
	// its local DB. Returned rows are hot rows without Spec/secrets.
	PlacementPage(req PlacementPageRequest) PlacementPageResponse

	// PlacementOf returns the full Placement record for sandboxID and true,
	// or a zero Placement and false if no record exists. Operator/debug
	// endpoints use this for convergence-status reads where the per-aspect
	// getters (OwnerOf/ExposedPortsOf) would lose the placement.Version
	// needed to compute "is this sandbox's route installed yet on this node".
	PlacementOf(sandboxID string) (Placement, bool)

	// PlacementVersion is the FSM's monotonic apply counter — bumps on every
	// raft log entry the FSM applied. Exposed for metrics/observability and
	// as a tie-breaker for tests; the ingress reconciler now uses
	// SubscribePlacement to wake on apply rather than polling this counter.
	// Zero means "no version data" (Noop or fresh cluster).
	PlacementVersion() uint64

	// SubscribePlacement returns a buffered (cap=1) channel that receives a
	// signal after every FSM apply on this node. The channel is fed directly
	// from FSM.Apply, so a leader-side commit reaches every node's
	// subscribers as soon as raft delivers the log entry — no poll interval.
	//
	// Multiple applies between reads collapse into one wake (cap=1, drops on
	// full). Cancel ctx (or the returned cancel func) to deregister; both
	// are safe to call multiple times. Callers MUST tolerate spurious wakes —
	// the channel says "something changed in the FSM," not "the placement
	// you care about changed."
	//
	// In single-node mode (Noop) the returned channel never fires; this is
	// safe to use in a select{} alongside a ticker because Go's select treats
	// a never-firing nil channel as permanently un-ready, not an error.
	SubscribePlacement(ctx context.Context) <-chan struct{}

	// Leader returns the node ID of the current Raft leader, empty if none.
	Leader() string

	// Close shuts down the cluster cleanly.
	Close() error
}

type Cluster struct {
	// contains filtered or unexported fields
}

type ClusterTLS struct {
	// contains filtered or unexported fields
}

type DrainStateResponse struct {
	Drained bool `json:"drained"`
}

type Endpoint struct {
	InternalURL string
	APIURL      string
}

type ExposedPortRoute struct {
	Protocol  string `json:"protocol"`
	HostPort  int    `json:"host_port,omitempty"`
	PublicURL string `json:"public_url,omitempty"`
}

type IngressRouteOwner struct {
	NodeID        string `json:"node_id"`
	APIURL        string `json:"api_url,omitempty"`
	InternalURL   string `json:"internal_url,omitempty"`
	DataPlaneHost string `json:"data_plane_host,omitempty"`
}

type IngressShardRoute struct {
	SandboxID  string              `json:"sandbox_id"`
	Shard      int                 `json:"shard"`
	ShardCount int                 `json:"shard_count"`
	Owners     []IngressRouteOwner `json:"owners"`
}

type LocalSandboxState struct {
	ID           string
	Spec         *models.CreateSandboxRequest
	Secrets      PlacementSecrets
	ExposedPorts map[int]ExposedPortRoute
	// CustomHostnames is the per-sandbox bound hostname set known to the
	// local store. Carried through AssertOwnership so a sandbox created before
	// the FSM learned about its hostnames (e.g. cluster mode enabled after the
	// sandbox already had custom domains) backfills the replicated set on
	// boot — without this a failover-recreate would lose the user's TLS
	// matchers.
	CustomHostnames []string
}

type Member struct {
	NodeID string `json:"node_id"`
	// NodeName is the operator-friendly display label (SB_NODE_NAME). Empty
	// for peers running pre-NodeName builds; dashboards fall back to NodeID.
	NodeName      string `json:"node_name,omitempty"`
	APIURL        string `json:"api_url"`
	DataPlaneHost string `json:"data_plane_host,omitempty"`
	RaftAddr      string `json:"raft_addr,omitempty"`
	// InternalURL is the cluster-internal mTLS endpoint used for raft
	// leader-forward applies. Empty when the peer is running without
	// SB_CLUSTER_TLS_DIR — the forwarder falls back to APIURL with PAT-only
	// auth in that case.
	InternalURL string `json:"internal_url,omitempty"`
	// Role is the peer's gossiped SB_NODE_ROLE. Empty for older builds that
	// pre-date the field; callers treat empty as the legacy "mixed" default.
	Role string `json:"role,omitempty"`
	// PublicHost is the peer's gossiped public ingress address
	// (config.EffectivePublicHost). Aggregated by Cluster.IngressTargets to
	// answer the DNS-helper API. Empty for peers without a public host set
	// or running pre-PublicHost builds.
	PublicHost string            `json:"public_host,omitempty"`
	Alive      bool              `json:"alive"`
	Capacity   capacity.Snapshot `json:"capacity"`
	// CapacityUpdatedUnix is when this node's last capacity heartbeat was
	// observed by the scheduler. CapacityStale means the last heartbeat is
	// missing or too old for placement admission.
	CapacityUpdatedUnix int64 `json:"capacity_updated_unix,omitempty"`
	CapacityStale       bool  `json:"capacity_stale,omitempty"`
}

type Noop struct {
	// contains filtered or unexported fields
}

type OwnerInfo struct {
	NodeID string
	APIURL string
	// InternalURL is the owner's cluster-internal mTLS URL. Empty when the
	// owner has no TLS material (mixed/legacy cluster). Owner API forwarding
	// uses this in preference to APIURL so the cross-node hop is cert-pinned.
	InternalURL string
	IsSelf      bool
}

type Placement struct {
	SandboxID           string              `json:"sandbox_id"`
	OwnerNodeID         string              `json:"owner_node_id"`
	OwnerAPIURL         string              `json:"owner_api_url"`
	OwnerDataPlaneHost  string              `json:"owner_data_plane_host,omitempty"`
	OwnerState          PlacementOwnerState `json:"owner_state,omitempty"`
	OrphanedOwnerNodeID string              `json:"orphaned_owner_node_id,omitempty"`
	OrphanedUnix        int64               `json:"orphaned_unix,omitempty"`
	Version             uint64              `json:"version"`
	CreatedUnix         int64               `json:"created_unix"`
	UpdatedUnix         int64               `json:"updated_unix"`
	// Name is the small, hot copy of Spec.Name used to rebuild the cluster-wide
	// uniqueness index without loading the larger recovery spec payload.
	Name string `json:"name,omitempty"`
	// RecoveryRef points at the out-of-snapshot recovery payload for this row.
	// Spec/secret fields are hydrated from that store only for point lookups and
	// recreate flows.
	RecoveryRef       string                       `json:"-"`
	Spec              *models.CreateSandboxRequest `json:"spec,omitempty"`
	SecretRef         string                       `json:"secret_ref,omitempty"`
	SecretVersion     int                          `json:"secret_version,omitempty"`
	ExposedPorts      map[int]string               `json:"exposed_ports,omitempty"`
	ExposedPortRoutes map[int]ExposedPortRoute     `json:"exposed_port_routes,omitempty"`
	// CustomHostnames is the replicated set of user-bound hostnames pointing at
	// this sandbox. Kept sorted and lower-cased so snapshot bytes are stable
	// across rebuilds and every node derives the same Caddy matcher order. The
	// FSM additionally maintains a hostname→sandboxID index so the TLS-ask
	// resolver and ingress reconciler can look up ownership in O(1) from any
	// node, including the ingress-only ones that don't run the local SQLite
	// custom-domains table. Hostnames are added/removed via the
	// opAddCustomDomain/opRemoveCustomDomain raft commands; opPlace preserves
	// the existing slice the same way ExposedPorts is preserved so a
	// re-place/reassign cannot erase domains a prior raft entry installed.
	CustomHostnames []string `json:"custom_hostnames,omitempty"`
	// State is empty for materialized placements (the historical schema) and
	// PlacementStateReserved for capacity-only intents that have not yet been
	// promoted by a successful local create. Reservations are eligible for
	// TTL-driven GC; opPlace transitions a reservation back to empty.
	State PlacementState `json:"state,omitempty"`
	// ExpiresUnix is meaningful only when State == PlacementStateReserved;
	// the leader GC sweep cancels rows whose ExpiresUnix < now.
	ExpiresUnix int64 `json:"expires_unix,omitempty"`
}

type PlacementLookupResponse struct {
	SandboxID string    `json:"sandbox_id"`
	Placement Placement `json:"placement"`
	Owner     OwnerInfo `json:"owner"`
	Orphaned  bool      `json:"orphaned"`
}

type PlacementOwnerState string

type PlacementPageRequest struct {
	Limit       int                  `json:"limit,omitempty"`
	PageToken   string               `json:"page_token,omitempty"`
	ShardFilter PlacementShardFilter `json:"shard_filter,omitempty"`
}

type PlacementPageResponse struct {
	Placements    []Placement `json:"placements"`
	NextPageToken string      `json:"next_page_token,omitempty"`
}

type PlacementReservation struct {
	SandboxID string
	Target    PlacementTarget
	Redacted  *models.CreateSandboxRequest
	Secrets   PlacementSecrets
	TTL       time.Duration
}

type PlacementSecrets struct {
	Ref     string `json:"ref,omitempty"`
	Version int    `json:"version,omitempty"`
}

type PlacementShardFilter struct {
	ShardCount int   `json:"shard_count,omitempty"`
	Shards     []int `json:"shards,omitempty"`
}

type PlacementState string

type PlacementTarget struct {
	NodeID        string
	APIURL        string
	DataPlaneHost string
	// InternalURL is the peer's cluster-internal mTLS URL (e.g. https://10.0.0.5:7002).
	// Empty when the peer is running without SB_CLUSTER_TLS_DIR or hasn't yet
	// gossiped its advertise URL. Cross-node create-forwarding uses this in
	// preference to APIURL so the hop rides the cert-pinned channel.
	InternalURL string
	IsSelf      bool
}

type RecoveryBlob struct {
	Ref           string                       `json:"ref"`
	SandboxID     string                       `json:"sandbox_id"`
	Spec          *models.CreateSandboxRequest `json:"spec,omitempty"`
	SecretRef     string                       `json:"secret_ref,omitempty"`
	SecretVersion int                          `json:"secret_version,omitempty"`
}

type SandboxRecreator interface {
	RecreateSandbox(ctx context.Context, id string, spec models.CreateSandboxRequest, secrets PlacementSecrets, exposedPorts map[int]ExposedPortRoute) error
}

type SelectPlacementRequest struct {
	Request capacity.Request `json:"request"`
}

type SelectPlacementResponse struct {
	Target PlacementTarget `json:"target"`
	Error  string          `json:"error,omitempty"`
}

type VolumeQueryResponse struct {
	Volume  *models.Volume  `json:"volume,omitempty"`
	Volumes []models.Volume `json:"volumes,omitempty"`
	Exists  bool            `json:"exists,omitempty"`
	Count   int             `json:"count,omitempty"`
}