clusterlist

package
v0.6.6 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 14 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

View Source
var ErrInvalidPageToken = errors.New("invalid page_token")

ErrInvalidPageToken is returned for a page_token PageLocal didn't issue.

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 PageLocal added in v0.6.5

func PageLocal(local []*models.Sandbox, limit int, pageToken string) ([]*models.Sandbox, string, error)

PageLocal pages a single-node list in sandbox-ID order, the same order the cluster placement index pages in, so a client that loops on the next-page header behaves identically in both modes. The token is opaque to clients and carries only the last ID returned; a sandbox created or destroyed between pages shifts nothing already returned.

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 WantsLocalPaging added in v0.6.5

func WantsLocalPaging(u *url.URL) bool

WantsLocalPaging reports whether a single-node list request asked for pages. Only an explicit limit or page_token turns paging on: older SDKs that never send either keep getting the whole list in one response, as single-node always returned before.

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