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
- func FilterLocalToPage(local []*models.Sandbox, placements []cluster.Placement, pageToken string) []*models.Sandbox
- func OwnerRefFromContext(ctx context.Context) string
- 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 WriteCoverageHeaders(w http.ResponseWriter, cov Coverage, nextPageToken string)
- type Coverage
- 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 ¶
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 ¶
OwnerRefFromContext returns the tenant OwnerRef for non-operator callers.
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 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.
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
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.