Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 184 additions & 3 deletions public/openapi.json

Large diffs are not rendered by default.

Binary file modified src/assets/shots/snapshots.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified src/assets/shots/workspace.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified src/assets/shots/workspaces.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
23 changes: 23 additions & 0 deletions src/content/docs/reference/api/authservice.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,27 @@ No fields: `{}`.
| `user` | [User](/reference/api/types/#user) | |
| `controlPlaneVersion` | string | The release of the control plane that answered, which is the release of the dashboard asking: the bundle is served from inside that binary. It rides here rather than on an endpoint of its own because every session asks this once, and because a version an installation will be matched against known flaws by is not something to hand out unauthenticated. |

## GetDeviceLogin

`POST /spin.v1.AuthService/GetDeviceLogin`

What a pending device login offers - the SSH key the device connects with - for the dashboard's page that confirms it, which adds that key with the person's passkey.

**Request**

| Field | Type | What it is |
|---|---|---|
| `userCode` | string | |

**Response**

| Field | Type | What it is |
|---|---|---|
| `sshPublicKey` | string | The key the device offers, as an authorized_keys line, its fingerprint and its name; empty for a device that offers none. |
| `sshKeyFingerprint` | string | |
| `sshKeyName` | string | |
| `sshKeyListed` | boolean | Whether the person already logs in with that key, for good: then there is nothing to add. |

## ListAPIKeys

`POST /spin.v1.AuthService/ListAPIKeys`
Expand Down Expand Up @@ -282,6 +303,8 @@ Start device login flow (for CLI when OAuth redirect is not available) Returns a
| Field | Type | What it is |
|---|---|---|
| `identityProviderId` | string | Optional: use default if empty |
| `sshPublicKey` | string | The SSH public key the device connects to workspaces with, and a name for it - the machine's. The page that confirms the login adds it with the person's passkey, so a first connection from the device is not refused for a key nobody added. Empty: none is offered. |
| `sshKeyName` | string | |

**Response**

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/reference/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ curl -s https://app.example.com/spin.v1.WorkspaceService/ListWorkspaces \
## Services

- [PasskeyService](/reference/api/passkeyservice/): PasskeyService is a person's passkeys: WebAuthn credentials of their account, under the. installation's base domain (internal/passkey). A passkey signs a challenge the control plane. issued, never a document: what turns a session into a key that logs in (SSHKeyService.AddSSHKey) is an assertion of one, so a session alone - stolen, or an agent's - is no shell.
- [AuthService](/reference/api/authservice/): 16 procedures
- [AuthService](/reference/api/authservice/): 17 procedures
- [WorkspaceService](/reference/api/workspaceservice/): 57 procedures
- [SettingsService](/reference/api/settingsservice/): 6 procedures
- [AdminService](/reference/api/adminservice/): AdminService manages installation-wide settings, user management, and resource presets. Only accessible to instance administrators.
Expand Down
22 changes: 20 additions & 2 deletions src/content/docs/reference/api/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -1077,6 +1077,7 @@ A prebuild: one build of a project's ref at a commit, and the snapshot it left.
| `storedBytes` | string or null (int64) | What it keeps in the object store, as storage-gc last read it; unset before a reading counted it. |
| `buildWorkspaceId` | string | The workspace that ran its build (workspaces.prebuild_id), while its row is kept, and whose it is: its events, logs and traces are its owner's to read, and no list of workspaces shows it. |
| `buildWorkspaceOwnerId` | string | |
| `steps` | list of [PrebuildStep](/reference/api/types/#prebuildstep) | What its build has done and is doing, in the order each began (GetPrebuild only): its guest's clone and create tasks, then the control plane's snapshot, publish, scan and share. |

## PrebuildRefNotFound

Expand All @@ -1093,6 +1094,23 @@ A prebuild ref the project's forge has not.

One of: `PREBUILD_STATE_UNSPECIFIED`, `PREBUILD_STATE_BUILDING`, `PREBUILD_STATE_READY`, `PREBUILD_STATE_FAILED`, `PREBUILD_STATE_RETIRED`.

## PrebuildStep

One step of a prebuild's build.

| Field | Type | What it is |
|---|---|---|
| `kind` | [PrebuildStepKind](/reference/api/types/#prebuildstepkind) | |
| `startedAt` | `Timestamp` | |
| `finishedAt` | `Timestamp` | Unset while it runs, and for one its build never finished: a failed prebuild's error is why. |
| `error` | string | Why it failed; empty for one that did not. |

## PrebuildStepKind

The steps of a prebuild's build. They run clone, keep, create, snapshot, publish, scan, share; keep is numbered last because it was added last, and a step's number is what is stored. - `PREBUILD_STEP_KIND_CLONE`: The guest's checkout of the repository at the build's commit. - `PREBUILD_STEP_KIND_CREATE`: The guest's run of the checkout's create task (.spin.yaml); none for a checkout without one. - `PREBUILD_STEP_KIND_SNAPSHOT`: The control plane's snapshot of the build's disk, once its guest said it was done. - `PREBUILD_STEP_KIND_PUBLISH`: The snapshot reaching the object store. - `PREBUILD_STEP_KIND_SCAN`: The scan of the snapshot for credentials, which nothing a member clones may carry. - `PREBUILD_STEP_KIND_SHARE`: The snapshot shared with the teams the project is shared with. - `PREBUILD_STEP_KIND_KEEP`: The control plane's snapshot of the checkout, published before the guest runs create: what the scan compares the build against, so what the repository commits is not refused.

One of: `PREBUILD_STEP_KIND_UNSPECIFIED`, `PREBUILD_STEP_KIND_CLONE`, `PREBUILD_STEP_KIND_CREATE`, `PREBUILD_STEP_KIND_SNAPSHOT`, `PREBUILD_STEP_KIND_PUBLISH`, `PREBUILD_STEP_KIND_SCAN`, `PREBUILD_STEP_KIND_SHARE`, `PREBUILD_STEP_KIND_KEEP`.

## PrebuildsKept

What a project's prebuilds keep in the volumes' bucket, and what that would cost a month at what the last billed day charged: an estimate, never said without the day it is from.
Expand Down Expand Up @@ -1934,9 +1952,9 @@ Timeline event for workspace state changes

## WorkspaceEventType

- `WORKSPACE_EVENT_TYPE_CREATED`: Workspace was created - `WORKSPACE_EVENT_TYPE_STARTED`: Workspace was started - `WORKSPACE_EVENT_TYPE_STOPPED`: Workspace was stopped; its disk is kept, and no snapshot is taken - `WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED`: Manual snapshot - `WORKSPACE_EVENT_TYPE_DELETED`: Workspace was deleted - `WORKSPACE_EVENT_TYPE_FAILED`: Workspace start failed - `WORKSPACE_EVENT_TYPE_RESTORED`: Its disk was put back to a snapshot - `WORKSPACE_EVENT_TYPE_RESUMED`: It went on from a snapshot's memory - `WORKSPACE_EVENT_TYPE_BOOTED`: Suspended, its memory could not be resumed, and its disk was booted - `WORKSPACE_EVENT_TYPE_QUARANTINED`: An administrator held it: stopped, and startable by nobody until released - `WORKSPACE_EVENT_TYPE_UNQUARANTINED`: The hold was released: back to stopped, where it was held from - `WORKSPACE_EVENT_TYPE_PLACED`: A workspace that waited for a host was given one, and its disk there - `WORKSPACE_EVENT_TYPE_TRASHED`: Deleted into the trash: its disk kept, its owner able to undelete it - `WORKSPACE_EVENT_TYPE_UNDELETED`: Taken back out of the trash - `WORKSPACE_EVENT_TYPE_MOVED`: Suspended on its host and resumed on another, which had room for what it was granted - `WORKSPACE_EVENT_TYPE_DISPLACED`: Its host was drained or went away: suspended there, it is resumed on another on its own - `WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED`: A stop on a host that can be taken away could not publish its disk first, so it runs on - `WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED`: Nobody used it for as long as the installation allows: suspended with its processes, a start resumes them - `WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED`: It ran at a stretch for as long as the installation allows: suspended with its processes, a start resumes them - `WORKSPACE_EVENT_TYPE_SUSPENSION_DUE`: A suspension is minutes away and the question was asked: its terminals, its page, the CLI; a keep answers it - `WORKSPACE_EVENT_TYPE_KEPT`: Somebody kept it awake until a time: no suspension before it - `WORKSPACE_EVENT_TYPE_UNRESPONSIVE`: Its supervisor said nothing for longer than the control plane waits: stopped by force, and a start brings it back - `WORKSPACE_EVENT_TYPE_REHOMED`: Its host stopped answering and it was moved to another on its own, giving up what that host had not published - `WORKSPACE_EVENT_TYPE_HELD`: Its host stopped answering and moving it would give up more than the installation does on its own: it waits for its owner - `WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN`: An administrator moved it off a host that is gone, giving up for its owner what that host had not published; its details say who and why - `WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY`: It ran out of memory: its guest's kernel killed a process (cause "guest", with the kills and their victims), its host found it short at its ceiling for a while (cause "ceiling"), or its host killed the machine (cause "host"). Its details say what it held, its grant and its ceiling. Said, never acted on: nothing resizes a workspace on its own. - `WORKSPACE_EVENT_TYPE_OVERSIZED`: It held far more than it used for a week: the most memory its processes used stayed under half its own, and a smaller preset would fit what it used. Its details say what it used, what it holds, and that preset. Said, never acted on: nothing resizes a workspace on its own.
- `WORKSPACE_EVENT_TYPE_CREATED`: Workspace was created - `WORKSPACE_EVENT_TYPE_STARTED`: Workspace was started - `WORKSPACE_EVENT_TYPE_STOPPED`: Workspace was stopped; its disk is kept, and no snapshot is taken - `WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED`: Manual snapshot - `WORKSPACE_EVENT_TYPE_DELETED`: Workspace was deleted - `WORKSPACE_EVENT_TYPE_FAILED`: Workspace start failed - `WORKSPACE_EVENT_TYPE_RESTORED`: Its disk was put back to a snapshot - `WORKSPACE_EVENT_TYPE_RESUMED`: It went on from a snapshot's memory - `WORKSPACE_EVENT_TYPE_BOOTED`: Suspended, its memory could not be resumed, and its disk was booted - `WORKSPACE_EVENT_TYPE_QUARANTINED`: An administrator held it: stopped, and startable by nobody until released - `WORKSPACE_EVENT_TYPE_UNQUARANTINED`: The hold was released: back to stopped, where it was held from - `WORKSPACE_EVENT_TYPE_PLACED`: A workspace that waited for a host was given one, and its disk there - `WORKSPACE_EVENT_TYPE_TRASHED`: Deleted into the trash: its disk kept, its owner able to undelete it - `WORKSPACE_EVENT_TYPE_UNDELETED`: Taken back out of the trash - `WORKSPACE_EVENT_TYPE_MOVED`: Suspended on its host and resumed on another, which had room for what it was granted - `WORKSPACE_EVENT_TYPE_DISPLACED`: Its host was drained or went away: suspended there, it is resumed on another on its own - `WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED`: A stop on a host that can be taken away could not publish its disk first, so it runs on - `WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED`: Nobody used it for as long as the installation allows: suspended with its processes, a start resumes them - `WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED`: It ran at a stretch for as long as the installation allows: suspended with its processes, a start resumes them - `WORKSPACE_EVENT_TYPE_SUSPENSION_DUE`: A suspension is minutes away and the question was asked: its terminals, its page, the CLI; a keep answers it - `WORKSPACE_EVENT_TYPE_KEPT`: Somebody kept it awake until a time: no suspension before it - `WORKSPACE_EVENT_TYPE_UNRESPONSIVE`: Its supervisor said nothing for longer than the control plane waits: stopped by force, and a start brings it back - `WORKSPACE_EVENT_TYPE_REHOMED`: Its host stopped answering and it was moved to another on its own, giving up what that host had not published - `WORKSPACE_EVENT_TYPE_HELD`: Its host stopped answering and moving it would give up more than the installation does on its own: it waits for its owner - `WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN`: An administrator moved it off a host that is gone, giving up for its owner what that host had not published; its details say who and why - `WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY`: It ran out of memory: its guest's kernel killed a process (cause "guest", with the kills and their victims), its host found it short at its ceiling for a while (cause "ceiling"), or its host killed the machine (cause "host"). Its details say what it held, its grant and its ceiling. Said, never acted on: nothing resizes a workspace on its own. - `WORKSPACE_EVENT_TYPE_OVERSIZED`: It held far more than it used for a week: the most memory its processes used stayed under half its own, and a smaller preset would fit what it used. Its details say what it used, what it holds, and that preset. Said, never acted on: nothing resizes a workspace on its own. - `WORKSPACE_EVENT_TYPE_MEMORY_NOT_SAVED`: Its host was being taken away and its memory could not be saved before the host's deadline: its processes are lost, and it comes back from its disk as last published. Its details say when that was, how long before the deadline, and why the memory was not saved.

One of: `WORKSPACE_EVENT_TYPE_UNSPECIFIED`, `WORKSPACE_EVENT_TYPE_CREATED`, `WORKSPACE_EVENT_TYPE_STARTED`, `WORKSPACE_EVENT_TYPE_STOPPED`, `WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED`, `WORKSPACE_EVENT_TYPE_DELETED`, `WORKSPACE_EVENT_TYPE_FAILED`, `WORKSPACE_EVENT_TYPE_RESTORED`, `WORKSPACE_EVENT_TYPE_RESUMED`, `WORKSPACE_EVENT_TYPE_BOOTED`, `WORKSPACE_EVENT_TYPE_QUARANTINED`, `WORKSPACE_EVENT_TYPE_UNQUARANTINED`, `WORKSPACE_EVENT_TYPE_PLACED`, `WORKSPACE_EVENT_TYPE_TRASHED`, `WORKSPACE_EVENT_TYPE_UNDELETED`, `WORKSPACE_EVENT_TYPE_MOVED`, `WORKSPACE_EVENT_TYPE_DISPLACED`, `WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED`, `WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED`, `WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED`, `WORKSPACE_EVENT_TYPE_SUSPENSION_DUE`, `WORKSPACE_EVENT_TYPE_KEPT`, `WORKSPACE_EVENT_TYPE_UNRESPONSIVE`, `WORKSPACE_EVENT_TYPE_REHOMED`, `WORKSPACE_EVENT_TYPE_HELD`, `WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN`, `WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY`, `WORKSPACE_EVENT_TYPE_OVERSIZED`.
One of: `WORKSPACE_EVENT_TYPE_UNSPECIFIED`, `WORKSPACE_EVENT_TYPE_CREATED`, `WORKSPACE_EVENT_TYPE_STARTED`, `WORKSPACE_EVENT_TYPE_STOPPED`, `WORKSPACE_EVENT_TYPE_SNAPSHOT_CREATED`, `WORKSPACE_EVENT_TYPE_DELETED`, `WORKSPACE_EVENT_TYPE_FAILED`, `WORKSPACE_EVENT_TYPE_RESTORED`, `WORKSPACE_EVENT_TYPE_RESUMED`, `WORKSPACE_EVENT_TYPE_BOOTED`, `WORKSPACE_EVENT_TYPE_QUARANTINED`, `WORKSPACE_EVENT_TYPE_UNQUARANTINED`, `WORKSPACE_EVENT_TYPE_PLACED`, `WORKSPACE_EVENT_TYPE_TRASHED`, `WORKSPACE_EVENT_TYPE_UNDELETED`, `WORKSPACE_EVENT_TYPE_MOVED`, `WORKSPACE_EVENT_TYPE_DISPLACED`, `WORKSPACE_EVENT_TYPE_STOP_BACKUP_FAILED`, `WORKSPACE_EVENT_TYPE_IDLE_SUSPENDED`, `WORKSPACE_EVENT_TYPE_RUNNING_CAP_SUSPENDED`, `WORKSPACE_EVENT_TYPE_SUSPENSION_DUE`, `WORKSPACE_EVENT_TYPE_KEPT`, `WORKSPACE_EVENT_TYPE_UNRESPONSIVE`, `WORKSPACE_EVENT_TYPE_REHOMED`, `WORKSPACE_EVENT_TYPE_HELD`, `WORKSPACE_EVENT_TYPE_RECOVERED_BY_ADMIN`, `WORKSPACE_EVENT_TYPE_OUT_OF_MEMORY`, `WORKSPACE_EVENT_TYPE_OVERSIZED`, `WORKSPACE_EVENT_TYPE_MEMORY_NOT_SAVED`.

## WorkspaceFailure

Expand Down
3 changes: 2 additions & 1 deletion src/content/docs/reference/cli/code.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ publishes is Microsoft's, licensed for an organization's own use.
An editor that runs spin itself - the Spinbox extension - names its own commit with
--vscode-commit and --no-open: no local 'code' is looked for, the workspace is given that
commit's server as above, the SSH config is written, and nothing is opened. With -o json the
answer is JSON Lines: a {"preparing": {...}} line for each step of a server being prepared, then
answer is JSON Lines: a {"confirming_key": {...}} line while this computer's key waits for the
person's passkey in the browser, a {"preparing": {...}} line for each step of a server being prepared, then
the result, whose not_given says why the workspace was not given one.

Examples:
Expand Down
16 changes: 9 additions & 7 deletions src/content/docs/reference/cli/smoke.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ sidebar:
```
Run the public contract against the installation this login is to - SPIN_ENDPOINT and
SPIN_TOKEN, or the profile: create a workspace and sign its access, run a command in it, check
it cannot reach the cloud's metadata service (and reaches --reach, when given), suspend it and
it cannot reach the cloud's metadata service by any route a guest has - its address, IMDSv2's
token, IPv6, its names, and --metadata-name when given - (and reaches --reach, when given), suspend it and
resume it where it was, and erase it whatever happened before.

It runs as the person the token is: a key they registered must be held here, as for
Expand All @@ -29,12 +30,13 @@ Usage:
spin smoke [flags]

Flags:
-h, --help[=true|false] help for smoke
--image string The image to start from (default: the installation's)
--network-tag strings Network policy to run under, by name (repeatable)
--preset string The preset it is sized by (default: the installation's)
--reach string A URL the workspace's policies let it reach, checked to be reached
--timeout duration How long the scenarios may take, not counting the erase (default 15m0s)
-h, --help[=true|false] help for smoke
--image string The image to start from (default: the installation's)
--metadata-name string A name that resolves publicly to the metadata service's address, checked not to be reached
--network-tag strings Network policy to run under, by name (repeatable)
--preset string The preset it is sized by (default: the installation's)
--reach string A URL the workspace's policies let it reach, checked to be reached
--timeout duration How long the scenarios may take, not counting the erase (default 15m0s)

Global Flags:
--config string config file (default is $HOME/.spin/config.yaml)
Expand Down
10 changes: 6 additions & 4 deletions src/content/docs/reference/configuration/file.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,11 +90,13 @@ settings:
# lost power, or its network, and said nothing. Its workspaces stay where they are until
# somebody runs `spin workspace recover --accept-data-loss`, which means noticing.
#
# rehome_after_seconds is how long the silence has to last; unset or zero, nothing is ever
# moved and this whole thing is off, which is what an installation starts as. A move gives
# up whatever the host had not published, so it is not a default.
# rehome_after_seconds is how long the silence has to last, the workspace running, starting
# or stopping; unset, 300; zero turns this off and a workspace caught mid-start or mid-stop
# is failed by the stale sweep instead. Unset, a move happens only when it gives up nothing:
# whatever the host had not published is not given up without somebody choosing it.
#
# rehome_max_unpublished_bytes is how much of that this installation gives up on its own.
# rehome_max_unpublished_bytes is how much of that this installation gives up on its own;
# unset, none.
# The number is what the silent host last reported it had not sent to the object store -
# for a host that is gone, what it never will. Over it, the workspace waits for a person.
# A host that never reported at all also waits: nothing known is not the same as nothing
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/reference/security/known-gaps.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ sidebar:

<!-- Generated by tools/refgen from spin:docs/security/README.md. Edit the source, not this file. -->

The open items of Spinbox's security model, from spin's [`docs/security/README.md`](https://github.com/spin-stack/spin/blob/51f7e0dea53e6f85aa855753766b688634487168/docs/security/README.md) at `51f7e0dea`. The numbers are [its rules](/reference/security/rules/).
The open items of Spinbox's security model, from spin's [`docs/security/README.md`](https://github.com/spin-stack/spin/blob/625db22b0029db30647ab676a286b7c9c2b9d3ab/docs/security/README.md) at `625db22b0`. The numbers are [its rules](/reference/security/rules/).

What no line keeps yet. Each is a design change, not a patch, which is why it is here.

Expand Down
Loading
Loading