Skip to content

api: share_memory fork mode + fork_count/mem_locked on Instance#220

Draft
sjmiller609 wants to merge 1 commit intohypeship/uffd-firecracker-wiringfrom
hypeship/fork-share-memory-api
Draft

api: share_memory fork mode + fork_count/mem_locked on Instance#220
sjmiller609 wants to merge 1 commit intohypeship/uffd-firecracker-wiringfrom
hypeship/fork-share-memory-api

Conversation

@sjmiller609
Copy link
Copy Markdown
Collaborator

Summary

Exposes the uffd/template-fork machinery through the existing POST /instances/{id}/fork endpoint, without introducing a new /templates resource.

  • ForkInstanceRequest.share_memory: bool — when true, the source instance is auto-promoted (idempotently) into a fan-out parent and the fork attaches to its mem-file instead of copying. Subsequent share_memory forks against the same source reuse the same registry entry.
  • Instance.fork_count: int and Instance.mem_locked: bool — read-only fields so clients can introspect lock state on the existing GetInstance response.
  • While mem_locked = true, start/restore/delete on the source return 409 (ErrInvalidState) until all share_memory forks are deleted. templateGuard now returns ErrInvalidState rather than ErrNotSupported so the lock surfaces as a transient 409, not a 501 capability gap.
  • Validation: share_memory is incompatible with template_id and with from_running=true (the latter would re-restore the source after locking).

The lib/templates package and TemplateID field stay as internal machinery — no public templates resource. share_memory=false forks are unchanged and may still be created against a locked source.

Test plan

  • go vet ./... clean
  • New unit tests in lib/instances/share_memory_test.go:
    • TestValidateForkRequest_ShareMemoryConflicts — rejects share_memory + template_id and share_memory + from_running
    • TestEnsureShareMemoryTemplate_AutoPromoteAndReuse — first call promotes, second reuses
    • TestEnsureShareMemoryTemplate_RejectsNonStandby — non-Standby source returns ErrInvalidState
    • TestTemplateGuard_ReturnsInvalidStateNotUnsupported — guard now maps to 409
    • TestHydrateForkLockState — fork_count/mem_locked reflect refcount changes
  • CI on green firecracker E2E + cross-hypervisor regression

ForkInstanceRequest gains share_memory: when true, the source instance is
auto-promoted (idempotently) into a fan-out parent and the fork attaches
to its mem-file via the existing template path instead of copying. While
any share_memory fork is alive, the source is mem-locked: start/restore/
delete return 409 (ErrInvalidState) until the forks are deleted.

Instance gains read-only fork_count and mem_locked fields so clients can
introspect lock state on the existing GetInstance response without
needing a separate templates resource. The internal templates registry
stays in place but is not exposed in OpenAPI.

templateGuard now returns ErrInvalidState rather than ErrNotSupported so
the lock surfaces as a transient 409, not a 501 capability gap.
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

✱ Stainless preview builds for hypeman

This PR will update the hypeman SDKs with the following commit message.

feat: api: share_memory fork mode + fork_count/mem_locked on Instance

Edit this comment to update it. It will appear in the SDK's changelogs.

hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ✅lint ❗test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/8a1894a220dba7b8928dfecb720e3c85d418b61f/dist.tar.gz
hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ✅lint ✅test ✅

go get github.com/stainless-sdks/hypeman-go@5bf5c10c8e7abc5dd96c6185bbe931301aca0d77
hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅


This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-08 18:18:37 UTC

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.

1 participant