clusterlist

package
v0.6.8 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 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 ListMode added in v0.6.7

func ListMode(c cluster.Client, r *http.Request) bool

ListMode reports whether a list should fan out across the cluster: a real cluster client is attached (not the standalone Noop) and this is not itself a forwarded peer hop. It is the single definition E2B, Daytona and Runloop used to each copy (the per-facade clusterListMode).

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 FacadeListPage added in v0.6.7

func FacadeListPage[T any](r *http.Request, c cluster.Client, local []T, idFn func(T) string, opts FacadeListOptions) ([]T, Coverage, string, bool)

FacadeListPage merges one owner-scoped page of a facade's sandbox list across the cluster: it selects the peers that hold this page, filters the local rows to it, forwards the caller's credential, and returns (items, coverage, next-cursor, ok). ok == false means the placement view is not ready and the caller should answer 503. With no cluster — or on a forwarded peer hop — it returns local unchanged. idFn extracts an item's sandbox id.

This is the glue E2B and Daytona each copied verbatim (listFacadeClusterItems), differing only in the element type, the id accessor, and the route path (D12).

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 FacadeListOptions added in v0.6.7

type FacadeListOptions struct {
	// Path is the facade's list route the peer hop GETs (e.g. "/e2b/sandboxes").
	Path string
	// AuthHeader / APIKeyHeader are the caller's credentials to forward to the
	// peer so it scopes to the same tenant; a facade passes whichever its
	// inbound auth accepts (E2B accepts X-API-KEY).
	AuthHeader   string
	APIKeyHeader string
	// Warn logs a peer that failed to answer, if non-nil.
	Warn func(msg, peer string, err error)
}

FacadeListOptions configures FacadeListPage for one facade.

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
	// APIKeyHeader is the caller's X-API-KEY, for facades (E2B) whose inbound
	// auth accepts it instead of Authorization. Forwarded on the same mTLS hop
	// so an X-API-KEY-only caller's remote sandboxes are not dropped (B9).
	APIKeyHeader string
	RawQuery     string
	Path         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