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 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" 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 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
}
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, message string)
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
}