Documentation
¶
Index ¶
- Constants
- func CancelReservationBestEffort(ctx context.Context, svc *service.Service, logger *slog.Logger, ...)
- func CapacityRequestFromCreate(req models.CreateSandboxRequest) capacity.Request
- func CreateOnSelectedNode(ctx context.Context, svc *service.Service, logger *slog.Logger, ...) (*models.CreateSandboxResponse, error)
- func DeterministicSandboxID(ownerRef, key string) string
- func FormatPromoteError(err error) string
- func FormatSealError(err error) string
- func OverlapCreateAndPromote(ctx context.Context, svc *service.Service, logger *slog.Logger, ...) (*models.CreateSandboxResponse, error)
- func RollbackLocalCreate(ctx context.Context, svc *service.Service, logger *slog.Logger, ...)
- type CreateOptions
- type Decision
- type ErrorWriter
- type OverlapFailure
- type OverlapOptions
- type PrepareOptions
Constants ¶
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 )
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 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
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
FormatPromoteError matches the v1 handler's historical promote-fail message.
func FormatSealError ¶ added in v0.5.6
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.
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
}
func Prepare ¶
func Prepare(w http.ResponseWriter, r *http.Request, svc *service.Service, req models.CreateSandboxRequest, writeError ErrorWriter, opts PrepareOptions) (Decision, bool)
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
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 leaves the handle untenanted.
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
}