Relationships
#4848 Workspace services: create, list, get, suspend, resume and delete a hosted workspace
Opened by zack · 11/17/2026· Shipped 11/18/2026
Issue 10 of the execution plan in design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4836 (wanted and status files), merged.
Problem
The host reads a wanted file for each workspace and acts on it, but nothing writes one for a request, and nothing creates a workspace. An operator makes each workspace by hand and suspends it by editing a file.
Change
Add the workspace application services in src/libswamp/hosted_workspace/. They work on a host's workspaces/ folder through the HostedWorkspace aggregate and its repository, which already exist. They are exported from mod.ts.
- Create. Refuses a name that
parseWorkspaceNamerefuses, and a name already taken by a folder, a wanted file or a status file. Sets the repo up in a folder under a hidden temporary name, then renames it into place, so the host never starts half a workspace. Writes the workspace'sserve.yaml: the root's auth mode, OAuth provider and admission lists, and the caller as its first admin. Records the creator and the time in the wanted file. A create that fails removes what it made and leaves no entry under the name. - Create never starts a serve. The design's default-off rule: the host starts a serve only when a wanted file says
active. Create writes the wanted file assuspendedbefore the rename, so the new workspace is listed and has no serve until a resume. The host already leaves a wanted file alone while its folder does not exist. - The provisioner. Setting up a repo runs as a child process in the new folder. The calling process never loads another workspace's extensions.
- List. Names, addresses and states.
- Get. One workspace: state, restarts and the host's reason when it is not ready.
- Suspend and resume. Each writes the wanted file with a new
changedAt. Resume is the only thing that starts a workspace's serve. A changedactiverecord is also what takes a workspace out offailed. - Delete. Writes
deleted. The host stops the serve and removes the folder and both files.
A decision this issue makes
In oauth mode a new workspace's first start looks up each admin name. Without a collective key in the host's environment that lookup is a device grant, so a person has to complete it. Create has to avoid that for the creator. The design names two ways and leaves the choice to this issue:
- create seeds the workspace's
oauth-resolved-adminsfrom names the root already resolved, or - serve gains an admin entry form that is already resolved.
The PR states which it chose and why, and updates the design doc.
Done when
- An integration test runs each service on a temp folder with the real file store.
- A scan of the folder taken at any point during a create never lists the new workspace until it is whole.
- A created workspace has its wanted file, saying
suspended, before its folder appears, and the host's reconciler never starts it. A resume then starts it. - A failed set-up leaves no folder and no wanted file under the name.
- Create refuses a taken name, whether a folder, a wanted file or a status file holds it.
- The services are exported from
mod.tsand the libswamp fitness rules pass. - Test fixtures that initialise a repo pass
tools: [].
Out of scope
workspace.*requests on the root. The next issue in the plan.- The
swamp serve workspacecommands. - The
workspacekind in grants. The services take a caller and do no authorization of their own. - Workspaces from the workspace registry. Item 19 in the plan.
- The host's own default for a folder with no wanted file. Item 20 in the plan.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.