clusterlist

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 2, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package clusterlist aggregates sandbox list reads across cluster owners. Used by /v1/sandboxes and the Daytona/E2B facades so enterprise topologies (thousands of workers) do not fan out to every alive peer.

Security: peer fetches require InternalURL + the caller's cert-pinned mTLS client. End-user Authorization is sent only over that mTLS channel. There is no public APIURL / fleet-PAT fallback (that path enabled cross-tenant enumeration on Daytona/E2B facades).

Index

Constants

View Source
const (
	// MaxConcurrentPeerReads bounds in-flight peer GETs during a list merge.
	MaxConcurrentPeerReads = 32
	// PeerTimeout is the per-peer HTTP budget; slow peers must not stall forever.
	PeerTimeout = 5 * time.Second
	// MergeTimeout caps the entire list merge across all peer waves.
	MergeTimeout = 5 * time.Second
	// DefaultPageLimit caps how many placement rows one list request hydrates.
	DefaultPageLimit = 100
	// MaxPageLimit is the hard ceiling for limit=.
	MaxPageLimit = 500
	// Coverage header names keep the /v1/sandboxes body a bare array (SDK wire
	// compat) while making partial results observable.
	HeaderPartial        = "X-Cluster-List-Partial"
	HeaderMissing        = "X-Cluster-List-Missing"
	HeaderPlacementReady = "X-Cluster-List-Placement-Ready"
	HeaderNextPageToken  = "X-Cluster-List-Next-Page-Token"
	HeaderAnswered       = "X-Cluster-List-Answered"
)

Variables

This section is empty.

Functions

func FilterLocalToPage

func FilterLocalToPage(local []*models.Sandbox, placements []cluster.Placement, pageToken string) []*models.Sandbox

FilterLocalToPage keeps local rows that appear on the current placement page. nil placements AND pageToken=="" (true cold start / small fleet) keeps all local rows. Non-nil empty placements (authoritative empty page) or a terminal pageToken with no rows returns an empty slice.

func OwnerRefFromContext

func OwnerRefFromContext(ctx context.Context) string

OwnerRefFromContext returns the tenant OwnerRef for non-operator callers.

func ParsePageParams

func ParsePageParams(u *url.URL) (limit int, pageToken string)

ParsePageParams reads limit/page_token from a request URL. pageToken is accepted as an alias for page_token (Daytona-style clients).

func PeerWantIDs

func PeerWantIDs(r *http.Request) (map[string]struct{}, error)

PeerWantIDs parses the exact sandbox-ID filter attached by an ingress list merge. Facade peer handlers must apply this before serializing their local inventory; filtering only after the response reaches ingress can turn a small placement page into an unbounded peer response and trip the body cap.

The filter is accepted only on a forwarded cluster hop. A missing ids key means the cold-start small-fleet fallback intentionally requested the full tenant-scoped local list; an explicitly empty ids key denies every row.

func PlacementWantIDs

func PlacementWantIDs(placements []cluster.Placement) map[string]struct{}

PlacementWantIDs builds the WantIDs set for Merge/MergeJSON from a placement page. nil placements means "no filter" (cold-start fan-out). A non-nil empty slice yields an empty map that denies every ID (authoritative empty page).

func SelectPeers

func SelectPeers(c cluster.Client, ownerRef string) []cluster.Member

SelectPeers is retained for tests; production list uses SelectPeersForPage.

func SelectPeersForPage

func SelectPeersForPage(c cluster.Client, ownerRef, pageToken string, limit int) (peers []cluster.Member, placements []cluster.Placement, next string, viewReady bool, missing []string)

SelectPeersForPage returns owner peers for one placement-index page plus the placement rows and next page token. Does not load the full placement view. missing lists placement owners that could not be reached (unknown/dead).

Authoritative empty pages (tenant or fleet has zero placements) return viewReady=true with peers=nil so callers respond 200 empty — not 503. viewReady=false only when PlacementPage failed / FSM not ready (non-authoritative).

func StripFacadePagination

func StripFacadePagination(rawQuery string) string

StripFacadePagination removes facade-specific pagination keys from a query string so peer fetches return full owner pages; the ingress applies facade pagination exactly once after the merge.

func WriteCoverageHeaders

func WriteCoverageHeaders(w http.ResponseWriter, cov Coverage, nextPageToken string)

WriteCoverageHeaders exposes completeness without changing the JSON body shape.

Types

type Coverage

type Coverage struct {
	Answered           []string `json:"answered"`
	Missing            []string `json:"missing"`
	Partial            bool     `json:"partial"`
	PlacementViewReady bool     `json:"placement_view_ready"`
}

Coverage reports which peers contributed to a merged list. Clients must treat Partial=true (or PlacementViewReady=false) as incomplete.

func MergeJSON

func MergeJSON[T any](ctx context.Context, peers []cluster.Member, local []T, idFn func(T) string, opts Options) (items []T, cov Coverage)

MergeJSON merges peer JSON arrays (facade list shapes) with the same transport rules.

type MemberLookup

type MemberLookup interface {
	LookupMember(id string) (cluster.Member, bool)
}

MemberLookup resolves one peer without scanning full membership.

type Options

type Options struct {
	OwnerRef string
	// AuthHeader is the caller's Authorization. Sent only on mTLS InternalURL.
	AuthHeader           string
	RawQuery             string
	Path                 string
	ForwardedHeaderName  string
	ForwardedHeaderValue string
	Local                []*models.Sandbox
	Transport            Transport
	// SelfNodeID is stamped on X-Cluster-Peer-Node-ID for inbound mTLS binding.
	SelfNodeID string
	// Limit/PageToken drive PlacementPage-backed peer selection.
	Limit     int
	PageToken string
	// WantIDs, when non-nil, drops peer/local rows whose ID is not in the set.
	// nil means no ID filter; empty non-nil map denies every ID.
	WantIDs map[string]struct{}
	Warn    func(msg string, peer string, err error)
}

Options controls cluster-wide list fan-out.

type PeerClientProvider

type PeerClientProvider interface {
	ClientForPeer(nodeID string) *http.Client
}

PeerClientProvider is implemented by cluster.Cluster / cluster.Agent.

type PeerDialer

type PeerDialer interface {
	PeerInternalHTTPClient() *http.Client
}

PeerDialer is implemented by cluster.Cluster / cluster.Agent.

type Result

type Result struct {
	Sandboxes     []*models.Sandbox `json:"sandboxes"`
	Coverage      Coverage          `json:"coverage"`
	NextPageToken string            `json:"next_page_token,omitempty"`
}

Result is one page of cluster-wide list hydration.

func Merge

func Merge(ctx context.Context, peers []cluster.Member, opts Options) Result

Merge hydrates one page of sandboxes from placement owners.

type Transport

type Transport struct {
	InternalClient *http.Client
	// PeerClient, when set, returns a cached per-node mTLS client (no transport
	// clone per dial). Cluster/Agent implement this via ClientForPeer.
	PeerClient func(nodeID string) *http.Client
}

Transport carries the cert-pinned cluster-internal mTLS client.

func TransportFromCluster

func TransportFromCluster(c cluster.Client) Transport

TransportFromCluster extracts dial options when c implements PeerDialer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL