Skip to content

Align the Porter backend with Porter volume and snapshot docs - #1423

Draft
ReganBell wants to merge 3 commits into
mainfrom
sandbox/porter-docs-alignment
Draft

ReganBell wants to merge 3 commits into
mainfrom
sandbox/porter-docs-alignment

Conversation

@ReganBell

Copy link
Copy Markdown
Contributor

Aligns the Porter backend with the Porter sandbox documentation and SDK 0.1.58.

  • Type sandbox creation with the SDK's SandboxSpec instead of a hand-declared subset.
  • Read and write home files through the volume file API, falling back to exec for scratch bodies, paths outside the volume, and clusters without the volumes mount.
  • Snapshot the body before restart, egress rotation and idle reaping, and recreate from the snapshot so installs outside the volume survive.
  • Add PORTER_CPUS and PORTER_MEMORY_MB, idle reaping so the TTL is only a cost cap, pagination, a 120 second client timeout, and failed-body logs in status.

Docs: https://docs.porter.run/sandboxes/volumes https://docs.porter.run/sandboxes/sdk/typescript/reference https://docs.porter.run/sandboxes/cli

Needs live QA before merge.

Bump porter-sandbox to 0.1.58 and type sandbox creation with the SDK's own
SandboxSpec, so resources, snapshot_id, env_groups and internal networking are
no longer hidden behind a hand-declared shape. The client is now a thin adapter
over the SDK instead of a Proxy cast, with the same error-detail enrichment.

Move file traffic under $HOME to Porter's volume file API: one atomic PUT per
write and 8 MiB ranged GETs per read instead of 64 KiB base64 exec chunks.
Import archives land in the workspace through the same path, and the export
archive is now built under $HOME/.qm-export (pruned from the home export) so it
reads back through the volume too. Scratch bodies, paths outside the volume,
and clusters without the sandbox-volumes mount keep the exec path; a client
error from the files API marks that volume as exec-only for the process, a
timeout falls back for that call only.

Carry files outside $HOME across body rotation with Porter filesystem
snapshots. A scope's body is snapshotted before restart, egress rotation and
idle reaping, and refreshed during the idle sweep when the scope has been
active since; the next body starts from snapshot_id with image left empty as
the docs require. One snapshot is kept per scope, superseded and destroyed
ones are deleted, a snapshot from a different image is ignored, and one Porter
can no longer start from is forgotten and the body comes from the image.
computerStatus reports it as recovery strategy provider_snapshot.

Add idle reaping: reapDeepIdle retires bodies whose scope has been inactive
past the deep-idle window and has no running process session, leaving the
volume and snapshot in place, so ttl_seconds is only the cost cap. The scope
record (body id, last activity, snapshot pointer) lives in the durable
porter_sandbox_bodies map and joins the legacy sandbox bindings.

Honour Pagination.has_next_page when listing, find the live body through the
home volume's attached_to before falling back to a tag scan, cache body
name-to-id resolution instead of a lookup plus get per exec, raise the SDK's
30 second client timeout to 120 seconds because snapshots.create resolves only
when the capture completes, and surface the failed body's log tail and the
lifetime cap in computerStatus. Exec stays unbounded by the SDK and is never
retried, as documented.

PORTER_CPUS and PORTER_MEMORY_MB set resources.cpu and resources.memory and
fill the advertised profile spec.
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