prebuilds
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Index¶
- Variables
- func GenerateName() (string, error)
- type ActionType
- type Claimer
- type GlobalSnapshot
- type NoopClaimer
- type NoopReconciler
- func (NoopReconciler) CalculateActions(context.Context, PresetSnapshot) (*ReconciliationActions, error)
- func (NoopReconciler) ReconcileAll(context.Context) error
- func (NoopReconciler) ReconcilePreset(context.Context, PresetSnapshot) error
- func (NoopReconciler) Run(context.Context)
- func (NoopReconciler) SnapshotState(context.Context, database.Store) (*GlobalSnapshot, error)
- func (NoopReconciler) Stop(context.Context, error)
- func (NoopReconciler) TrackResourceReplacement(context.Context, uuid.UUID, uuid.UUID, []*sdkproto.ResourceReplacement)
- type PresetSnapshot
- type PubsubWorkspaceClaimListener
- type PubsubWorkspaceClaimPublisher
- type Reconciler
- type ReconciliationActions
- type ReconciliationOrchestrator
- type ReconciliationState
- type StateSnapshotter
Constants¶
This section is empty.
Variables¶
var (ErrNoClaimablePrebuiltWorkspaces =xerrors.New("no claimable prebuilt workspaces found")ErrAGPLDoesNotSupportPrebuiltWorkspaces =xerrors.New("prebuilt workspaces functionality is not supported under the AGPL license"))
var SystemUserID =uuid.MustParse("c42fdf75-3097-471c-8c33-fb52454d81c0")Functions¶
funcGenerateName¶added inv2.22.0
GenerateName generates a 20-byte prebuild name which should safe to use without truncation in most situations.UUIDs may be too long for a resource name in cloud providers (since this ID will be used in the prebuild's name).
We're generating a 9-byte suffix (72 bits of entropy):1 - e^(-1e9^2 / (2 * 2^72)) = ~0.01% likelihood of collision in 1 billion IDs.Seehttps://en.wikipedia.org/wiki/Birthday_attack.
Types¶
typeActionType¶added inv2.22.0
type ActionTypeint
ActionType represents the type of action needed to reconcile prebuilds.
const (// ActionTypeUndefined represents an uninitialized or invalid action type.ActionTypeUndefinedActionType =iota// ActionTypeCreate indicates that new prebuilds should be created.ActionTypeCreate// ActionTypeDelete indicates that existing prebuilds should be deleted.ActionTypeDelete// ActionTypeBackoff indicates that prebuild creation should be delayed.ActionTypeBackoff)
typeClaimer¶added inv2.22.0
type Claimer interface {Claim(ctxcontext.Context, userIDuuid.UUID, namestring, presetIDuuid.UUID) (*uuid.UUID,error)Initiator()uuid.UUID}var DefaultClaimerClaimer =NoopClaimer{}typeGlobalSnapshot¶added inv2.22.0
type GlobalSnapshot struct {Presets []database.GetTemplatePresetsWithPrebuildsRowRunningPrebuilds []database.GetRunningPrebuiltWorkspacesRowPrebuildsInProgress []database.CountInProgressPrebuildsRowBackoffs []database.GetPresetsBackoffRowHardLimitedPresets []database.GetPresetsAtFailureLimitRow}GlobalSnapshot represents a full point-in-time snapshot of state relating to prebuilds across all templates.
funcNewGlobalSnapshot¶added inv2.22.0
func NewGlobalSnapshot(presets []database.GetTemplatePresetsWithPrebuildsRow,runningPrebuilds []database.GetRunningPrebuiltWorkspacesRow,prebuildsInProgress []database.CountInProgressPrebuildsRow,backoffs []database.GetPresetsBackoffRow,hardLimitedPresets []database.GetPresetsAtFailureLimitRow,)GlobalSnapshot
func (GlobalSnapshot)FilterByPreset¶added inv2.22.0
func (sGlobalSnapshot) FilterByPreset(presetIDuuid.UUID) (*PresetSnapshot,error)
typeNoopClaimer¶added inv2.22.0
type NoopClaimer struct{}func (NoopClaimer)Initiator¶added inv2.22.0
func (NoopClaimer) Initiator()uuid.UUID
typeNoopReconciler¶added inv2.22.0
type NoopReconciler struct{}func (NoopReconciler)CalculateActions¶added inv2.22.0
func (NoopReconciler) CalculateActions(context.Context,PresetSnapshot) (*ReconciliationActions,error)
func (NoopReconciler)ReconcileAll¶added inv2.22.0
func (NoopReconciler) ReconcileAll(context.Context)error
func (NoopReconciler)ReconcilePreset¶added inv2.22.0
func (NoopReconciler) ReconcilePreset(context.Context,PresetSnapshot)error
func (NoopReconciler)Run¶added inv2.22.0
func (NoopReconciler) Run(context.Context)
func (NoopReconciler)SnapshotState¶added inv2.22.0
func (NoopReconciler) SnapshotState(context.Context,database.Store) (*GlobalSnapshot,error)
func (NoopReconciler)TrackResourceReplacement¶added inv2.22.0
func (NoopReconciler) TrackResourceReplacement(context.Context,uuid.UUID,uuid.UUID, []*sdkproto.ResourceReplacement)
typePresetSnapshot¶added inv2.22.0
type PresetSnapshot struct {Presetdatabase.GetTemplatePresetsWithPrebuildsRowRunning []database.GetRunningPrebuiltWorkspacesRowExpired []database.GetRunningPrebuiltWorkspacesRowInProgress []database.CountInProgressPrebuildsRowBackoff *database.GetPresetsBackoffRowIsHardLimitedbool}PresetSnapshot is a filtered view of GlobalSnapshot focused on a single preset.It contains the raw data needed to calculate the current state of a preset's prebuilds,including running prebuilds, in-progress builds, and backoff information.- Running: prebuilds running and non-expired- Expired: prebuilds running and expired due to the preset's TTL- InProgress: prebuilds currently in progress- Backoff: holds failure info to decide if prebuild creation should be backed off
func (PresetSnapshot)CalculateActions¶added inv2.22.0
func (pPresetSnapshot) CalculateActions(clockquartz.Clock, backoffIntervaltime.Duration) ([]*ReconciliationActions,error)
CalculateActions determines what actions are needed to reconcile the current state with the desired state.The function:1. First checks if a backoff period is needed (if previous builds failed)2. If the preset is inactive (template version is not active), it will delete all running prebuilds3. For active presets, it calculates the number of prebuilds to create or delete based on:
- The desired number of instances
- Currently running prebuilds
- Currently running expired prebuilds
- Prebuilds in transition states (starting/stopping/deleting)
- Any extraneous prebuilds that need to be removed
The function returns a ReconciliationActions struct that will have exactly one action type set:- ActionTypeBackoff: Only BackoffUntil is set, indicating when to retry- ActionTypeCreate: Only Create is set, indicating how many prebuilds to create- ActionTypeDelete: Only DeleteIDs is set, containing IDs of prebuilds to delete
func (PresetSnapshot)CalculateState¶added inv2.22.0
func (pPresetSnapshot) CalculateState() *ReconciliationState
CalculateState computes the current state of prebuilds for a preset, including:- Actual: Number of currently running prebuilds, i.e., non-expired and expired prebuilds- Expired: Number of currently running expired prebuilds- Desired: Number of prebuilds desired as defined in the preset- Eligible: Number of prebuilds that are ready to be claimed- Extraneous: Number of extra running prebuilds beyond the desired count- Starting/Stopping/Deleting: Counts of prebuilds in various transition states
The function takes into account whether the preset is active (using the active template version)and calculates appropriate counts based on the current state of running prebuilds andin-progress transitions. This state information is used to determine what reconciliationactions are needed to reach the desired state.
typePubsubWorkspaceClaimListener¶added inv2.22.0
type PubsubWorkspaceClaimListener struct {// contains filtered or unexported fields}funcNewPubsubWorkspaceClaimListener¶added inv2.22.0
func NewPubsubWorkspaceClaimListener(pspubsub.Pubsub, loggerslog.Logger) *PubsubWorkspaceClaimListener
func (PubsubWorkspaceClaimListener)ListenForWorkspaceClaims¶added inv2.22.0
func (pPubsubWorkspaceClaimListener) ListenForWorkspaceClaims(ctxcontext.Context, workspaceIDuuid.UUID, reinitEvents chan<-agentsdk.ReinitializationEvent) (func(),error)
ListenForWorkspaceClaims subscribes to a pubsub channel and sends any received events on the chan that it returns.pubsub.Pubsub does not communicate when its last callback has been called after it has been closed. As such the chanreturned by this method is never closed. Call the returned cancel() function to close the subscription when it is no longer needed.cancel() will be called if ctx expires or is canceled.
typePubsubWorkspaceClaimPublisher¶added inv2.22.0
type PubsubWorkspaceClaimPublisher struct {// contains filtered or unexported fields}funcNewPubsubWorkspaceClaimPublisher¶added inv2.22.0
func NewPubsubWorkspaceClaimPublisher(pspubsub.Pubsub) *PubsubWorkspaceClaimPublisher
func (PubsubWorkspaceClaimPublisher)PublishWorkspaceClaim¶added inv2.22.0
func (pPubsubWorkspaceClaimPublisher) PublishWorkspaceClaim(claimagentsdk.ReinitializationEvent)error
typeReconciler¶added inv2.22.0
type Reconciler interface {StateSnapshotter// ReconcileAll orchestrates the reconciliation of all prebuilds across all templates.// It takes a global snapshot of the system state and then reconciles each preset// in parallel, creating or deleting prebuilds as needed to reach their desired states.ReconcileAll(ctxcontext.Context)error}typeReconciliationActions¶added inv2.22.0
type ReconciliationActions struct {// ActionType determines which field is set and what action should be takenActionTypeActionType// Create is set when ActionType is ActionTypeCreate and indicates the number of prebuilds to createCreateint32// DeleteIDs is set when ActionType is ActionTypeDelete and contains the IDs of prebuilds to deleteDeleteIDs []uuid.UUID// BackoffUntil is set when ActionType is ActionTypeBackoff and indicates when to retry creating prebuildsBackoffUntiltime.Time}ReconciliationActions represents actions needed to reconcile the current state with the desired state.Based on ActionType, exactly one of Create, DeleteIDs, or BackoffUntil will be set.
func (*ReconciliationActions)IsNoop¶added inv2.22.0
func (ra *ReconciliationActions) IsNoop()bool
typeReconciliationOrchestrator¶added inv2.22.0
type ReconciliationOrchestrator interface {Reconciler// Run starts a continuous reconciliation loop that periodically calls ReconcileAll// to ensure all prebuilds are in their desired states. The loop runs until the context// is canceled or Stop is called.Run(ctxcontext.Context)// Stop gracefully shuts down the orchestrator with the given cause.// The cause is used for logging and error reporting.Stop(ctxcontext.Context, causeerror)// TrackResourceReplacement handles a pathological situation whereby a terraform resource is replaced due to drift,// which can obviate the whole point of pre-provisioning a prebuilt workspace.// See more detail athttps://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces#preventing-resource-replacement.TrackResourceReplacement(ctxcontext.Context, workspaceID, buildIDuuid.UUID, replacements []*sdkproto.ResourceReplacement)}ReconciliationOrchestrator manages the lifecycle of prebuild reconciliation.It runs a continuous loop to check and reconcile prebuild states, and can be stopped gracefully.
var DefaultReconcilerReconciliationOrchestrator =NoopReconciler{}typeReconciliationState¶added inv2.22.0
type ReconciliationState struct {Actualint32// Number of currently running prebuilds, i.e., non-expired, expired and extraneous prebuildsExpiredint32// Number of currently running prebuilds that exceeded their allowed time-to-live (TTL)Desiredint32// Number of prebuilds desired as defined in the presetEligibleint32// Number of prebuilds that are ready to be claimedExtraneousint32// Number of extra running prebuilds beyond the desired count// Counts of prebuilds in various transition statesStartingint32Stoppingint32Deletingint32}ReconciliationState represents the processed state of a preset's prebuilds,calculated from a PresetSnapshot. While PresetSnapshot contains raw data,ReconciliationState contains derived metrics that are directly used todetermine what actions are needed (create, delete, or backoff).For example, it calculates how many prebuilds are expired, eligible,how many are extraneous, and how many are in various transition states.
typeStateSnapshotter¶added inv2.22.0
type StateSnapshotter interface {// SnapshotState captures the current state of all prebuilds across templates.// It creates a global database snapshot that can be viewed as a collection of PresetSnapshots,// each representing the state of prebuilds for a specific preset.// MUST be called inside a repeatable-read transaction.SnapshotState(ctxcontext.Context, storedatabase.Store) (*GlobalSnapshot,error)}StateSnapshotter defines the operations necessary to capture workspace prebuilds state.
Source Files