solari-runloop-compat 0.2.6__tar.gz → 0.2.8__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/COMPAT.md +49 -25
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/PKG-INFO +1 -1
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/pyproject.toml +1 -1
- solari_runloop_compat-0.2.8/solari_runloop/__init__.py +94 -0
- solari_runloop_compat-0.2.8/solari_runloop/_client.py +143 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_dockerfile.py +68 -11
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_gateway.py +303 -73
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_mapping.py +195 -20
- solari_runloop_compat-0.2.8/solari_runloop/_options.py +118 -0
- solari_runloop_compat-0.2.8/solari_runloop/_resources.py +868 -0
- solari_runloop_compat-0.2.8/solari_runloop/_types.py +42 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/pagination.py +6 -2
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/sdk.py +236 -104
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/__init__.py +6 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/blueprint_list_view.py +17 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/devboxes/devbox_snapshot_async_status_view.py +20 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/devboxes/execution_update_chunk.py +15 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/object_download_url_view.py +12 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/object_view.py +45 -0
- solari_runloop_compat-0.2.8/solari_runloop/types/secret_list_view.py +21 -0
- solari_runloop_compat-0.2.6/solari_runloop/__init__.py +0 -42
- solari_runloop_compat-0.2.6/solari_runloop/_client.py +0 -107
- solari_runloop_compat-0.2.6/solari_runloop/_resources.py +0 -417
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/.gitignore +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/LICENSE +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/NOTICE +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/README.md +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_branding.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_config.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_context.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_exceptions.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_loop.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_models.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_redact.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_sync.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/_vendor_user.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/lib/__init__.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/lib/polling.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/blueprint_build_log.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/blueprint_build_logs_list_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/blueprint_build_parameters.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/blueprint_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devbox_async_execution_detail_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devbox_execution_detail_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devbox_snapshot_list_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devbox_snapshot_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devbox_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devboxes/__init__.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/devboxes/devbox_logs_list_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/secret_view.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/__init__.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/after_idle.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/code_mount_parameters.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/launch_parameters.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/lifecycle_configuration.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/lifecycle_hooks.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/shared/resume_triggers.py +0 -0
- {solari_runloop_compat-0.2.6 → solari_runloop_compat-0.2.8}/solari_runloop/types/tunnel_view.py +0 -0
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
## At a glance (2026-10-21 night, verified against the staging integration build `desktop-gateway:staging-3015d4e085a1`)
|
|
4
4
|
- **Works today**: devbox create / retrieve / list (paged) / update (name, metadata) / suspend / resume / keep-alive / shutdown; `cmd.exec` and `exec_async` (with streaming callbacks); file read / write / upload / download; disk snapshots (sync and async, update, create-from-snapshot); open and authenticated **tunnels**; **blueprints** from a Dockerfile (Ubuntu/Debian *or any public image*, `COPY`/`ADD` with a build context); storage objects and object mounts; devbox logs; sizes (capped at 8 vCPU / 16 GiB); Runloop's error classes, retries, pagination and env vars.
|
|
5
5
|
- **Runloop's own example recipes**: 4 of 4 supported ones pass with only the import changed (`devbox_snapshots`, `devbox_snapshot_resume`, `devbox_from_blueprint_lifecycle`, `devbox_tunnel`): 19 checks, 0 failures, run repeatedly. The other three example recipes (`blueprint_with_build_context`, `secrets_with_devbox`, `mcp_github_tools`) need features Solari lacks (see below) and fail loudly with `SolariCompatUnsupported`.
|
|
6
|
-
- **Live test suite** (`pytest -m live`, creates and deletes its own resources): 14 of 15 on the last full run; the one failure was a transient gateway `DependencyUnavailable` (503) on a devbox create, which the client now retries for ~45 s.
|
|
6
|
+
- **Live test suite** (`pytest -m live`, creates and deletes its own resources): 14 of 15 on the last full run; the one failure was a transient gateway `DependencyUnavailable` (503) on a devbox create, which the client now retries for ~45 s. Offline: 290+ unit tests.
|
|
7
7
|
- **Needs a gateway rollout or a key before it works**: named shells (`devbox.shell(name)`: the gateway is live but sandbox images need the new golden pin), durable executions and gateway-side logs (waiting on a Firestore TTL), account secrets (: wired as `sdk.secret.*`, `client.secrets.*` and `devbox.create(secrets={ENV: secret_name})`; answers `SolariCompatUnsupported` while the gateway has no `ORG_SECRETS_KEY`).
|
|
8
|
-
- **Not supported (raises `SolariCompatUnsupported
|
|
8
|
+
- **Not supported (raises `SolariCompatUnsupported`, naming the thing)**: agents, axons, gateways/MCP configs, network policies, restricted keys, SSH keys, PTY tunnels, per-devbox resource usage, blueprint preview, multi-stage Dockerfiles, `STOPSIGNAL`, `EXPOSE .../udp`, `FROM` private registries, `FROM --platform` other than linux/amd64, `code_mounts`, per-call headers / query / body / idempotency keys, `http_client`, custom `default_headers` / `default_query`, `launch_parameters` keys Solari cannot honour (see below). **Nothing is accepted and dropped**: an option or parameter that is not honoured raises, and one that is not Runloop's at all is a `TypeError`.
|
|
9
9
|
|
|
10
10
|
Legend: **OK** works and is tested; **DIFF** works with a behaviour difference (explained); **GATEWAY** waits on a
|
|
11
11
|
gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupported`.
|
|
@@ -16,8 +16,12 @@ gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupp
|
|
|
16
16
|
|---|---|
|
|
17
17
|
| `Runloop(bearer_token=...)` / env `RUNLOOP_API_KEY` | OK, with a safety rule: sources are tried in order (argument, `SOLARI_API_KEY`, `RUNLOOP_API_KEY`) and **a key that does not start with `slr_` is never used or sent** (it is probably a Runloop secret): it is skipped with a warning that does not print it, and if no `slr_` key remains the constructor raises `RunloopError`. An `slr_` key is accepted from any source. |
|
|
18
18
|
| `base_url` / env `RUNLOOP_BASE_URL` (default `https://api.runloop.ai`) | OK. Order: argument, `SOLARI_BASE_URL`, `RUNLOOP_BASE_URL`, default `https://api.getsolari.com`. The argument and `SOLARI_BASE_URL` must point at getsolari.com (https) or loopback, otherwise `RunloopError` ("Refusing to send a Solari API key to …"); `RUNLOOP_BASE_URL` is ignored with a warning unless it does. |
|
|
19
|
-
| `timeout
|
|
20
|
-
| `
|
|
19
|
+
| `timeout` | OK. Seconds (or an `httpx.Timeout` whose four parts are equal): the HTTP request timeout of every transport and the control-channel call timeout; unset or `None` is Solari's default (300 s per request), not "no limit". Per call, `timeout=` stops the wait with `APITimeoutError` (the Solari request already sent is not cancelled). |
|
|
20
|
+
| `default_headers`, `default_query`, `http_client`, `shared_http_pool`, `*_pool_shards`, `_strict_response_validation` | NO when non-empty / non-default: `SolariCompatUnsupported` naming the option. An unknown option is a `TypeError`. |
|
|
21
|
+
| `with_options(timeout=, max_retries=)`, `copy()` | OK: a client that shares this one's connections and executions with other settings. Another key or base URL, headers, query or HTTP client raise. |
|
|
22
|
+
| `with_raw_response`, `with_streaming_response` | NO: `SolariCompatUnsupported`. |
|
|
23
|
+
| Per-call `extra_headers`, `extra_query`, `extra_body`, `idempotency_key` | NO (non-empty): `SolariCompatUnsupported` naming it, before any request is made. `timeout` is honoured. `NOT_GIVEN` / `omit` / `None` mean "not set", as in Runloop. |
|
|
24
|
+
| `max_retries` | OK (default 5), validated (integer >= 0) and applied to **every** transport, including the sandbox client's own: idempotent calls retry on network errors, 502/503/504/507 and `retryable` bodies. |
|
|
21
25
|
| Sync and async (`Runloop`/`AsyncRunloop`, `RunloopSDK`/`AsyncRunloopSDK`) | OK. The sync API drives the async core on one background thread per client (`_loop.py`); don't call it from inside a callback it invoked. |
|
|
22
26
|
|
|
23
27
|
## Object layer (`RunloopSDK`)
|
|
@@ -33,25 +37,37 @@ gateway endpoint (see `GATEWAY-ENDPOINTS.md`); **NO** raises `SolariCompatUnsupp
|
|
|
33
37
|
| `devbox.cmd.exec_async(...)` -> `Execution` | DIFF | `result()`, `get_state()`, `kill()`, `send_std_in()`, `join()` work **inside the creating process** (an in-memory registry). On a gateway with durable executions (detected by probing `GET /sandboxes/{id}/executions`) every command runs through it, so `executions.retrieve / await_completed / kill / send_std_in` also work by `(devbox_id, execution_id)` from **another process**; callbacks are fed by polling the execution (~0.4 s). Against a gateway without it, the in-process registry above is used. `close_std_in` NO. |
|
|
34
38
|
| `devbox.shell(name).exec / exec_async / delete`, `shell_name=` | DIFF | Wired to the gateway's named shells: one persistent bash per name (cwd, env, functions, jobs persist). Output reaches `stdout=/stderr=/output=` callbacks when the command ends, not while it runs; a shell command cannot be killed or given stdin (end the shell with `shell.delete()`). Raises `SolariCompatUnsupported` on a gateway or sandbox image without shells (the guest image needs a new golden). Not yet run against staging: is not deployed. |
|
|
35
39
|
| `devbox.file.read / write / upload / download` | OK, live | Relative paths resolve against `$HOME`; parent dirs are created on write/upload. `upload(file=)` takes bytes, `Path`, str path or a file object. |
|
|
36
|
-
| `devbox.snapshot_disk(name=, commit_message=, metadata=)` / `_async` |
|
|
37
|
-
| `snapshot.get_info /
|
|
40
|
+
| `devbox.snapshot_disk(name=, commit_message=, metadata=)` / `_async` | OK, live | Returns a `Snapshot`. The sync call returns a complete snapshot; the `_async` call really is asynchronous (the gateway answers 202 `pending`) and `snapshot.await_completed()` waits for it. Snapshots are RAM+disk. `name`, `metadata` and `commit_message` are **stored** (the commit message in the snapshot's metadata under the reserved key `runloop.commit_message`, which no view shows in `metadata`) and the stored snapshot is read back and returned, never an echo of the request. At most 1000 characters of commit message and 64 metadata entries (it counts as one). A gateway that kept none of it gets the snapshot deleted and `SolariCompatUnsupported`. |
|
|
41
|
+
| `snapshot.get_info / query_status / await_completed / delete`, `snapshot.list`, `snapshot.from_id` | OK, live | As in Runloop, `get_info`, `query_status` and `await_completed` return a `DevboxSnapshotAsyncStatusView` `{status, error_message, snapshot}`: `in_progress` (gateway `pending`), `complete` (`snapshot` is the `DevboxSnapshotView`), `error` (the gateway's reason in `error_message`; `await_completed` raises `RunloopError("Snapshot ... failed: ...")`), `deleted` (a snapshot this client deleted; any other missing id is `NotFoundError`). `snapshot.update(name=, metadata=, commit_message=)`: OK on a gateway with `PATCH /snapshots/{id}`, else unsupported; `metadata` replaces the visible metadata and keeps the commit message, `commit_message` alone keeps the metadata. Deleting a snapshot with live children is a 409 `ConflictError`. |
|
|
38
42
|
| `devbox.get_tunnel()`, `get_tunnel_url(port)`, `net.enable_tunnel / get_tunnel / remove_tunnel`, create `tunnel={'auth_mode','wake_on_http','http_keep_alive'}` | DIFF, live | Real tunnel API: one switch for every guest port, `https://<label>-<port>.<preview domain>`; `tunnel_key` is the `<label>`. `authenticated` (Solari's default) returns an `auth_token` that must be sent in the **`x-solari-preview-token`** header (Runloop uses `Authorization: Bearer`); `open` needs nothing. `get_tunnel()` returns `None` when no tunnel is enabled (as Runloop). **Difference:** Solari refuses `open` + `wake_on_http` (anonymous traffic could wake and bill a sandbox); the shim raises `SolariCompatUnsupported` for it, use `authenticated`. Checked on 2 gateway replicas: 40/40 requests succeed with the token, 20/20 are refused without it, revocation takes effect within 3 s. On a gateway without the tunnel API it falls back to an open per-port preview URL. |
|
|
39
|
-
| `devbox.logs(execution_id=, shell_name=)` | DIFF |
|
|
40
|
-
| `devbox.create_ssh_key()`, PTY tunnels, gateway/MCP tokens, `watch_evictions` | NO | Runloop platform features. |
|
|
41
|
-
| `blueprint.create(name, dockerfile=, system_setup_commands=, file_mounts=, base_blueprint_name=/id=, build_args=, launch_parameters=)` | DIFF, live | Builds a Solari template from a **Dockerfile subset** and waits for it (`FROM` ubuntu/debian = the native base; **any other public image** (e.g. `python:3.12-alpine`) is built natively by the gateway (`compiled.fromImage`), see the limits below; `RUN ENV ARG WORKDIR ENTRYPOINT CMD`; `COPY`/`ADD` with a `build_context` (see below)
|
|
42
|
-
| `blueprint.from_id / list`, `Blueprint.get_info / logs / delete` | OK, live | `list()` returns your org's custom templates only. `logs()` has no timestamps/levels (Solari returns plain lines). |
|
|
43
|
-
| `storage_object.upload_from_dir/
|
|
44
|
-
| `secret.create / from_name / from_id / update / list / delete`, `Secret.get_info / update / delete`, `client.secrets
|
|
43
|
+
| `devbox.logs(execution_id=, shell_name=)` | DIFF | Everything Solari can tell, merged by time with no row twice: the gateway's `GET /sandboxes/{id}/logs` (durable executions, entrypoint; followed page by page to the end) **plus** the record this client keeps of the commands it ran over the control channel (`cmd.exec`, `execute*`), which never reach the gateway's log. **Limit:** commands another process ran over *its* control channel are in neither source. With no logs route on the gateway and no history of this devbox in this client the call raises `SolariCompatUnsupported` instead of returning `[]`. A local execution id is answered from the local record (the gateway does not know it). `shell_name=` is answered from this client's record of that shell's commands, and raises when this client never used the shell. |
|
|
44
|
+
| `devbox.net.create_ssh_key()`, `devboxes.create_ssh_key`, PTY tunnels, gateway/MCP tokens, `watch_evictions`, `retrieve_resource_usage` | NO | Runloop platform features, or (usage) not reported per devbox by Solari. |
|
|
45
|
+
| `blueprint.create(name, dockerfile=, system_setup_commands=, file_mounts=, base_blueprint_name=/id=, build_args=, build_context=, launch_parameters=)` | DIFF, live | Builds a Solari template from a **Dockerfile subset** and waits for it (`FROM` ubuntu/debian = the native base; **any other public image** (e.g. `python:3.12-alpine`) is built natively by the gateway (`compiled.fromImage`), see the limits below; `RUN ENV ARG WORKDIR ENTRYPOINT CMD`; `SHELL` (JSON form; later shell-form `RUN` / `CMD` / `ENTRYPOINT` run under it); `EXPOSE` (validated; every guest port is reachable through the tunnel, so a TCP port needs nothing more); `COPY`/`ADD` with a `build_context` (see below)). `ENTRYPOINT`/`CMD` are recorded in the image and not started (pass `entrypoint=` to `devboxes.create`). **`LABEL` and `MAINTAINER`** are metadata only: accepted, with one warning per Dockerfile that they are ignored. **Refused by name, never dropped:** `STOPSIGNAL` (a Solari template has no stop signal: remove the line), `EXPOSE .../udp`, `FROM --platform` other than linux/amd64, multi-stage, `USER`, `VOLUME`, `HEALTHCHECK`, `ONBUILD`. `launch_parameters` on a blueprint carries the **size** only (`resource_size_request`, `custom_cpu_cores`, `custom_gb_memory`, `custom_disk_size`, which now also sends the disk size, plus `architecture: x86_64` and `provisioning_tier: standard`); `launch_commands`, `keep_alive_time_seconds`, `after_idle`, `lifecycle`, `user_parameters`, `available_ports`... raise and say to pass them to `devboxes.create`. `metadata`, `code_mounts`, `services`, `secrets`, `network_policy_id` raise. See `BLUEPRINTS.md`. |
|
|
46
|
+
| `blueprint.from_id / list`, `Blueprint.get_info / logs / delete` | OK, live | `list()` returns your org's custom templates only; `name` (substring), `status`, `limit`, `starting_after` and `include_total_count` are honoured (the count is exact when asked for). `blueprints.list_public()` is Solari's built-in sandbox templates (`base`, ...): the ones every account can create from. `logs()` has no timestamps/levels (Solari returns plain lines). `blueprints.preview` -> NO. |
|
|
47
|
+
| `storage_object.create / upload_from_dir / upload_from_bytes / upload_from_text / upload_from_file / list / from_id`, `StorageObject.refresh / complete / upload_content / get_download_url / download_as_bytes / download_as_text / delete`, `as_build_context()` | DIFF | On a gateway with storage objects these are real: `create` opens an object and returns its `upload_url` (`upload_content` PUTs to it, `complete` finishes it), `ttl` (a `timedelta`) or `ttl_ms` sets the expiry, views are Runloop's `ObjectView` (state `UPLOADING` / `READ_ONLY` / `DELETED`; the MIME type maps to `text` / `gzip` / `tgz` / `tar` / `binary`). `metadata` has nowhere to live and `list(search=, starting_after=, state=)`, `get_download_url(duration_seconds=)` have no equivalent: they raise. Without storage objects on the gateway, `upload_from_dir` makes a deterministic `.tar.gz` build context **held by this client** and embedded in the build recipe (capped at ~700 KB compressed, honours `.dockerignore`; `COPY`/`ADD` incl. `--chown`, `--chmod`, globs, `ADD` of a local tar copy from it; `COPY --from`, URLs, `../` sources are refused); the other calls raise `SolariCompatUnsupported`. A context from another process is `SolariCompatUnsupported`. |
|
|
48
|
+
| `secret.create / from_name / from_id / update / list / delete`, `Secret.get_info / update / delete`, `SecretById`, `client.secrets.*` (including `*_by_id`), create `secrets={ENV: secret_name}` | DIFF | Solari account secrets: **write-only** (no route returns a value), names `[A-Za-z][A-Za-z0-9_.-]{0,63}` double as ids (so `from_id(x)` is `from_name(x)` and `retrieve_by_id` is `retrieve`), values up to 16 KiB, 200 per org, at most 20 per create, reserved env names (`LD_*`, `PATH`, `HOME`...) refused. `list(limit=)` says `has_more` when others follow and leaves `total_count` `None` rather than guess; the gateway pages at 100, so a larger `limit` returns one page of 100 with `has_more` set. Not exercised on staging yet: the gateway answers 501 until the org-secrets key exists, and the shim then raises `SolariCompatUnsupported`. |
|
|
45
49
|
| `agent`, `axon`, `network_policy`, `gateway_config`, `mcp_config` | NO | Runloop platform features. |
|
|
46
50
|
|
|
47
51
|
## REST layer (`client.devboxes.*`)
|
|
48
52
|
`create`, `create_and_await_running`, `retrieve`, `list` (auto-paginating, awaitable or `async for`), `shutdown`, `suspend`,
|
|
49
|
-
`resume`, `keep_alive`, `await_running`, `await_suspended`, `execute`, `execute_sync`, `execute_async`,
|
|
53
|
+
`resume`, `keep_alive`, `await_running`, `await_suspended`, `update`, `execute`, `execute_sync`, `execute_async`,
|
|
50
54
|
`execute_and_await_completion`, `wait_for_command`, `read_file_contents`, `write_file_contents`, `upload_file`,
|
|
51
|
-
`download_file`, `snapshot_disk`, `snapshot_disk_async`, `list_disk_snapshots`, `delete_disk_snapshot`, `
|
|
52
|
-
(retrieve, await_completed, kill, send_std_in
|
|
53
|
-
`
|
|
54
|
-
|
|
55
|
+
`download_file`, `snapshot_disk`, `snapshot_disk_async`, `list_disk_snapshots`, `delete_disk_snapshot`, `enable_tunnel`, `remove_tunnel`,
|
|
56
|
+
`executions.*` (retrieve, await_completed, kill, send_std_in, execute_async, execute_sync, stream_stdout_updates, stream_stderr_updates),
|
|
57
|
+
`disk_snapshots.*` (list, update, delete, query_status, await_completed), `logs.list`: **OK** (same caveats as above). Every method takes
|
|
58
|
+
exactly Runloop's parameters. Details that differ from what the old signatures let through:
|
|
59
|
+
- `execute(command_id=, optimistic_timeout=)`: waits up to `optimistic_timeout` seconds (default and maximum 25) and returns the `running` view if the command is still going; `command_id` becomes the execution id (a reused id is a 409). `execute_and_await_completion` waits for completion; `optimistic_timeout` only bounds Runloop's first request, so it changes nothing here. `execute_sync` returns Runloop's `DevboxExecutionDetailView` and refuses `attach_stdin=True` (nothing could write to a command that has to finish first).
|
|
60
|
+
- `wait_for_command(execution_id, *, devbox_id, statuses, last_n, timeout_seconds)` has Runloop's signature (the execution id is first) and, like Runloop's long-poll, answers 408 when the wait runs out.
|
|
61
|
+
- A wait that runs out of time (`await_running`, `await_completed`, `await_build_complete`, ...) raises `PollingTimeout` (`solari_runloop.lib.polling`, as in Runloop's SDK) carrying the last view; the TypeScript package throws `PollingTimeoutError` with `lastResult`.
|
|
62
|
+
- A `polling_config` on a command wait honours `timeout_seconds` only: completion is awaited, not polled, so a non-default `interval_seconds` / `max_attempts` raises.
|
|
63
|
+
- `executions.kill(kill_process_group=True)` and `send_std_in(signal="EOF")` raise (Solari kills the command, and a command handle cannot close stdin); `send_std_in(signal="INTERRUPT")` sends SIGINT to the command. `stream_*_updates` yields the output so far from `offset` and then what the command prints, until it exits (an iterator of `ExecutionUpdateChunk`; it takes no `timeout`).
|
|
64
|
+
- `attach_stdin` on `execute_async` / `exec_async` is satisfied (the control channel can always be written to with `send_std_in`).
|
|
65
|
+
- `shutdown(force=True)` is satisfied (Solari's shutdown always shuts down).
|
|
66
|
+
- `list(include_total_count=True)` counts every matching devbox (it follows all pages); without it `total_count` is `None`. A `status` with no Solari state behind it (`failure`, `suspending`, `resuming`) raises instead of returning an empty list.
|
|
67
|
+
- `list_disk_snapshots` / `disk_snapshots.list`: `devbox_id`, `source_devbox_id`, `limit`, `starting_after`, `name`, `source_blueprint_id` (the snapshot's template) and `include_total_count` are honoured; `total_count` is `None` when more pages exist and the count was not asked for, and when `starting_after` is used. `metadata_key` / `metadata_key_in` raise (Solari cannot filter by metadata).
|
|
68
|
+
- `retrieve_resource_usage`, `create_ssh_key`, `create_pty_tunnel`, `create_gateway_token`, `create_mcp_token`, `watch_evictions`, `blueprints.preview`: NO, `SolariCompatUnsupported` naming the method. `client.accounts`, `agents`, `axons` (and `axons.events`, `axons.sql`), `apikeys`, `restricted_keys`, `pty`, `network_policies`, `gateway_configs`, `mcp_configs`, `objects`: NO at any depth. `with_raw_response` / `with_streaming_response`: NO.
|
|
69
|
+
- `client.blueprints` (create, retrieve, list, list_public, delete, logs, await_build_complete, create_and_await_build_complete): OK (Dockerfile subset). `client.secrets` (including `*_by_id`): OK, see the secrets row.
|
|
70
|
+
- Names importable from `runloop_api_client` that have no meaning here (`DefaultHttpxClient`, `DefaultAsyncHttpxClient`, `Stream`, `AsyncStream`, `APIResponse`, ...) raise `SolariCompatUnsupported` by name on import. `NOT_GIVEN`, `omit`, `Timeout`, `file_from_path`, `BaseModel`, `RequestOptions`, `DEFAULT_TIMEOUT` and `DEFAULT_MAX_RETRIES` are provided.
|
|
55
71
|
|
|
56
72
|
## Create parameters
|
|
57
73
|
| Runloop param | Mapping |
|
|
@@ -64,12 +80,20 @@ await_build_complete, create_and_await_build_complete): OK (Dockerfile subset).
|
|
|
64
80
|
| `file_mounts` | files written after create |
|
|
65
81
|
| `entrypoint` | started in the background after create |
|
|
66
82
|
| `launch_parameters.launch_commands` | run in order after create; a non-zero exit fails the create (and shuts the devbox down) |
|
|
67
|
-
| `launch_parameters.
|
|
68
|
-
| `launch_parameters.
|
|
83
|
+
| `launch_parameters.lifecycle.after_idle` | same as `after_idle`; if both are given they must be equal (`BadRequestError` otherwise) |
|
|
84
|
+
| `launch_parameters.lifecycle.resume_triggers.http` | a wake-on-HTTP tunnel (`auth_mode='authenticated'`, `wake_on_http=True`) is enabled after create; a `tunnel` you pass must already say so, otherwise `SolariCompatUnsupported`. `axon_event` -> NO |
|
|
85
|
+
| `launch_parameters.lifecycle.lifecycle_hooks`, `network_policy_id`, `required_services` | NO |
|
|
86
|
+
| `launch_parameters.architecture`, `provisioning_tier` | `x86_64` / `standard` (or unset) accepted; `arm64` / `flex` -> NO |
|
|
87
|
+
| `launch_parameters.available_ports` | validated (1-65535) and satisfied by design: every guest port is reachable through the tunnel / preview URL (Runloop's own docs call the field deprecated and ignored) |
|
|
88
|
+
| any other `launch_parameters` key, or sub-key of the ones above | NO: `SolariCompatUnsupported` naming it |
|
|
89
|
+
| `launch_parameters.keep_alive_time_seconds` | `timeoutMs`, `lifecycle.onTimeout = "kill"` (Runloop's default is shutdown). Together with `after_idle` (or `lifecycle.after_idle`) it raises `SolariCompatUnsupported`: Solari has one idle timeout, so pass one of them. |
|
|
90
|
+
| `launch_parameters.after_idle {on_idle, idle_time_seconds}` | `timeoutMs`; `on_idle: "suspend"` -> `onTimeout: "pause"`, otherwise `"kill"`. `after_idle` and `lifecycle.after_idle` with different values raise `SolariCompatUnsupported`. |
|
|
69
91
|
| `launch_parameters.resource_size_request`, `custom_cpu_cores`, `custom_gb_memory`, `custom_disk_size` | see sizes |
|
|
70
92
|
| `blueprint_id` | a Solari template id |
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
93
|
+
| `tunnel {auth_mode, wake_on_http, http_keep_alive}` | enables the tunnel right after create (see the tunnel row); an unknown key, an `auth_mode` other than `open` / `authenticated`, and `open` with `wake_on_http` raise |
|
|
94
|
+
| `secrets {ENV: name}` | account secrets injected as env vars (see the secrets row) |
|
|
95
|
+
| `mounts` | `object_mount` only, on a gateway with storage objects; other kinds -> NO |
|
|
96
|
+
| `code_mounts`, `gateways`, `mcp` | NO |
|
|
73
97
|
|
|
74
98
|
### Sizes (cap silently, never error)
|
|
75
99
|
CPU is rounded **up** to a whole vCPU; the result is capped at Solari's limits, **8 vCPU / 16 GiB**, with a `WARNING` on the
|
|
@@ -108,12 +132,12 @@ import) keep working but still lack the image's `ENV`: rebuild them.
|
|
|
108
132
|
Solari-specific: a **429 `ConcurrencyLimitExceeded`** is a `RateLimitError` that the client does NOT retry.
|
|
109
133
|
- IDs are Solari's opaque signed strings (they contain `:` and `.`), not `dbx_...`. Snapshot ids are `snap_...`.
|
|
110
134
|
- Pagination: `devboxes.list()` returns a page with `.devboxes`, `.has_more`, `.has_next_page()`, `.get_next_page()`;
|
|
111
|
-
iterating it (or `async for`) walks every page. `total_count` is
|
|
135
|
+
iterating it (or `async for`) walks every page. `total_count` is `None` unless you pass `include_total_count=True`, which counts every matching devbox. `starting_after` is sent as `startingAfter` to a gateway that supports it (detected from `hasMore` in the list reply); on an older one it is treated as the opaque cursor from a previous page. `list` only returns sandboxes, never desktops.
|
|
112
136
|
- Not retried-for-you: Runloop's long-poll `*_and_await_*` helpers poll with `PollingConfig` (re-exported from
|
|
113
137
|
`solari_runloop.lib.polling`; same fields).
|
|
114
138
|
|
|
115
139
|
## Not compatible, by design
|
|
116
|
-
Persistent 1:1 `dbx_` ids;
|
|
140
|
+
Persistent 1:1 `dbx_` ids; log streaming over SSE (`stream_*_updates` polls the execution); anything under `agents`/`axons`/`gateways`/`mcp`.
|
|
117
141
|
|
|
118
142
|
## Runloop's own examples (import swapped, run against staging by `tests/run_runloop_examples.sh`)
|
|
119
143
|
Last run 2026-10-21 against the F15 integration build `desktop-gateway:staging-190c78afc3e2`: **4 of 4 supported recipes pass (19 checks, 0 failures)**, run twice. Live suite (`pytest -m live`) on the previous build: 14 of 15, the other one a list-lag flake now retried.
|
|
@@ -126,7 +150,7 @@ Last run 2026-10-21 against the F15 integration build `desktop-gateway:staging-1
|
|
|
126
150
|
| `blueprint_with_build_context`, `secrets_with_devbox`, `mcp_github_tools` | not run: storage objects / secret store / MCP are not supported |
|
|
127
151
|
|
|
128
152
|
## Test status
|
|
129
|
-
- `tests/` offline: mappings, config, errors, sync/async surface over a fake gateway.
|
|
153
|
+
- `tests/` offline: mappings, config, errors, sync/async surface over a fake gateway. `test_honest*.py` pin the rule that nothing is accepted and dropped (constructor and per-call options, `launch_parameters`, the Dockerfile, logs, snapshot status and commit messages, the object layer); `test_vendor_surface.py` compares every public method and parameter with the real `runloop_api_client` 2.0.0 when it is installed (`pip install runloop_api_client==2.0.0`).
|
|
130
154
|
- `tests/test_live_staging.py` (`pytest -m live`): quickstart, exec failure/stderr/tail, async exec streaming and kill, file round-trips,
|
|
131
155
|
list/retrieve/pagination, suspend/resume state, snapshot -> create from snapshot, errors, size capping. See the PR for the latest run.
|
|
132
156
|
|
|
@@ -149,4 +173,4 @@ sudo). Restores from a snapshot keep the snapshot's own user.
|
|
|
149
173
|
- Error messages carry only the first 8 characters of a sandbox id.
|
|
150
174
|
- `list_disk_snapshots` returns a list that also has `.snapshots`, `.has_more` and `.total_count`, the same shape as the TypeScript package.
|
|
151
175
|
- `devboxes.execute_sync` / `execute_and_await_completion` run over the control channel, so output is never truncated (the gateway's durable executions keep only the last 256 KiB, and are still used by `execute_async`).
|
|
152
|
-
- `launch_parameters.user_parameters` `{username, uid}` sets the create user (`username`, home `/home/<username>`, `/root` for `root`); the gateway picks the uid, so
|
|
176
|
+
- `launch_parameters.user_parameters` `{username, uid}` sets the create user (`username`, home `/home/<username>`, `/root` for `root`); the gateway picks the uid, so the requested `uid` is checked against the created user's real uid after create and a mismatch fails the create (the devbox is shut down) with `SolariCompatUnsupported`; it is never quietly different. On a gateway without user support this raises `SolariCompatUnsupported` instead of running as root.
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "solari-runloop-compat"
|
|
7
|
-
version = "0.2.
|
|
7
|
+
version = "0.2.8"
|
|
8
8
|
description = "Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.9"
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
"""Runloop-compatible interface over the Solari sandbox gateway.
|
|
2
|
+
|
|
3
|
+
Not affiliated with Runloop. See COMPAT.md for exactly which parts of the Runloop SDK are supported.
|
|
4
|
+
Change ``from runloop_api_client import RunloopSDK`` to ``from solari_runloop import RunloopSDK``.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing_extensions import TypedDict
|
|
10
|
+
|
|
11
|
+
from . import types
|
|
12
|
+
from ._branding import TARGET_RUNLOOP_VERSION
|
|
13
|
+
from ._client import AsyncRunloop, Runloop
|
|
14
|
+
from ._exceptions import (
|
|
15
|
+
APIError,
|
|
16
|
+
APIStatusError,
|
|
17
|
+
ConflictError,
|
|
18
|
+
NotFoundError,
|
|
19
|
+
RateLimitError,
|
|
20
|
+
RunloopError,
|
|
21
|
+
BadRequestError,
|
|
22
|
+
APITimeoutError,
|
|
23
|
+
APIConnectionError,
|
|
24
|
+
AuthenticationError,
|
|
25
|
+
InternalServerError,
|
|
26
|
+
PermissionDeniedError,
|
|
27
|
+
SolariCompatUnsupported,
|
|
28
|
+
UnprocessableEntityError,
|
|
29
|
+
APIResponseValidationError,
|
|
30
|
+
)
|
|
31
|
+
from ._models import BaseModel
|
|
32
|
+
from ._types import NOT_GIVEN, NoneType, NotGiven, Omit, Timeout, not_given, omit
|
|
33
|
+
from .lib.polling import PollingConfig, PollingTimeout
|
|
34
|
+
from .sdk import AsyncRunloopSDK, RunloopSDK
|
|
35
|
+
|
|
36
|
+
__version__ = "0.2.8"
|
|
37
|
+
Client = Runloop
|
|
38
|
+
AsyncClient = AsyncRunloop
|
|
39
|
+
|
|
40
|
+
#: Solari's HTTP request timeout when none is given (seconds, all four httpx components equal), and its retry count.
|
|
41
|
+
DEFAULT_TIMEOUT = Timeout(300.0)
|
|
42
|
+
DEFAULT_MAX_RETRIES = 5
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def file_from_path(path: str) -> "tuple[str, bytes]":
|
|
46
|
+
"""Runloop's helper: ``(file name, contents)``, accepted by ``upload_file(file=...)``."""
|
|
47
|
+
import os
|
|
48
|
+
|
|
49
|
+
with open(path, "rb") as f:
|
|
50
|
+
return os.path.basename(path), f.read()
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class RequestOptions(TypedDict, total=False):
|
|
54
|
+
"""Runloop's per-call options type. Only ``timeout`` is honoured; the others raise ``SolariCompatUnsupported`` when set."""
|
|
55
|
+
|
|
56
|
+
extra_headers: object
|
|
57
|
+
extra_query: object
|
|
58
|
+
extra_body: object
|
|
59
|
+
timeout: object
|
|
60
|
+
idempotency_key: str
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
#: Names Runloop's package exports that have no meaning over Solari (its HTTP stack and response wrappers): importing one raises
|
|
64
|
+
#: SolariCompatUnsupported with the name instead of an ImportError that looks like a missing package.
|
|
65
|
+
_UNSUPPORTED_NAMES = {
|
|
66
|
+
"DefaultHttpxClient": "Solari's transport is not configurable; use `timeout` and `max_retries`.",
|
|
67
|
+
"DefaultAsyncHttpxClient": "Solari's transport is not configurable; use `timeout` and `max_retries`.",
|
|
68
|
+
"DefaultAioHttpClient": "Solari's transport is not configurable; use `timeout` and `max_retries`.",
|
|
69
|
+
"DEFAULT_CONNECTION_LIMITS": "The HTTP connection pool is not configurable.",
|
|
70
|
+
"Transport": "Solari's transport is not configurable.",
|
|
71
|
+
"ProxiesTypes": "Solari's transport is not configurable.",
|
|
72
|
+
"APIResponse": "Raw response wrappers (with_raw_response / with_streaming_response) are not provided.",
|
|
73
|
+
"AsyncAPIResponse": "Raw response wrappers (with_raw_response / with_streaming_response) are not provided.",
|
|
74
|
+
"Stream": "Server-sent-event streams are not exposed; executions.stream_*_updates return an iterator of chunks.",
|
|
75
|
+
"AsyncStream": "Server-sent-event streams are not exposed; executions.stream_*_updates return an iterator of chunks.",
|
|
76
|
+
"resources": "Use client.devboxes / client.blueprints / client.secrets.",
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def __getattr__(name: str): # type: ignore[no-untyped-def]
|
|
81
|
+
if name in _UNSUPPORTED_NAMES:
|
|
82
|
+
raise SolariCompatUnsupported(name, _UNSUPPORTED_NAMES[name])
|
|
83
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
__all__ = [
|
|
87
|
+
"Runloop", "AsyncRunloop", "RunloopSDK", "AsyncRunloopSDK", "Client", "AsyncClient",
|
|
88
|
+
"RunloopError", "APIError", "APIStatusError", "APIConnectionError", "APITimeoutError",
|
|
89
|
+
"APIResponseValidationError", "BadRequestError", "AuthenticationError", "PermissionDeniedError",
|
|
90
|
+
"NotFoundError", "ConflictError", "UnprocessableEntityError", "RateLimitError", "InternalServerError",
|
|
91
|
+
"SolariCompatUnsupported", "PollingConfig", "PollingTimeout", "types", "TARGET_RUNLOOP_VERSION",
|
|
92
|
+
"NOT_GIVEN", "NotGiven", "not_given", "Omit", "omit", "NoneType", "Timeout", "BaseModel", "DEFAULT_TIMEOUT", "DEFAULT_MAX_RETRIES",
|
|
93
|
+
"file_from_path", "RequestOptions",
|
|
94
|
+
]
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
"""``Runloop`` / ``AsyncRunloop``: the REST-style client (``client.devboxes.*``)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any, Optional
|
|
6
|
+
|
|
7
|
+
from . import _config
|
|
8
|
+
from . import _exceptions as ex
|
|
9
|
+
from ._gateway import Gateway
|
|
10
|
+
from ._loop import LoopThread
|
|
11
|
+
from ._options import client_options, timeout_seconds, validate_int
|
|
12
|
+
from ._resources import AsyncBlueprints, AsyncDevboxes, AsyncSecrets, _Unsupported
|
|
13
|
+
from ._sync import SyncMirror
|
|
14
|
+
from ._types import NotGiven, not_given
|
|
15
|
+
|
|
16
|
+
DEFAULT_MAX_RETRIES = 5
|
|
17
|
+
|
|
18
|
+
_UNSUPPORTED_RESOURCES = {
|
|
19
|
+
"objects": "Storage objects have no Solari equivalent yet.",
|
|
20
|
+
"agents": "Agents are a Runloop platform feature.",
|
|
21
|
+
"axons": "Axons are a Runloop platform feature.",
|
|
22
|
+
"network_policies": "Network policies have no Solari equivalent.",
|
|
23
|
+
"gateway_configs": "Agent gateways are a Runloop platform feature.",
|
|
24
|
+
"mcp_configs": "MCP configs are a Runloop platform feature.",
|
|
25
|
+
"accounts": "Accounts are a Runloop platform feature.",
|
|
26
|
+
"apikeys": "API keys are managed in the Solari console.",
|
|
27
|
+
"restricted_keys": "Restricted keys are a Runloop platform feature.",
|
|
28
|
+
"pty": "PTY tunnels are not exposed through the compat layer.",
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class AsyncRunloop:
|
|
33
|
+
"""Async REST client.
|
|
34
|
+
|
|
35
|
+
Honoured: ``bearer_token``, ``base_url``, ``timeout`` (seconds: the HTTP request timeout and the control-channel call
|
|
36
|
+
timeout) and ``max_retries`` (Solari's transport retries). ``default_headers`` / ``default_query`` (non-empty),
|
|
37
|
+
``http_client`` and the pool-tuning options raise :class:`SolariCompatUnsupported`; an unknown option is a ``TypeError``.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
_solari_mirror = False
|
|
41
|
+
|
|
42
|
+
def __init__(
|
|
43
|
+
self,
|
|
44
|
+
*,
|
|
45
|
+
bearer_token: Optional[str] = None,
|
|
46
|
+
base_url: Any = None,
|
|
47
|
+
timeout: Any = not_given,
|
|
48
|
+
max_retries: int = DEFAULT_MAX_RETRIES,
|
|
49
|
+
**options: Any,
|
|
50
|
+
) -> None:
|
|
51
|
+
client_options(dict(options, bearer_token=bearer_token, base_url=base_url, timeout=timeout, max_retries=max_retries), rest_client=True)
|
|
52
|
+
token, url = _config.resolve(bearer_token, str(base_url) if base_url is not None else None)
|
|
53
|
+
seconds = timeout_seconds(timeout, "timeout")
|
|
54
|
+
self.bearer_token = token
|
|
55
|
+
self.base_url = url
|
|
56
|
+
self.max_retries = validate_int("max_retries", max_retries)
|
|
57
|
+
self.timeout = seconds
|
|
58
|
+
ms = int(seconds * 1000) if seconds else None
|
|
59
|
+
self._attach(Gateway(token=token, base_url=url, max_retries=self.max_retries, call_timeout_ms=ms, request_timeout_ms=ms))
|
|
60
|
+
|
|
61
|
+
def _attach(self, gw: Gateway) -> None:
|
|
62
|
+
self._gw = gw
|
|
63
|
+
self.devboxes = AsyncDevboxes(gw)
|
|
64
|
+
self.blueprints = AsyncBlueprints(gw)
|
|
65
|
+
self.secrets = AsyncSecrets(gw)
|
|
66
|
+
for name, hint in _UNSUPPORTED_RESOURCES.items():
|
|
67
|
+
setattr(self, name, _Unsupported(name, hint))
|
|
68
|
+
for wrapper in ("with_raw_response", "with_streaming_response"):
|
|
69
|
+
setattr(self, wrapper, _Unsupported(wrapper, "Solari has no HTTP response to wrap; use the methods directly."))
|
|
70
|
+
|
|
71
|
+
def with_options(self, *, timeout: Any = not_given, max_retries: Any = not_given, **options: Any) -> "AsyncRunloop":
|
|
72
|
+
"""A client with other ``timeout`` / ``max_retries`` that shares this client's connections and executions. Runloop's
|
|
73
|
+
other ``with_options`` arguments (another key or base URL, headers, query, HTTP client) raise."""
|
|
74
|
+
for key in ("bearer_token", "base_url", "http_client", "default_headers", "set_default_headers", "default_query", "set_default_query", "shared_http_pool", "api_pool_shards", "background_pool_shards", "transfer_pool_shards", "_extra_kwargs"):
|
|
75
|
+
if options.pop(key, None):
|
|
76
|
+
raise ex.SolariCompatUnsupported(f"with_options({key}=...)", "Only timeout and max_retries can be changed; create another client for another key or URL.")
|
|
77
|
+
if options:
|
|
78
|
+
raise TypeError(f"unexpected keyword argument(s): {', '.join(sorted(options))}")
|
|
79
|
+
seconds = timeout_seconds(timeout, "timeout")
|
|
80
|
+
retries = None if isinstance(max_retries, NotGiven) or max_retries is None else validate_int("max_retries", max_retries)
|
|
81
|
+
view = self.__class__.__new__(self.__class__)
|
|
82
|
+
view.bearer_token, view.base_url = self.bearer_token, self.base_url
|
|
83
|
+
view.max_retries = self.max_retries if retries is None else retries
|
|
84
|
+
view.timeout = seconds if seconds else self.timeout
|
|
85
|
+
view._attach(self._gw.with_options(max_retries=retries, timeout_ms=int(seconds * 1000) if seconds else None))
|
|
86
|
+
return view
|
|
87
|
+
|
|
88
|
+
copy = with_options
|
|
89
|
+
|
|
90
|
+
async def close(self) -> None:
|
|
91
|
+
await self._gw.aclose()
|
|
92
|
+
|
|
93
|
+
async def __aenter__(self) -> "AsyncRunloop":
|
|
94
|
+
return self
|
|
95
|
+
|
|
96
|
+
async def __aexit__(self, *_exc: Any) -> None:
|
|
97
|
+
await self.close()
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
class Runloop:
|
|
101
|
+
"""Sync REST client: the async client driven from a background event loop (see ``_loop.py``)."""
|
|
102
|
+
|
|
103
|
+
def __init__(self, **kwargs: Any) -> None:
|
|
104
|
+
self._attach(AsyncRunloop(**kwargs), LoopThread())
|
|
105
|
+
|
|
106
|
+
@classmethod
|
|
107
|
+
def _wrapping(cls, inner: AsyncRunloop, loop: LoopThread) -> "Runloop":
|
|
108
|
+
"""A sync view of an existing async client (used by ``RunloopSDK`` so both share one loop)."""
|
|
109
|
+
self = cls.__new__(cls)
|
|
110
|
+
self._attach(inner, loop)
|
|
111
|
+
return self
|
|
112
|
+
|
|
113
|
+
def _attach(self, inner: AsyncRunloop, loop: LoopThread) -> None:
|
|
114
|
+
self._loop = loop
|
|
115
|
+
self._inner = inner
|
|
116
|
+
self._shares_loop = False
|
|
117
|
+
self.bearer_token = self._inner.bearer_token
|
|
118
|
+
self.base_url = self._inner.base_url
|
|
119
|
+
self.max_retries = self._inner.max_retries
|
|
120
|
+
self.timeout = self._inner.timeout
|
|
121
|
+
self.devboxes = SyncMirror(self._inner.devboxes, self._loop)
|
|
122
|
+
self.blueprints = SyncMirror(self._inner.blueprints, self._loop)
|
|
123
|
+
self.secrets = SyncMirror(self._inner.secrets, self._loop)
|
|
124
|
+
for name in (*_UNSUPPORTED_RESOURCES, "with_raw_response", "with_streaming_response"):
|
|
125
|
+
setattr(self, name, getattr(self._inner, name))
|
|
126
|
+
|
|
127
|
+
def with_options(self, **options: Any) -> "Runloop":
|
|
128
|
+
view = Runloop._wrapping(self._inner.with_options(**options), self._loop)
|
|
129
|
+
view._shares_loop = True
|
|
130
|
+
return view
|
|
131
|
+
|
|
132
|
+
copy = with_options
|
|
133
|
+
|
|
134
|
+
def close(self) -> None:
|
|
135
|
+
self._loop.run(self._inner.close())
|
|
136
|
+
if not self._shares_loop:
|
|
137
|
+
self._loop.close()
|
|
138
|
+
|
|
139
|
+
def __enter__(self) -> "Runloop":
|
|
140
|
+
return self
|
|
141
|
+
|
|
142
|
+
def __exit__(self, *_exc: Any) -> None:
|
|
143
|
+
self.close()
|
|
@@ -7,8 +7,11 @@ that model can do faithfully; everything else raises :class:`SolariCompatUnsuppo
|
|
|
7
7
|
|
|
8
8
|
Supported: ``FROM`` (one stage; ubuntu/debian-family or a Solari base/template map to the native base, any other public
|
|
9
9
|
image becomes the gateway's native ``compiled.fromImage`` build, BLUEPRINTS.md level 3b), ``RUN``, ``ENV``, ``ARG`` (defaults and
|
|
10
|
-
``--build-arg``), ``WORKDIR``, ``ENTRYPOINT``, ``CMD
|
|
11
|
-
|
|
10
|
+
``--build-arg``), ``WORKDIR``, ``ENTRYPOINT``, ``CMD`` (recorded in the image, not started: pass ``entrypoint=`` to ``devboxes.create``), ``SHELL``
|
|
11
|
+
(exec form; later shell-form ``RUN``/``CMD``/``ENTRYPOINT`` use it), ``EXPOSE`` (validated; every guest port is reachable through the
|
|
12
|
+
tunnel, so a TCP port needs nothing more). ``LABEL`` and ``MAINTAINER`` are metadata only: accepted with one warning that says they are not recorded. Refused, never dropped: ``STOPSIGNAL`` (a Solari template has
|
|
13
|
+
no stop signal), ``EXPOSE .../udp``, ``FROM --platform`` other than linux/amd64, multi-stage, ``USER``, ``VOLUME``, ``HEALTHCHECK``,
|
|
14
|
+
``ONBUILD``.
|
|
12
15
|
"""
|
|
13
16
|
|
|
14
17
|
from __future__ import annotations
|
|
@@ -79,7 +82,8 @@ def _subst(s: str, args: Dict[str, str], only: Optional[set] = None) -> str:
|
|
|
79
82
|
return re.sub(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))", rep, s)
|
|
80
83
|
|
|
81
84
|
|
|
82
|
-
def _json_or_shell(rest: str) -> List[str]:
|
|
85
|
+
def _json_or_shell(rest: str, shell: Optional[List[str]] = None) -> List[str]:
|
|
86
|
+
"""Exec form as given; shell form runs under the Dockerfile's ``SHELL`` (default ``/bin/sh -c``)."""
|
|
83
87
|
rest = rest.strip()
|
|
84
88
|
if rest.startswith("["):
|
|
85
89
|
try:
|
|
@@ -88,7 +92,35 @@ def _json_or_shell(rest: str) -> List[str]:
|
|
|
88
92
|
return v
|
|
89
93
|
except ValueError:
|
|
90
94
|
pass
|
|
91
|
-
return ["/bin/sh", "-c", rest]
|
|
95
|
+
return [*(shell or ["/bin/sh", "-c"]), rest]
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _parse_shell(rest: str) -> List[str]:
|
|
99
|
+
"""``SHELL ["/bin/bash", "-o", "pipefail", "-c"]``: Docker requires the JSON exec form."""
|
|
100
|
+
try:
|
|
101
|
+
v = json.loads(rest.strip())
|
|
102
|
+
except ValueError:
|
|
103
|
+
v = None
|
|
104
|
+
if not (isinstance(v, list) and v and all(isinstance(x, str) and x for x in v)):
|
|
105
|
+
raise ex.SolariCompatUnsupported(f"SHELL {rest}", 'SHELL takes the JSON form, for example SHELL ["/bin/bash", "-c"].')
|
|
106
|
+
return v
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _check_expose(rest: str, args: Dict[str, str]) -> None:
|
|
110
|
+
"""``EXPOSE 80 443/tcp 8000-8010``: validated, then satisfied by design (every guest port is reachable through the
|
|
111
|
+
tunnel / preview URL). UDP has no equivalent (previews are TCP/HTTP) and raises."""
|
|
112
|
+
tokens = _subst(rest, args).split()
|
|
113
|
+
if not tokens:
|
|
114
|
+
raise ex.SolariCompatUnsupported("EXPOSE without a port")
|
|
115
|
+
for tok in tokens:
|
|
116
|
+
m = re.fullmatch(r"(\d{1,5})(?:-(\d{1,5}))?(?:/(tcp|udp))?", tok, re.I)
|
|
117
|
+
if not m:
|
|
118
|
+
raise ex.SolariCompatUnsupported(f"EXPOSE {tok}", "Use N, N/tcp or N-M.")
|
|
119
|
+
lo, hi = int(m.group(1)), int(m.group(2) or m.group(1))
|
|
120
|
+
if not (1 <= lo <= hi <= 65535):
|
|
121
|
+
raise ex.SolariCompatUnsupported(f"EXPOSE {tok}", "Ports are 1-65535 and a range runs low to high.")
|
|
122
|
+
if (m.group(3) or "tcp").lower() == "udp":
|
|
123
|
+
raise ex.SolariCompatUnsupported(f"EXPOSE {tok}", "Solari tunnels and preview URLs carry TCP/HTTP only.")
|
|
92
124
|
|
|
93
125
|
|
|
94
126
|
def _parse_env(rest: str) -> List[Tuple[str, str]]:
|
|
@@ -106,6 +138,12 @@ def _registry_of(image: str) -> str:
|
|
|
106
138
|
|
|
107
139
|
def _resolve_from(rest: str, args: Dict[str, str]) -> Tuple[Optional[str], Optional[str], Optional[str]]:
|
|
108
140
|
"""-> ``(base, from_template, from_image)`` for the CompiledImage."""
|
|
141
|
+
for flag in (t for t in rest.split() if t.startswith("--")):
|
|
142
|
+
if flag.split("=", 1)[0] != "--platform":
|
|
143
|
+
raise ex.SolariCompatUnsupported(f"FROM {flag.split('=', 1)[0]}")
|
|
144
|
+
platform = _subst(flag.partition("=")[2], args).strip()
|
|
145
|
+
if platform not in ("", "linux/amd64", "linux/x86_64"):
|
|
146
|
+
raise ex.SolariCompatUnsupported(f"FROM --platform={platform}", "Solari sandboxes are linux/amd64.")
|
|
109
147
|
tokens = [t for t in rest.split() if not t.startswith("--")]
|
|
110
148
|
if "AS" in [t.upper() for t in tokens[1:]]:
|
|
111
149
|
raise ex.SolariCompatUnsupported("Multi-stage Dockerfile (FROM ... AS)", "Single-stage builds only.")
|
|
@@ -157,6 +195,8 @@ def compile_dockerfile(
|
|
|
157
195
|
arg_names: set = set(build_args or {}) # ARG / --build-arg names: expanded here; ENV names are expanded by the gateway
|
|
158
196
|
workdir = "/"
|
|
159
197
|
context_loaded = False
|
|
198
|
+
warned_metadata = False
|
|
199
|
+
shell: Optional[List[str]] = None # the Dockerfile's SHELL; None = Docker's default (/bin/sh -c)
|
|
160
200
|
|
|
161
201
|
for instr, rest in logical_lines(dockerfile or ""):
|
|
162
202
|
if instr == "FROM":
|
|
@@ -187,7 +227,12 @@ def compile_dockerfile(
|
|
|
187
227
|
arg_names.discard(k)
|
|
188
228
|
steps.append({"op": "env", "key": k, "value": v})
|
|
189
229
|
elif instr == "RUN":
|
|
190
|
-
|
|
230
|
+
if rest.startswith("["):
|
|
231
|
+
cmd = " ".join(shlex.quote(a) for a in json.loads(rest)) # exec form bypasses SHELL
|
|
232
|
+
else:
|
|
233
|
+
cmd = _subst_run(rest, arg_only)
|
|
234
|
+
if shell:
|
|
235
|
+
cmd = " ".join(shlex.quote(a) for a in [*shell, cmd])
|
|
191
236
|
steps.append(_run(cmd))
|
|
192
237
|
elif instr == "WORKDIR":
|
|
193
238
|
wd = _subst(rest, args)
|
|
@@ -195,16 +240,28 @@ def compile_dockerfile(
|
|
|
195
240
|
workdir = wd
|
|
196
241
|
steps.append({"op": "workdir", "dir": wd})
|
|
197
242
|
elif instr == "ENTRYPOINT":
|
|
198
|
-
cmdv = _json_or_shell(_subst(rest, args))
|
|
243
|
+
cmdv = _json_or_shell(_subst(rest, args), shell)
|
|
199
244
|
steps.append({"op": "entrypoint", "command": cmdv})
|
|
200
245
|
elif instr == "CMD":
|
|
201
|
-
cmdv = _json_or_shell(_subst(rest, args))
|
|
246
|
+
cmdv = _json_or_shell(_subst(rest, args), shell)
|
|
202
247
|
steps.append({"op": "cmd", "command": cmdv})
|
|
203
|
-
elif instr in ("LABEL", "
|
|
204
|
-
|
|
248
|
+
elif instr in ("LABEL", "MAINTAINER"):
|
|
249
|
+
# Metadata only: it cannot change how the image runs. Accepted, with one warning per Dockerfile.
|
|
250
|
+
if not warned_metadata:
|
|
251
|
+
warned_metadata = True
|
|
252
|
+
log.warning(
|
|
253
|
+
"Dockerfile %s is ignored: a Solari template stores no image labels, so they are not recorded or readable later; the devbox runs the same without them. Remove LABEL / MAINTAINER lines to silence this warning",
|
|
254
|
+
instr,
|
|
255
|
+
)
|
|
256
|
+
elif instr == "STOPSIGNAL":
|
|
257
|
+
raise ex.SolariCompatUnsupported(
|
|
258
|
+
instr,
|
|
259
|
+
"A Solari template has no stop signal, so this line would be lost. Remove it from the Dockerfile.",
|
|
260
|
+
)
|
|
261
|
+
elif instr == "EXPOSE":
|
|
262
|
+
_check_expose(rest, args)
|
|
205
263
|
elif instr == "SHELL":
|
|
206
|
-
|
|
207
|
-
raise ex.SolariCompatUnsupported("SHELL " + rest)
|
|
264
|
+
shell = _parse_shell(rest)
|
|
208
265
|
elif instr in ("COPY", "ADD"):
|
|
209
266
|
if context is None:
|
|
210
267
|
raise ex.SolariCompatUnsupported(instr, "No build_context was given. Upload one with sdk.storage_object.upload_from_dir(...) and pass build_context=obj.as_build_context().")
|