Skip to content

Add force option to instance stop - #573

Merged
chruffins merged 3 commits into
mainfrom
hypeship/force-stop
Nov 16, 2026
Merged

chruffins merged 3 commits into
mainfrom
hypeship/force-stop

Conversation

@chruffins

@chruffins chruffins commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

POST /instances/{id}/stop only does a graceful stop: it asks the guest to shut down, waits up to the grace period, and falls back to a hypervisor shutdown. That wait is wasted when the guest state is about to be thrown away, for example right before restoring a memory snapshot to reset a VM. On a macOS guest the graceful stop takes about 7s.

This adds an optional body to stop, {"force": true}, which skips the guest shutdown and goes straight to the existing hypervisor shutdown path. With no body or {"force": false}, stop behaves as before. The naming follows other platforms' hard-stop options (AWS StopInstances --force, Hyper-V Stop-VM -TurnOff).

Existing and new flows

Existing: stop -> graceful guest shutdown RPC -> wait grace period
               -> (if VM still up) hypervisor shutdown -> (if still up) kill
New:      stop {force: false | no body} -> unchanged
          stop {force: true}            -> hypervisor shutdown -> (if still up) kill

Everything after that (network release, socket cleanup, snapshot dir removal, metadata) is unchanged.

Behavior

  • macOS guests: a forced stop never counts as graceful (stop_graceful stays false), so a stopped snapshot or fork from that stop returns 409 until the guest is booted and stopped gracefully again. On VZ the hypervisor shutdown is the shim's vmm.shutdown (VZVirtualMachine.stop(), then a clean shim exit), so the vmnet network is released. It does not SIGKILL the shim unless the shim fails to exit.
  • Empty bodies: the generated strict handler rejects an empty body, so the middleware that already rewrites empty standby bodies to {} now covers /stop as well. It is renamed NormalizeOptionalStandbyBody -> NormalizeOptionalBody. Existing callers that POST stop with no body keep working.
  • Internal callers (restart policy, fork target state, macOS agent startup, rekey failure) pass StopInstanceRequest{} and keep the graceful behavior.
  • The instances.stop span and the "stopping instance" log carry force.

Change size

~1,210 lines changed; roughly 70 LOC of meaningful implementation (approximate, excluding generated code, tests, docs and the call-site signature updates):

Chunk ~LOC What
lib/instances/stop.go 30 skip the graceful step when forced (mostly re-indentation)
cmd/api/api/optional_body.go 15 route list for optional bodies, now /standby and /stop
openapi.yaml + handler + StopInstanceRequest 25 request schema and plumbing
lib/oapi/oapi.go ~880 regenerated with make oapi-generate
tests + call sites + docs ~230 StopInstance signature update, new tests, macOS doc note

Testing

  • go test ./lib/instances -run TestForceStopSkipsGuestShutdown — passes; fails with Force: false, confirming it detects the guest shutdown RPC.

  • go test ./cmd/api/api -run TestNormalizeOptionalBody — passes, including the new empty /stop body case.

  • go test ./lib/instances on a Linux VM without KVM or mkfs.erofs: 24 failures, the same set as on main in that environment.

  • Manual, on an Apple silicon Mac (macOS 27, macOS 27.0.1 guest, 4 vCPU / 8 GiB):

    • forced stop: 0.06s, Stopped, no shim process left, stop_graceful false
    • fork after a forced stop: 409 (macOS fork requires a gracefully stopped source)
    • start after a forced stop: Running (vmnet network reusable)
    • stop with no body: graceful, 6.9s, stop_graceful true
    • forced stop + memory-snapshot restore, 3 cycles: 4.6–4.8s total, files written before the stop were gone after restore
  • Manual, Linux smoke test on a KVM dev host (throwaway test, not committed): nginx guest with networking, cycle forced stop -> start -> graceful stop -> start -> forced stop. Each stop checked Stopped, the hypervisor PID gone and the TAP device removed; each start checked the exec agent answers and the guest has an IP.

    Hypervisor Forced stop Graceful stop
    Cloud Hypervisor 0.87s, 0.31s 0.57s
    Firecracker 0.37s, 0.30s 5.38s
  • Not run: QEMU, and CI.

Not included

  • A per-call grace period (timeout_seconds). The stored per-instance StopTimeout is still not exposed in the API.
  • A combined reset operation (stop + restore + post-restore steps).

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 35b0667. Configure here.

Comment thread openapi.yaml
guest state will be discarded, for example before restoring a snapshot.
A forced stop of a macOS guest is never graceful, so it cannot be used
for a stopped snapshot or fork until the guest is booted and stopped
gracefully again.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stop request model missing SDK mapping

Medium Severity

StopInstanceRequest is added as a named OpenAPI schema and as the /instances/{id}/stop request body, but stainless.yaml is not updated with a corresponding model mapping. The stop method is already listed, yet the new request schema is not, so Stainless SDK previews can omit the force field and leave SDK clients unable to request a forced stop.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 35b0667. Configure here.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

116 files generated at ea58c65 (pushed)

go get github.com/kernel/hypeman-go-staging@ea58c653683a65a90661d45731268866bbafc06f
✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

233 files generated at 9e71992 (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

138 files generated at 0e0c6ee (pushed)

Diagnostics: ❗ 0 new / 1 total error, 💡 0 new / 5 total note
LevelCodeMessageTargets
Build metadata
Buildbd_76m5NS2g-mighty-drop
Timestamp2026-11-16T16:24:08.281Z
stlc8413509
Spec hashdb282710e062
Config hash659c3687c3f0

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-11-16 16:24:35 UTC

@chruffins
chruffins marked this pull request as ready for review November 16, 2026 16:20
@chruffins
chruffins merged commit f2a59f0 into main Nov 16, 2026
13 checks passed
@chruffins
chruffins deleted the hypeship/force-stop branch November 16, 2026 16:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants