feat(agent): Add shutdown lifecycle states and shutdown_script support (#6139)

* feat(api): Add agent shutdown lifecycle states

* feat(agent): Add shutdown_script support

* feat(agent): Add shutdown_script timeout

* feat(site): Support new agent lifecycle states

---

Co-authored-by: Marcin Tojek <marcin@coder.com>

codersdk/agentsdk/agentsdk.go

@@ -69,15 +69,17 @@ type Metadata struct {
 	// GitAuthConfigs stores the number of Git configurations
 	// the Coder deployment has. If this number is >0, we
 	// set up special configuration in the workspace.
-	GitAuthConfigs       int                     `json:"git_auth_configs"`
-	VSCodePortProxyURI   string                  `json:"vscode_port_proxy_uri"`
-	Apps                 []codersdk.WorkspaceApp `json:"apps"`
-	DERPMap              *tailcfg.DERPMap        `json:"derpmap"`
-	EnvironmentVariables map[string]string       `json:"environment_variables"`
-	StartupScript        string                  `json:"startup_script"`
-	StartupScriptTimeout time.Duration           `json:"startup_script_timeout"`
-	Directory            string                  `json:"directory"`
-	MOTDFile             string                  `json:"motd_file"`
+	GitAuthConfigs        int                     `json:"git_auth_configs"`
+	VSCodePortProxyURI    string                  `json:"vscode_port_proxy_uri"`
+	Apps                  []codersdk.WorkspaceApp `json:"apps"`
+	DERPMap               *tailcfg.DERPMap        `json:"derpmap"`
+	EnvironmentVariables  map[string]string       `json:"environment_variables"`
+	StartupScript         string                  `json:"startup_script"`
+	StartupScriptTimeout  time.Duration           `json:"startup_script_timeout"`
+	Directory             string                  `json:"directory"`
+	MOTDFile              string                  `json:"motd_file"`
+	ShutdownScript        string                  `json:"shutdown_script"`
+	ShutdownScriptTimeout time.Duration           `json:"shutdown_script_timeout"`
 }
 
 // Metadata fetches metadata for the currently authenticated workspace agent.

codersdk/workspaceagents.go

@@ -44,13 +44,35 @@ type WorkspaceAgentLifecycle string
 
 // WorkspaceAgentLifecycle enums.
 const (
-	WorkspaceAgentLifecycleCreated      WorkspaceAgentLifecycle = "created"
-	WorkspaceAgentLifecycleStarting     WorkspaceAgentLifecycle = "starting"
-	WorkspaceAgentLifecycleStartTimeout WorkspaceAgentLifecycle = "start_timeout"
-	WorkspaceAgentLifecycleStartError   WorkspaceAgentLifecycle = "start_error"
-	WorkspaceAgentLifecycleReady        WorkspaceAgentLifecycle = "ready"
+	WorkspaceAgentLifecycleCreated         WorkspaceAgentLifecycle = "created"
+	WorkspaceAgentLifecycleStarting        WorkspaceAgentLifecycle = "starting"
+	WorkspaceAgentLifecycleStartTimeout    WorkspaceAgentLifecycle = "start_timeout"
+	WorkspaceAgentLifecycleStartError      WorkspaceAgentLifecycle = "start_error"
+	WorkspaceAgentLifecycleReady           WorkspaceAgentLifecycle = "ready"
+	WorkspaceAgentLifecycleShuttingDown    WorkspaceAgentLifecycle = "shutting_down"
+	WorkspaceAgentLifecycleShutdownTimeout WorkspaceAgentLifecycle = "shutdown_timeout"
+	WorkspaceAgentLifecycleShutdownError   WorkspaceAgentLifecycle = "shutdown_error"
+	WorkspaceAgentLifecycleOff             WorkspaceAgentLifecycle = "off"
 )
 
+// WorkspaceAgentLifecycleOrder is the order in which workspace agent
+// lifecycle states are expected to be reported during the lifetime of
+// the agent process. For instance, the agent can go from starting to
+// ready without reporting timeout or error, but it should not go from
+// ready to starting. This is merely a hint for the agent process, and
+// is not enforced by the server.
+var WorkspaceAgentLifecycleOrder = []WorkspaceAgentLifecycle{
+	WorkspaceAgentLifecycleCreated,
+	WorkspaceAgentLifecycleStarting,
+	WorkspaceAgentLifecycleStartTimeout,
+	WorkspaceAgentLifecycleStartError,
+	WorkspaceAgentLifecycleReady,
+	WorkspaceAgentLifecycleShuttingDown,
+	WorkspaceAgentLifecycleShutdownTimeout,
+	WorkspaceAgentLifecycleShutdownError,
+	WorkspaceAgentLifecycleOff,
+}
+
 type WorkspaceAgent struct {
 	ID                   uuid.UUID               `json:"id" format:"uuid"`
 	CreatedAt            time.Time               `json:"created_at" format:"date-time"`
@@ -76,9 +98,11 @@ type WorkspaceAgent struct {
 	ConnectionTimeoutSeconds int32                 `json:"connection_timeout_seconds"`
 	TroubleshootingURL       string                `json:"troubleshooting_url"`
 	// LoginBeforeReady if true, the agent will delay logins until it is ready (e.g. executing startup script has ended).
-	LoginBeforeReady bool `db:"login_before_ready" json:"login_before_ready"`
+	LoginBeforeReady bool `json:"login_before_ready"`
 	// StartupScriptTimeoutSeconds is the number of seconds to wait for the startup script to complete. If the script does not complete within this time, the agent lifecycle will be marked as start_timeout.
-	StartupScriptTimeoutSeconds int32 `db:"startup_script_timeout_seconds" json:"startup_script_timeout_seconds"`
+	StartupScriptTimeoutSeconds  int32  `json:"startup_script_timeout_seconds"`
+	ShutdownScript               string `json:"shutdown_script,omitempty"`
+	ShutdownScriptTimeoutSeconds int32  `json:"shutdown_script_timeout_seconds"`
 }
 
 type DERPRegion struct {