chore: comment query

coder · DanielleMaywood · Nov 13, 2024 · Nov 7, 2024 · Nov 7, 2024 · Nov 7, 2024
commit 18e9550d24f62f73ed9ea620e1c633ca61376a2b
diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/workspaces.sql b/coderd/database/queries/workspaces.sql
@@ -580,7 +580,11 @@ WHERE
 	) AND
 
 	(
-		-- isEligibleForAutostop
+		-- A workspace may be eligible for autostop if the following are true:
+		--   * The provisioner job has not failed.
+		--   * The workspace is not dormant.
+		--   * The workspace build was a start transition.
+		--   * The workspace's owner is suspended OR the workspace build deadline has passed.
 		(
 			provisioner_jobs.job_status != 'failed'::provisioner_job_status AND
 			workspaces.dormant_at IS NULL AND
@@ -592,22 +596,33 @@ WHERE
 			)
 		) OR
 
-		-- isEligibleForAutostart
+		-- A workspace may be eligible for autostart if the following are true:
+		--   * The workspace's owner is active.
+		--   * The provisioner job did not failed.
+		--   * The workspace build was a stop transition.
+		--   * The workspace has an autostart schedule.
 		(
 			users.status = 'active'::user_status AND
 			provisioner_jobs.job_status != 'failed'::provisioner_job_status AND
 			workspace_builds.transition = 'stop'::workspace_transition AND
 			workspaces.autostart_schedule IS NOT NULL
 		) OR
 
-		-- isEligibleForDormantStop
+		-- A workspace may be eligible for dormant stop if the following are true:
+		--   * The workspace is not dormant.
 // isEligibleForDormantStop returns true if the workspace should be dormant 
 // for breaching the inactivity threshold of the template. 
 func isEligibleForDormantStop(ws database.Workspace, templateSchedule schedule.TemplateScheduleOptions, currentTick time.Time) bool { 
 	// Only attempt against workspaces not already dormant. 
 	return !ws.DormantAt.Valid && 
 		// The template must specify an time_til_dormant value. 
 		templateSchedule.TimeTilDormant > 0 && 
 		// The workspace must breach the time_til_dormant value. 
 		currentTick.Sub(ws.LastUsedAt) > templateSchedule.TimeTilDormant 
 } 
 case isEligibleForDormantStop(ws, templateSchedule, currentTick): 
 	// Only stop started workspaces. 
 	if latestBuild.Transition == database.WorkspaceTransitionStart { 
 		return database.WorkspaceTransitionStop, database.BuildReasonDormancy, nil 
 	} 
 	// We shouldn't transition the workspace but we sho
