Creates and deletes
Spaces being created or deleted: the rows they show at once, their progress and how they hand over to the registry.
Spaces being created or deleted: the rows they show at once, their progress and how they hand over to the registry.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
app_creates_reduce applies a create or delete action (a start, the SDK's create progress, a timer tick, the result) and app_creates_compose adds the pending rows to the registry's Spaces. Progress moves by the SDK's fractions, else by the time each phase usually takes for the image, from the now the shell passes.
AppCreatesState record#Returned by app_creates_reduce, app_creates_settle.
| Field | Type | Default | Description |
|---|---|---|---|
pending | Vec<AppPendingCreate> | Oldest first. | |
deleting | Vec<AppPendingDelete> | Spaces being deleted, oldest first. | |
powering | Vec<AppPendingPower> | Spaces being turned off or on (or whose last try failed). |
AppCreateAction enum#.start(id: String, name: String, os: AppSpaceOs, provider: AppSpaceProvider, now: Int64, image: String?, kind: AppSpaceKind?, hostArch: String?, gpu: Bool)
.progress(id: String, phase: String, fraction: Double?, now: Int64?, bytesDone: UInt64?, bytesTotal: UInt64?, bytesPerSecond: Double?)
.cancelStart(id: String)
.cancelDone(id: String)
.cancelFail(id: String, error: String)
.tick(now: Int64)
.finish(id: String, spaceId: String)
.fail(id: String, error: String)
.dismiss(id: String)
.deleteStart(id: String, now: Int64)
.deleteFail(id: String)
.deleteDone(id: String)
.powerStart(id: String, on: Bool, now: Int64)
.powerDone(id: String)
.powerFail(id: String, error: String)| Variant | Description |
|---|---|
Start | A create started: its row shows now. Fields: id: String, name: String, os: AppSpaceOs, provider: AppSpaceProvider, now: i64, image: Option<String>, kind: Option<AppSpaceKind>, host_arch: Option<String>, gpu: bool |
Progress | The SDK reported progress. Fields: id: String, phase: String, fraction: Option<f64>, now: Option<i64>, bytes_done: Option<u64>, bytes_total: Option<u64>, bytes_per_second: Option<f64> |
CancelStart | Cancel was pressed: the shell asks the SDK to cancel the create (cancel_create with the pending id, passed as the create's create_id); the row shows Cancelling until the create ends. Fields: id: String |
CancelDone | The cancel finished (or the create ended cancelled): the row goes. Fields: id: String |
CancelFail | The cancel itself failed: the row shows why. Fields: id: String, error: String |
Tick | Time passed (a shell's timer, a few times a second while a create is pending): progress within a phase that reports no fraction advances with the time the phase usually takes. Fields: now: i64 |
Finish | The create returned the Space. Fields: id: String, space_id: String |
Fail | The create failed. Fields: id: String, error: String |
Dismiss | Remove a failed row. Fields: id: String |
DeleteStart | The user confirmed Delete: the row shows Deleting now. A second start for a Space already deleting does nothing. Fields: id: String, now: i64 |
DeleteFail | The delete failed: the row is back as the registry lists it. Fields: id: String |
DeleteDone | The delete returned: the row goes now, and stays gone while the registry still lists the Space. Fields: id: String |
PowerStart | The power button was pressed: the row says Suspending, Resuming, Turning off or Turning on now and the button waits. A second press while one runs does nothing. Fields: id: String, on: bool, now: i64 |
PowerDone | The SDK's stop or start returned: the row keeps saying so until the registry shows the Space on (or off). Fields: id: String |
PowerFail | It failed: the row shows why, inline, and the button works again. Fields: id: String, error: String |
AppPendingCreate record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | pending:<token>. | |
name | String | Display name. | |
os | AppSpaceOs | Operating system. | |
provider | AppSpaceProvider | Where it runs. | |
started_at / startedAt | i64 | Epoch ms it started. | |
phase | String | The SDK's last phase word (preparing, pulling, ...). | |
fraction | Option<f64> | The phase's fraction, when the SDK knows it. | |
pulled | bool | The image was pulled (the pull takes most of the bar). | |
permille | u32 | Overall progress in thousandths; never goes backwards. | |
error | Option<String> | Why it failed. | |
credit_url / creditUrl | Option<String> | It failed for want of Cua Cloud credit: the billing page. | |
space_id / spaceId | Option<String> | The registered Space's id once it finished; the row goes when the registry lists it. | |
image | Option<String> | The image asked for. | |
kind | Option<AppSpaceKind> | Container or VM. | |
arch | Option<String> | The platform that will run (arm64, amd64). | |
emulated | bool | It runs emulated: a local Space whose platform is not the host's. | |
phase_at / phaseAt | Option<i64> | Epoch ms the current phase began (the time-based progress within a phase that reports no fraction), or last moved (a new fraction): a phase that stays put longer than stall_limit_secs fails the row with stall_error. | |
bytes_done / bytesDone | Option<u64> | Bytes of the download so far, when the SDK counts them. | |
bytes_total / bytesTotal | Option<u64> | Bytes the download has in all. | |
bytes_per_second / bytesPerSecond | Option<f64> | The download's smoothed rate, bytes per second. | |
cancelling | bool | Cancel was pressed: the SDK is stopping the create and removing what it made; the row goes when that ends. | |
gpu | bool | GPU acceleration was asked for. |
AppPendingDelete record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | The Space's id. | |
started_at / startedAt | i64 | Epoch ms the delete started. | |
done | bool | The delete returned: the row stays hidden until the registry stops listing the Space. |
app_creates_compose#The registry's Spaces plus a row per Space being created.
func appCreatesCompose(spaces: [AppSpace], state: AppCreatesState) -> [AppSpace]| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
state | AppCreatesState | required |
Returns Vec<AppSpace>
app_creates_is_deleting#Whether the Space id is being deleted: a Delete for it does nothing.
func appCreatesIsDeleting(state: AppCreatesState, id: String) -> Bool| Parameter | Type | Default |
|---|---|---|
state | AppCreatesState | required |
id | String | required |
Returns bool
app_creates_is_pending#Whether id is a Space still being created (or whose create failed).
func appCreatesIsPending(id: String) -> Bool| Parameter | Type | Default |
|---|---|---|
id | String | required |
Returns bool
app_creates_reduce#Advances the Spaces being created (see spaces::creating).
func appCreatesReduce(state: AppCreatesState, action: AppCreateAction) -> AppCreatesState| Parameter | Type | Default |
|---|---|---|
state | AppCreatesState | required |
action | AppCreateAction | required |
Returns AppCreatesState
app_creates_settle#Drops finished creates the registry lists and finished deletes it no longer lists (after each registry refresh).
func appCreatesSettle(state: AppCreatesState, spaces: [AppSpace]) -> AppCreatesState| Parameter | Type | Default |
|---|---|---|
state | AppCreatesState | required |
spaces | Vec<AppSpace> | required |
Returns AppCreatesState