clustercreate

package
v0.6.12 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	HeaderTarget = "X-Cluster-Create-Target"
	HeaderID     = "X-Cluster-Create-ID"

	// HeaderIdempotencyKey is the client-supplied create idempotency key the
	// v1 and Daytona surfaces honor. It is opt-in: a create without it keeps
	// the default mint-fresh-every-call behaviour, so two deliberate identical
	// POSTs still make two sandboxes (unlike E2B, which is content-addressed).
	HeaderIdempotencyKey = "Idempotency-Key"

	ReservationTTL = 120 * time.Second
)
View Source
const (
	OverlapPhaseCreate  = "create"
	OverlapPhaseSeal    = "seal"
	OverlapPhasePromote = "promote"
)

OverlapPhase names which step failed on the overlapped reserved-path create. Handlers use errors.As(*OverlapFailure) to map to the right HTTP status.

Variables

This section is empty.

Functions

func CancelReservationBestEffort

func CancelReservationBestEffort(ctx context.Context, svc *service.Service, logger *slog.Logger, sandboxID string)

func CapacityRequestFromCreate

func CapacityRequestFromCreate(req models.CreateSandboxRequest) capacity.Request

func CreateOnSelectedNode

func CreateOnSelectedNode(ctx context.Context, svc *service.Service, logger *slog.Logger, req models.CreateSandboxRequest, reservationID string, opts CreateOptions) (*models.CreateSandboxResponse, error)

func DeterministicSandboxID added in v0.6.7

func DeterministicSandboxID(ownerRef, key string) string

DeterministicSandboxID derives a stable sandbox id from an owner reference and a caller-supplied idempotency key, so a retried create (same owner, same key) resolves to the same id and is deduplicated by the reservation / CreateSandboxWithID fast path instead of minting a second sandbox. It returns "" when key is blank — the caller then mints a fresh random id and the create is not idempotent, which keeps the mechanism opt-in. The owner is mixed in so two tenants that happen to choose the same key never collide, and so a derived id satisfies CreateSandboxWithID's owner check on replay. The shape ("sb-" + 16 hex) matches service.GenerateSandboxID, so the id is a valid container name and is indistinguishable downstream from a random one.

func FormatPromoteError added in v0.5.6

func FormatPromoteError(err error) string

FormatPromoteError matches the v1 handler's historical promote-fail message.

func FormatSealError added in v0.5.6

func FormatSealError(err error) string

FormatSealError matches the v1 handler's historical seal-fail message.

func OverlapCreateAndPromote added in v0.5.6

func OverlapCreateAndPromote(
	ctx context.Context,
	svc *service.Service,
	logger *slog.Logger,
	req models.CreateSandboxRequest,
	reservationID string,
	opts OverlapOptions,
) (*models.CreateSandboxResponse, error)

OverlapCreateAndPromote runs CreateSandboxWithID in parallel with SealAndDistribute (the seal), joins both, and only then promotes via RecordPlacement (plans/warm-create-latency-tier1.5-seal-promote-overlap.md).

Promote is deliberately NOT overlapped with the create. The FSM releases the pending-reservation accounting on opPlace, and that accounting is what ClusterCreateMaxPendingPerWorker backpressure and SelectPlacement's double-booking guard count — promoting early would uncharge an in-flight local create. It is also what keeps the placement invisible to the owner watcher, which would otherwise start a concurrent recreate of a failover-enabled sandbox whose local create outlives one 5s watcher tick. The row must stay Reserved until the local create has succeeded.

Reserved path only — reservationID must be non-empty. The local-image CreateSandbox path (no ID) stays sequential at the call site.

func RollbackLocalCreate added in v0.6.1

func RollbackLocalCreate(ctx context.Context, svc *service.Service, logger *slog.Logger, sandboxID string)

RollbackLocalCreate retracts a non-reserved local create. Placement release is conditional on complete local destruction: retaining the row and its lifecycle identity is safer than creating an untracked live runtime when a runtime, secret, or store finalizer fails.

The retained row is marked rollback-pending first, so the ownership replay does not place it (here there is no placement at all, so the replay would create one) and reconcile finishes the destroy (markRollbackPending).

Types

type CreateOptions

type CreateOptions struct {
	PromoteWithSpec bool
	// SandboxID is the id an UNRESERVED create uses. Prepare deliberately
	// returns no reservation for local-only images (local snapshots, mapped
	// built images), so a facade that derives a retry-stable id must not
	// pass that id as reservationID — no reservation exists under it and
	// the reserved path would refuse the create. Empty generates an id.
	SandboxID string
}

type Decision

type Decision struct {
	ReservationID string
	// contains filtered or unexported fields
}

func (Decision) RecordReserveStages added in v0.6.12

func (d Decision) RecordReserveStages(timing *createtiming.CreateTiming)

RecordReserveStages adds the router's cluster_place and cluster_reserve stages to the local create's recorder, so its Server-Timing covers the time before create;dur started. Nil-safe; a Decision from a forwarded create carries none (the router reports its own, see forwardReservedCreate).

type ErrorWriter

type ErrorWriter func(w http.ResponseWriter, status int, code, message string)

ErrorWriter renders one error in the calling facade's envelope. code is models.ErrorResponse.Code for surfaces that carry it (v1, Daytona); E2B and Runloop ignore it and render their own shapes (and Runloop's x-should-retry).

type OverlapFailure added in v0.5.6

type OverlapFailure struct {
	Phase string
	Err   error
}

OverlapFailure is returned when the create leg, seal leg, or the post-join promote fails. Retract has already been attempted; the handler should surface Err (not invent a new shape). Phase distinguishes create vs seal vs promote for status mapping.

func AsOverlapFailure added in v0.5.6

func AsOverlapFailure(err error) (*OverlapFailure, bool)

AsOverlapFailure extracts an OverlapFailure from err, if present.

func (*OverlapFailure) Error added in v0.5.6

func (f *OverlapFailure) Error() string

func (*OverlapFailure) Unwrap added in v0.5.6

func (f *OverlapFailure) Unwrap() error

type OverlapOptions added in v0.5.6

type OverlapOptions struct {
	// PromoteWithSpec includes the redacted create request in RecordPlacement.
	// v1 always wants true; Daytona/E2B facades pass true; helpers that rely
	// on the reservation-held spec pass false.
	PromoteWithSpec bool
	Timing          *createtiming.CreateTiming
}

OverlapOptions configures reserved-path create∥seal.

type PrepareOptions

type PrepareOptions struct {
	PreferredSandboxID string
	// Normalize runs after the shared create normalizations and before
	// placement. v1 uses it to settle runtime/template_id, which decides
	// which workers are even eligible. Facades translate their own wire
	// shape first and pass nil.
	Normalize func(*models.CreateSandboxRequest) error
	// OwnerRef is the tenant account recorded on the reservation's secret
	// handle. Empty takes the caller's owner (service.OwnerRefForCreate), so
	// a team's reservation always counts against its quota.
	OwnerRef string
	// SyncBody re-marshals the normalized request into r.Body so a forwarded
	// create carries the normalizations the router applied. Native v1 sets
	// this because the peer re-decodes the same CreateSandboxRequest shape;
	// facades must NOT, because they forward their own wire body and
	// re-translate it on the target.
	SyncBody bool
	// MetricPrefix labels idempotency-conflict metrics. Defaults to
	// "cluster.create" when empty.
	MetricPrefix string
	// OnForwardStale fires when a forwarded create lands on the wrong node.
	OnForwardStale func()
	// Logger, when set, records placement decisions worth tracing.
	Logger *slog.Logger
}

Jump to

Keyboard shortcuts

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