8000
uld still 
 	// make it dormant. 
 	return "", database.BuildReasonDormancy, nil 
 // Transition the workspace to dormant if it has breached the template's 
 // threshold for inactivity. 
 if reason == database.BuildReasonDormancy { 
 	wsOld := ws 
 	wsNew, err := tx.UpdateWorkspaceDormantDeletingAt(e.ctx, database.UpdateWorkspaceDormantDeletingAtParams{ 
 		ID: ws.ID, 
 		DormantAt: sql.NullTime{ 
 			Time:  dbtime.Now(), 
 			Valid: true, 
 		}, 
 	}) 
 // isEligibleForDormantStop returns true if the workspace should be dormant 
 // for breaching the inactivity threshold of the template. 
 func isEligibleForDormantStop(ws database.Workspace, templateSchedule schedule.TemplateScheduleOptions, currentTick time.Time) bool { 
 	// Only attempt against workspaces not already dormant. 
 	return !ws.DormantAt.Valid && 
 		// The template must specify an time_til_dormant value. 
 		templateSchedule.TimeTilDormant > 0 && 
 		// The workspace must breach the time_til_dormant value. 
 		currentTick.Sub(ws.LastUsedAt) > templateSchedule.TimeTilDormant 
 } 
 case isEligibleForDormantStop(ws, templateSchedule, currentTick): 
 	// Only stop started workspaces. 
 	if latestBuild.Transition == database.WorkspaceTransitionStart { 
 		return database.WorkspaceTransitionStop, database.BuildReasonDormancy, nil 
 	} 
 	// We shouldn't transition the workspace but we sho
8000
uld still 
 	// make it dormant. 
 	return "", database.BuildReasonDormancy, nil 
 // Transition the workspace to dormant if it has breached the template's 
 // threshold for inactivity. 
 if reason == database.BuildReasonDormancy { 
 	wsOld := ws 
 	wsNew, err := tx.UpdateWorkspaceDormantDeletingAt(e.ctx, database.UpdateWorkspaceDormantDeletingAtParams{ 
 		ID: ws.ID, 
 		DormantAt: sql.NullTime{ 
 			Time:  dbtime.Now(), 
 			Valid: true, 
 		}, 
 	}) 
+		--   * The template has set a time til dormant.
+		--   * The workspace has been unused for longer than the time til dormancy.
 		(
 			workspaces.dormant_at IS NULL AND
 			templates.time_til_dormant > 0 AND
 			(@now :: timestamptz) - workspaces.last_used_at > (INTERVAL '1 millisecond' * (templates.time_til_dormant / 1000000))
 		) OR
 
-		-- isEligibleForDelete
+		-- A workspace may be eligible for deletion if the following are true:
+		--   * The workspace is dormant.
+		--   * The workspace is scheduled to be deleted.
+		--   * If there was a prior attempt to delete the workspace that failed:
+		--      * This attempt was at least 24 hours ago>
 		(
 			workspaces.dormant_at IS NOT NULL AND
 			workspaces.deleting_at IS NOT NULL AND
@@ -632,11 +647,16 @@ WHERE
 			END
 		) OR
 
-		-- isEligibleForFailedStop
+		-- A workspace may be eligible for failed stop if the following are true:
+		--   * The template has a failure ttl set.
+		--   * The workspace build was a start transition.
 // isEligibleForFailedStop returns true if the workspace is eligible to be stopped 
 // due to a failed build. 
 func isEligibleForFailedStop(build database.WorkspaceBuild, job database.ProvisionerJob, templateSchedule schedule.TemplateScheduleOptions, currentTick time.Time) bool { 
 	// If the template has specified a failure TLL. 
 	return templateSchedule.FailureTTL > 0 && 
 		// And the job resulted in failure. 
 		job.JobStatus == database.ProvisionerJobStatusFailed && 
 		build.Transition == database.WorkspaceTransitionStart && 
 		// And sufficient time has elapsed since the job has completed. 
 		job.CompletedAt.Valid && 
 		currentTick.Sub(job.CompletedAt.Time) > templateSchedule.FailureTTL 
 } 
 // isEligibleForFailedStop returns true if the workspace is eligible to be stopped 
 // due to a failed build. 
 func isEligibleForFailedStop(build database.WorkspaceBuild, job database.ProvisionerJob, templateSchedule schedule.TemplateScheduleOptions, currentTick time.Time) bool { 
 	// If the template has specified a failure TLL. 
 	return templateSchedule.FailureTTL > 0 && 
 		// And the job resulted in failure. 
 		job.JobStatus == database.ProvisionerJobStatusFailed && 
 		build.Transition == database.WorkspaceTransitionStart && 
 		// And sufficient time has elapsed since the job has completed. 
 		job.CompletedAt.Valid && 
 		currentTick.Sub(job.CompletedAt.Time) > templateSchedule.FailureTTL 
 } 
+		--   * The provisioner job failed.
+		--   * The provisioner job had completed.
+		--   * The provisioner job has been completed for longer than the failure ttl.
 		(
 			templates.failure_ttl > 0 AND
-			provisioner_jobs.job_status = 'failed'::provisioner_job_status AND
 			workspace_builds.transition = 'start'::workspace_transition AND
+			provisioner_jobs.job_status = 'failed'::provisioner_job_status AND
 			provisioner_jobs.completed_at IS NOT NULL AND
 			(@now :: timestamptz) - provisioner_jobs.completed_at > (INTERVAL '1 millisecond' * (templates.failure_ttl / 1000000))
 		)