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
- Variables
- func FilterLocalToPage(local []*models.Sandbox, placements []cluster.Placement, pageToken string) []*models.Sandbox
- func ListMode(c cluster.Client, r *http.Request) bool
- func OwnerRefFromContext(ctx context.Context) string
- func PageLocal(local []*models.Sandbox, limit int, pageToken string) ([]*models.Sandbox, string, error)
- func ParsePageParams(u *url.URL) (limit int, pageToken string)
- func PeerWantIDs(r *http.Request) (map[string]struct{}, error)
- func PlacementWantIDs(placements []cluster.Placement) map[string]struct{}
- func SelectPeers(c cluster.Client, ownerRef string) []cluster.Member
- func SelectPeersForPage(c cluster.Client, ownerRef, pageToken string, limit int) (peers []cluster.Member, placements []cluster.Placement, next string, ...)
- func StripFacadePagination(rawQuery string) string
- func WantsLocalPaging(u *url.URL) bool
- func WriteCoverageHeaders(w http.ResponseWriter, cov Coverage, nextPageToken string)
- type Coverage
- type FacadeListOptions
- type MemberLookup
- type Options
- type PeerClientProvider
- type PeerDialer
- type Result
- type Transport
Constants ¶
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 ¶
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
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 ¶
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 ¶
ParsePageParams reads limit/page_token from a request URL. pageToken is accepted as an alias for page_token (Daytona-style clients).
func PeerWantIDs ¶
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 ¶
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 ¶
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 ¶
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
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).
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 ¶
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
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 ¶
PeerClientProvider is implemented by cluster.Cluster / cluster.Agent.
type PeerDialer ¶
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.
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 ¶
TransportFromCluster extracts dial options when c implements PeerDialer.