Jul 8, 2025 · Jul 1, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/workspacebuilds.go b/coderd/workspacebuilds.go
 // @Produce json
 // @Tags Builds
 // @Param workspacebuild path string true "Workspace build ID"
 // @Param expect_status query string false "Expected status of the job" Enums(running, pending)
 // @Param expect_status query string false "Expected status of the job. If expect_status is supplied, the request will be rejected with 412 Precondition Failed if the job doesn't match the state when performing the cancellation." Enums(running, pending)
 // @Success 200 {object} codersdk.Response
 // @Router /workspacebuilds/{workspacebuild}/cancel [patch]
 func (api *API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r *http.Request) {
 ctx := r.Context()
 expectStatus := r.URL.Query().Get("expect_status")

 var expectStatus database.ProvisionerJobStatus
 expectStatusParam := r.URL.Query().Get("expect_status")
 if expectStatusParam != "" {
 if expectStatusParam != "running" && expectStatusParam != "pending" {
 httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
 Message: fmt.Sprintf("Invalid expect_status %q. Only 'running' or 'pending' are allowed.", expectStatusParam),
 })
 return
 }
 expectStatus = database.ProvisionerJobStatus(expectStatusParam)
 }

 workspaceBuild := httpmw.WorkspaceBuildParam(r)
 workspace, err := api.Database.GetWorkspaceByID(ctx, workspaceBuild.WorkspaceID)
 if err != nil {
 return
 }

 code := http.StatusOK
 resp := codersdk.Response{}
 code := http.StatusInternalServerError
 resp := codersdk.Response{
 Message: "Internal error canceling workspace build.",
 }
 err = api.Database.InTx(func(db database.Store) error {
 valid, err := verifyUserCanCancelWorkspaceBuilds(ctx, db, httpmw.APIKey(r).UserID, workspace.TemplateID, expectStatus)
 if err != nil {
 return xerrors.New("job has already been marked as canceled")
 }

 if expectStatus != "" {
 if expectStatus != "running" && expectStatus != "pending" {
 code = http.StatusBadRequest
 resp.Message = fmt.Sprintf("Invalid expect_status %q. Only 'running' or 'pending' are allowed.", expectStatus)

 return xerrors.Errorf("invalid expect_status %q", expectStatus)
 }
 if expectStatus != "" && job.JobStatus != expectStatus {
 code = http.StatusPreconditionFailed
 resp.Message = "Job is not in the expected state."

 if job.JobStatus != database.ProvisionerJobStatus(expectStatus) {
 code = http.StatusPreconditionFailed
 resp.Message = "Job is not in the expected state."

 return xerrors.Errorf("job is not in the expected state: expected: %q, got %q", expectStatus, job.JobStatus)
 }
 return xerrors.Errorf("job is not in the expected state: expected: %q, got %q", expectStatus, job.JobStatus)
 }

 err = db.UpdateProvisionerJobWithCancelByID(ctx, database.UpdateProvisionerJobWithCancelByIDParams{
 })
 }

 func verifyUserCanCancelWorkspaceBuilds(ctx context.Context, store database.Store, userID uuid.UUID, templateID uuid.UUID,expectStatus string) (bool, error) {
 // If theexpectStatus is pending, we can cancel it.
 ifexpectStatus =="pending" {
 func verifyUserCanCancelWorkspaceBuilds(ctx context.Context, store database.Store, userID uuid.UUID, templateID uuid.UUID,jobStatus database.ProvisionerJobStatus) (bool, error) {
 // If thejobStatus is pending, we can cancel it.
 ifjobStatus ==database.ProvisionerJobStatusPending {
 return true, nil
 }

diff --git a/coderd/workspacebuilds_test.go b/coderd/workspacebuilds_test.go
 require.Equal(t, codersdk.ProvisionerJobCanceled, build.Job.Status)
 })

 t.Run("Cancel with expect_state=pending - should fail with 412", func(t *testing.T) {
 t.Run("Cancel with expect_state=pendingwhen job is running- should fail with 412", func(t *testing.T) {
 t.Parallel()

 client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
 coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
 template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 workspace := coderdtest.CreateWorkspace(t, client, template.ID)
 var build codersdk.WorkspaceBuild

 ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 defer cancel()

 var build codersdk.WorkspaceBuild
 require.Eventually(t, func() bool {
 var err error
 build, err = client.WorkspaceBuild(ctx, workspace.LatestBuild.ID)
 require.Equal(t, http.StatusPreconditionFailed, apiErr.StatusCode())
 })

 t.Run("Cancel with expect_state=running when job is pending - should fail with 412", func(t *testing.T) {
 t.Parallel()
 if !dbtestutil.WillUsePostgres() {
 t.Skip("this test requires postgres")
 }
 // Given: a coderd instance with a provisioner daemon
 store, ps, db := dbtestutil.NewDBWithSQLDB(t)
 client, closeDaemon := coderdtest.NewWithProvisionerCloser(t, &coderdtest.Options{
 Database:                 store,
 Pubsub:                   ps,
 IncludeProvisionerDaemon: true,
 })
 defer closeDaemon.Close()
 // Given: a user, template, and workspace
 user := coderdtest.CreateFirstUser(t, client)
 version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
 coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
 template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 workspace := coderdtest.CreateWorkspace(t, client, template.ID)
 coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)

 // Stop the provisioner daemon.
 require.NoError(t, closeDaemon.Close())
 ctx := testutil.Context(t, testutil.WaitLong)
 // Given: no provisioner daemons exist.
 _, err := db.ExecContext(ctx, `DELETE FROM provisioner_daemons;`)
 require.NoError(t, err)

 // When: a new workspace build is created
 build, err := client.CreateWorkspaceBuild(ctx, workspace.ID, codersdk.CreateWorkspaceBuildRequest{
 TemplateVersionID: template.ActiveVersionID,
 Transition:        codersdk.WorkspaceTransitionStart,
 })
 // Then: the request should succeed.
 require.NoError(t, err)
 // Then: the provisioner job should remain pending.
 require.Equal(t, codersdk.ProvisionerJobPending, build.Job.Status)

 // Then: the response should indicate no provisioners are available.
 if assert.NotNil(t, build.MatchedProvisioners) {
 assert.Zero(t, build.MatchedProvisioners.Count)
 assert.Zero(t, build.MatchedProvisioners.Available)
 assert.Zero(t, build.MatchedProvisioners.MostRecentlySeen.Time)
 assert.False(t, build.MatchedProvisioners.MostRecentlySeen.Valid)
 }

 // When: a cancel request is made with expect_state=running
 err = client.CancelWorkspaceBuild(ctx, build.ID, codersdk.CancelWorkspaceBuildParams{
 ExpectStatus: codersdk.CancelWorkspaceBuildStatusRunning,
 })
 // Then: the request should fail with 412.
 require.Error(t, err)

 var apiErr *codersdk.Error
 require.ErrorAs(t, err, &apiErr)
 require.Equal(t, http.StatusPreconditionFailed, apiErr.StatusCode())
 })

 t.Run("Cancel with expect_state - invalid status", func(t *testing.T) {
 t.Parallel()

diff --git a/docs/reference/api/builds.md b/docs/reference/api/builds.md
diff --git a/site/src/api/api.ts b/site/src/api/api.ts
 workspaceBuildId: TypesGen.WorkspaceBuild["id"],
 params?: TypesGen.CancelWorkspaceBuildParams,
 ): Promise<TypesGen.Response> => {
 const queryParams = new URLSearchParams({ ...params });
 const response = await this.axios.patch(
 `/api/v2/workspacebuilds/${workspaceBuildId}/cancel${queryParams}`,
 `/api/v2/workspacebuilds/${workspaceBuildId}/cancel`,
 null,
 { params },
 );

 return response.data;
diff --git a/site/src/api/queries/workspaces.ts b/site/src/api/queries/workspaces.ts
 import { API, type DeleteWorkspaceOptions } from "api/api";
 import { DetailedError, isApiValidationError } from "api/errors";
 import type {
 CancelWorkspaceBuildParams,
 CreateWorkspaceRequest,
 ProvisionerLogLevel,
 UsageAppName,
 export const cancelBuild = (workspace: Workspace, queryClient: QueryClient) => {
 return {
 mutationFn: () => {
 if (workspace.latest_build.status=== "pending") {
 return API.cancelWorkspaceBuild(workspace.latest_build.id, {
 expect_status: "pending",
 });
 }
 return API.cancelWorkspaceBuild(workspace.latest_build.id);
 const {status} = workspace.latest_build;
 const params: CancelWorkspaceBuildParams = {
 expect_status:
 status === "pending" || status === "running" ? status : undefined,
 };
 return API.cancelWorkspaceBuild(workspace.latest_build.id, params);
 },
 onSuccess: async () => {
 await queryClient.invalidateQueries({
Original file line number	Diff line number	Diff line change
Expand Up		@@ -581,12 +581,24 @@ func (api *API) notifyWorkspaceUpdated(
		// @Produce json
		// @Tags Builds
		// @Param workspacebuild path string true "Workspace build ID"
		// @Param expect_status query string false "Expected status of the job" Enums(running, pending)
		// @Param expect_status query string false "Expected status of the job. If expect_status is supplied, the request will be rejected with 412 Precondition Failed if the job doesn't match the state when performing the cancellation." Enums(running, pending)
		// @Success 200 {object} codersdk.Response
		// @Router /workspacebuilds/{workspacebuild}/cancel [patch]
		func (api API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r http.Request) {
		ctx := r.Context()
		expectStatus := r.URL.Query().Get("expect_status")

		var expectStatus database.ProvisionerJobStatus
		expectStatusParam := r.URL.Query().Get("expect_status")
		if expectStatusParam != "" {
		if expectStatusParam != "running" && expectStatusParam != "pending" {
		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
		Message: fmt.Sprintf("Invalid expect_status %q. Only 'running' or 'pending' are allowed.", expectStatusParam),
		})
		return
		}
		expectStatus = database.ProvisionerJobStatus(expectStatusParam)
		}

		workspaceBuild := httpmw.WorkspaceBuildParam(r)
		workspace, err := api.Database.GetWorkspaceByID(ctx, workspaceBuild.WorkspaceID)
		if err != nil {
Expand All		@@ -596,8 +608,10 @@ func (api API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r http.Reques
		return
		}

		code := http.StatusOK
		resp := codersdk.Response{}
		code := http.StatusInternalServerError
		resp := codersdk.Response{
		Message: "Internal error canceling workspace build.",
		}
		err = api.Database.InTx(func(db database.Store) error {
		valid, err := verifyUserCanCancelWorkspaceBuilds(ctx, db, httpmw.APIKey(r).UserID, workspace.TemplateID, expectStatus)
		if err != nil {
Expand DownExpand Up		@@ -635,20 +649,11 @@ func (api API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r http.Reques
		return xerrors.New("job has already been marked as canceled")
		}

		if expectStatus != "" {
		if expectStatus != "running" && expectStatus != "pending" {
		code = http.StatusBadRequest
		resp.Message = fmt.Sprintf("Invalid expect_status %q. Only 'running' or 'pending' are allowed.", expectStatus)

		return xerrors.Errorf("invalid expect_status %q", expectStatus)
		}
		if expectStatus != "" && job.JobStatus != expectStatus {
		code = http.StatusPreconditionFailed
		resp.Message = "Job is not in the expected state."

		if job.JobStatus != database.ProvisionerJobStatus(expectStatus) {
		code = http.StatusPreconditionFailed
		resp.Message = "Job is not in the expected state."

		return xerrors.Errorf("job is not in the expected state: expected: %q, got %q", expectStatus, job.JobStatus)
		}
		return xerrors.Errorf("job is not in the expected state: expected: %q, got %q", expectStatus, job.JobStatus)
		}

		err = db.UpdateProvisionerJobWithCancelByID(ctx, database.UpdateProvisionerJobWithCancelByIDParams{
Expand DownExpand Up		@@ -688,9 +693,9 @@ func (api API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r http.Reques
		})
		}

		func verifyUserCanCancelWorkspaceBuilds(ctx context.Context, store database.Store, userID uuid.UUID, templateID uuid.UUID,expectStatus string) (bool, error) {
		// If theexpectStatus is pending, we can cancel it.
		ifexpectStatus =="pending" {
		func verifyUserCanCancelWorkspaceBuilds(ctx context.Context, store database.Store, userID uuid.UUID, templateID uuid.UUID,jobStatus database.ProvisionerJobStatus) (bool, error) {
		// If thejobStatus is pending, we can cancel it.
kacpersaw marked this conversation as resolved. OutdatedShow resolvedHide resolved
		ifjobStatus ==database.ProvisionerJobStatusPending {
		return true, nil
		}

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -682,7 +682,7 @@ func TestPatchCancelWorkspaceBuild(t *testing.T) {
		require.Equal(t, codersdk.ProvisionerJobCanceled, build.Job.Status)
		})

		t.Run("Cancel with expect_state=pending - should fail with 412", func(t *testing.T) {
		t.Run("Cancel with expect_state=pendingwhen job is running- should fail with 412", func(t *testing.T) {
		t.Parallel()

		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
Expand All		@@ -699,11 +699,11 @@ func TestPatchCancelWorkspaceBuild(t *testing.T) {
		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
		workspace := coderdtest.CreateWorkspace(t, client, template.ID)
		var build codersdk.WorkspaceBuild

		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
		defer cancel()

		var build codersdk.WorkspaceBuild
		require.Eventually(t, func() bool {
		var err error
		build, err = client.WorkspaceBuild(ctx, workspace.LatestBuild.ID)
Expand All		@@ -722,6 +722,64 @@ func TestPatchCancelWorkspaceBuild(t *testing.T) {
		require.Equal(t, http.StatusPreconditionFailed, apiErr.StatusCode())
		})

deansheather marked this conversation as resolved. Show resolvedHide resolved
		t.Run("Cancel with expect_state=running when job is pending - should fail with 412", func(t *testing.T) {
		t.Parallel()
		if !dbtestutil.WillUsePostgres() {
		t.Skip("this test requires postgres")
		}
		// Given: a coderd instance with a provisioner daemon
		store, ps, db := dbtestutil.NewDBWithSQLDB(t)
		client, closeDaemon := coderdtest.NewWithProvisionerCloser(t, &coderdtest.Options{
		Database: store,
		Pubsub: ps,
		IncludeProvisionerDaemon: true,
		})
		defer closeDaemon.Close()
		// Given: a user, template, and workspace
		user := coderdtest.CreateFirstUser(t, client)
		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
		workspace := coderdtest.CreateWorkspace(t, client, template.ID)
		coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)

		// Stop the provisioner daemon.
		require.NoError(t, closeDaemon.Close())
		ctx := testutil.Context(t, testutil.WaitLong)
		// Given: no provisioner daemons exist.
		_, err := db.ExecContext(ctx, `DELETE FROM provisioner_daemons;`)
		require.NoError(t, err)

		// When: a new workspace build is created
		build, err := client.CreateWorkspaceBuild(ctx, workspace.ID, codersdk.CreateWorkspaceBuildRequest{
		TemplateVersionID: template.ActiveVersionID,
		Transition: codersdk.WorkspaceTransitionStart,
		})
		// Then: the request should succeed.
		require.NoError(t, err)
		// Then: the provisioner job should remain pending.
		require.Equal(t, codersdk.ProvisionerJobPending, build.Job.Status)

		// Then: the response should indicate no provisioners are available.
		if assert.NotNil(t, build.MatchedProvisioners) {
		assert.Zero(t, build.MatchedProvisioners.Count)
		assert.Zero(t, build.MatchedProvisioners.Available)
		assert.Zero(t, build.MatchedProvisioners.MostRecentlySeen.Time)
		assert.False(t, build.MatchedProvisioners.MostRecentlySeen.Valid)
		}

		// When: a cancel request is made with expect_state=running
		err = client.CancelWorkspaceBuild(ctx, build.ID, codersdk.CancelWorkspaceBuildParams{
		ExpectStatus: codersdk.CancelWorkspaceBuildStatusRunning,
		})
		// Then: the request should fail with 412.
		require.Error(t, err)

		var apiErr *codersdk.Error
		require.ErrorAs(t, err, &apiErr)
		require.Equal(t, http.StatusPreconditionFailed, apiErr.StatusCode())
		})

		t.Run("Cancel with expect_state - invalid status", func(t *testing.T) {
		t.Parallel()

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1279,9 +1279,10 @@ class ApiMethods {
		workspaceBuildId: TypesGen.WorkspaceBuild["id"],
		params?: TypesGen.CancelWorkspaceBuildParams,
		): Promise<TypesGen.Response> => {
		const queryParams = new URLSearchParams({ ...params });
		const response = await this.axios.patch(
		`/api/v2/workspacebuilds/${workspaceBuildId}/cancel${queryParams}`,
		`/api/v2/workspacebuilds/${workspaceBuildId}/cancel`,
		null,
		{ params },
		);

		return response.data;
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,6 +1,7 @@
		import { API, type DeleteWorkspaceOptions } from "api/api";
		import { DetailedError, isApiValidationError } from "api/errors";
		import type {
		CancelWorkspaceBuildParams,
		CreateWorkspaceRequest,
		ProvisionerLogLevel,
		UsageAppName,
Expand DownExpand Up		@@ -266,12 +267,12 @@ export const startWorkspace = (
		export const cancelBuild = (workspace: Workspace, queryClient: QueryClient) => {
		return {
		mutationFn: () => {
		if (workspace.latest_build.status=== "pending") {
		return API.cancelWorkspaceBuild(workspace.latest_build.id, {
		expect_status: "pending",
		});
		}
		return API.cancelWorkspaceBuild(workspace.latest_build.id);
		const {status} = workspace.latest_build;
		const params: CancelWorkspaceBuildParams = {
		expect_status:
		status === "pending" \|\| status === "running" ? status : undefined,
		};
		return API.cancelWorkspaceBuild(workspace.latest_build.id, params);
Copy link Collaborator BrunoQuaresmaJul 7, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Double checking... can`cancelWorkspaceBuild` being called in any status? I see the params can be`undefined`, but it would still call the`cancelWorkspaceBuild` 🤔. This part of the code is quite hard for me to understand why the params are only set when the status is pending or running. Copy link ContributorAuthor kacpersawJul 8, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. `expect_status` is an optional parameter for cancel that ensures the job is in a specific state before proceeding - it only supports`pending` and`running`. So, cancel can be called without it.
		},
		onSuccess: async () => {
		await queryClient.invalidateQueries({
Expand Down