cordium-sdk 0.2.0__tar.gz

cordium_sdk-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cordium_sdk-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py

cordium_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: cordium-sdk
+Version: 0.2.0
+Summary: The synchronous and asynchronous Python SDK for Cordium workspaces
+Author-email: Octelium <contact@octelium.com>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/octelium/sdk-python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: octelium-apis<2,>=1.0.3
+Requires-Dist: betterproto==2.0.0b7
+Requires-Dist: grpclib<0.5,>=0.4.8
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# Cordium Python SDK
+
+Typed synchronous and native `asyncio` clients for [Cordium](https://github.com/octelium/cordium) workspaces. Python 3.11+.
+
+The SDK covers workspaces, execution, files, persistent terminals, logs, events, templates and builds, snapshots, volumes, Spaces, Secrets, Git providers, memberships, regions, and configuration. Generated protobuf messages remain available for the full API.
+
+## Installation
+
+From this checkout:
+
+```bash
+python -m pip install ./packages/apis ./packages/cordium
+```
+
+The distribution is `cordium-sdk`; the import is `cordium`. It requires the accompanying `octelium-apis>=1.0.3` bindings. Both packages must be released before a registry-only install of this version will work.
+
+```bash
+export CORDIUM_DOMAIN=example.com
+export OCTELIUM_AUTH_TOKEN='<your authentication token>'
+```
+
+The client connects to `octelium-api.<domain>:443` with verified TLS. Construction is lazy; the first request authenticates.
+
+## Start with the blocking client
+
+```python
+from cordium import Cordium, Resources
+
+with Cordium() as client:
+    workspace = client.workspaces.run(
+        image="python:3.13",
+        resources=Resources(cpu=1000, memory=1024),
+        ephemeral=True,
+        timeout=300,
+    )
+    try:
+        result = workspace.exec(["python", "-c", "print('Hello from Cordium')"])
+        print(result.stdout)
+        workspace.files.write_text("/workspace/hello.txt", "Hello!\n")
+    finally:
+        workspace.stop().wait_until_stopped()
+        workspace.delete()
+```
+
+`create()` returns a stopped workspace. `run()` creates, starts, and waits for `RUNNING` under one total deadline. A failed `run()` leaves the workspace for diagnosis. A `WorkspaceFailureError` carries its resource in `.workspace`; other SDK errors expose `.code`, `.details`, and their underlying `__cause__` when available.
+
+**Client context exit closes connections and cancels operations; it does not stop or delete workspaces.** Ephemeral workspaces discard storage on stop but retain their resource object until explicitly deleted.
+
+All examples assume access to an existing Cordium Cluster and permission for the requested operations. No Cluster is provisioned by the SDK.
+
+## Native async
+
+```python
+import asyncio
+from cordium import AsyncCordium
+
+async def main() -> None:
+    async with AsyncCordium() as client:
+        workspace = await client.workspaces.run(image="python:3.13")
+        try:
+            async with asyncio.TaskGroup() as group:
+                version = group.create_task(workspace.exec(["python", "--version"]))
+                platform = group.create_task(workspace.exec(["uname", "-a"]))
+            print(version.result().stdout, platform.result().stdout)
+        finally:
+            await workspace.stop()
+            await workspace.wait_until_stopped()
+            await workspace.delete()
+
+asyncio.run(main())
+```
+
+Async methods and their blocking counterparts use the same names, arguments, and result types. Async streams use `async for`, `async with`, and `aclose()`; blocking streams use `for`, `with`, and `close()`. `AsyncCordium` belongs to one event loop. `Cordium` owns one event-loop thread and supports calls from multiple threads. Create a new client after `fork`; do not share a client across processes. Use `AsyncCordium` in async applications so the application loop remains responsive.
+
+## Configuration and references
+
+```python
+from cordium import Application, Ref, Resources, SecretRef, Task, VolumeMount
+
+workspace = client.workspaces.create(
+    template="python.team.cordium",
+    display_name="data processing",
+    env={"MODE": "development", "API_KEY": SecretRef("api-key")},
+    vars={"branch": "main"},
+    resources=Resources(cpu=2000, memory=2048, storage=10000),
+    applications=[Application("api", 8000, default=True)],
+    tasks=[Task(name="setup", command="python -m pip install -r requirements.txt")],
+    volumes=[VolumeMount("data.team.cordium", "/data")],
+)
+workspace.start(region=Ref(uid="region-uid"), vars={"branch": "release"})
+workspace.wait_until_running()
+```
+
+CPU uses **millicores**; memory and storage use **megabytes**, following the protobuf API. Omitted values inherit Cluster/template/Space policy. `SecretRef` resolves a Space Secret without exposing its value locally. Start-time variables and region selection apply only to that run.
+
+Methods accepting a reference take a name string or `Ref(uid="...")`. Space-scoped resource names may be qualified, such as `python.team.cordium`. Workspace names are assigned by the Cluster. `template` and `snapshot` are exclusive; a snapshot restore cannot be ephemeral. Templates cannot declare workspace applications or ephemeral storage.
+
+Convenience fields replace the corresponding fields of a copied `spec=` message. Lists replace, rather than append. `create_workspace_spec(...)` builds the same validated spec without network I/O. For advanced image sources, repository authentication, networking, capabilities, filesystem policy, devcontainer features, and additional repositories, supply generated messages through `spec=`. Source template/snapshot references are creation options, not persisted spec fields.
+
+Workspace properties (`name`, `uid`, `state`, `hostname`, `url`, `spec`, `status`, `proto`, etc.) read a local cache. `refresh()`, lifecycle methods, and waits refresh it. Protobuf properties return deep copies. `wait_until_ready()` accepts `PREPARING`, when exec is available but setup is still running; `wait_until_running()` waits for setup to finish. Watch events do not silently mutate existing handles.
+
+## Commands and streaming
+
+A command string runs as a shell expression. A sequence of strings is safely quoted as literal argv. `argv(...)` and `shell_quote(...)` are available for composing commands. NUL bytes in shell arguments are rejected. `cwd=`, `env=`, and `root=True` configure execution.
+
+```python
+from cordium import ExecError
+
+try:
+    result = workspace.exec(["python", "script.py"], timeout=60)
+except ExecError as error:
+    print(error.result.exit_code, error.result.stderr)
+
+with workspace.exec_stream("python -u server.py", timeout=60) as command:
+    for event in command:
+        print(event.stream, event.data)  # bytes; chunk boundaries need not be UTF-8 boundaries
+    result = command.wait()
+```
+
+`exec()` defaults to `check=True`, raising `ExecError` for nonzero exit. `exec_stream()` defaults to `check=False`, allowing inspection of the exit status after streaming. `ExecResult` includes `exit_code`, `stdout_bytes`, `stderr_bytes`, `success`, `truncated`, and `killed`. Its `.stdout`/`.stderr` properties decode UTF-8 with replacement; use bytes for exact data.
+
+Captures are limited to 1 MiB **per output stream** by default. Excess capture sets `truncated`; it does not stop output iteration. Stream queues default to 8 MiB and also have an event-count limit; a stalled consumer gets `RESOURCE_EXHAUSTED` instead of unbounded memory growth. Configure `max_capture_bytes` and `max_buffer_bytes` as needed. Calling `wait()` before output iteration selects drain-only mode. After iteration begins, continue consuming output while waiting for completion.
+
+For interactive input, use `command.write(str_or_bytes)` and `command.kill()`. `stdin=` sends initial data. **The Exec protocol has no independent stdin EOF message.** A command reading until EOF can remain blocked; use explicit framing such as `head -c 4` when sending four bytes. The file helpers handle this framing automatically. Cancelling/closing an exec session cancels the remote command; `kill()` explicitly signals its process group.
+
+Python does not close a custom iterator on `break`. Use a context manager around command, watch, log, and terminal streams whenever iteration can end early. A stream is single-consumer; concurrent reads are rejected. No background reconnect or replay is performed.
+
+## Files
+
+```python
+workspace.files.write_bytes("/workspace/data.bin", b"\x00\xff")
+text = workspace.files.read_text("/workspace/hello.txt")
+workspace.files.upload("./local.zip", "/workspace/input.zip")
+workspace.files.download("/workspace/output.zip", "./output.zip")
+workspace.files.mkdir("/workspace/results", parents=True)
+workspace.files.remove("/workspace/results", recursive=True)
+```
+
+`read_bytes`/`read_text` default to a 16 MiB limit and fail rather than silently truncate. Text decoding defaults to strict UTF-8; configure `encoding`/`errors` if needed. `upload` and `download` use bounded chunks; they do not buffer entire files. Downloads atomically replace the destination only on success, using a private file (mode `0600` on POSIX). Existing local files survive failed downloads. Remote writes truncate their destination and may leave partial data on failure. Parent directories must exist unless explicitly created with `mkdir()`.
+
+Paths are quoted literally, including spaces and shell metacharacters; `~` and `$HOME` are not expanded. Helpers require standard POSIX `sh`, `head`, `cat`, `base64`, `mkdir`, and `rm` in the workspace. `root=True` is available on each operation. File upload detects size changes during transfer; callers should avoid editing a source during upload.
+
+## Persistent terminals, logs, and events
+
+```python
+terminal = workspace.terminals.create(cols=120, rows=40)
+try:
+    with terminal:
+        terminal.write("echo hello\n")
+        with terminal.events as events:
+            for event in events:
+                if event.type == "output":
+                    print(event.data)
+                    break
+finally:
+    terminal.remove()
+```
+
+A terminal persists after detachment and may have multiple listeners. `close()`/`aclose()` and context exit detach locally; **only `remove()` terminates its shell**. Use `workspace.terminals.list()` and `.attach(id)` to reconnect. Output subscriptions begin lazily; creating a handle alone is not a guarantee that a listener has reached the server. Events distinguish binary output, resize, and close. `resize(cols, rows)` changes the PTY dimensions.
+
+`workspace.logs()` streams typed initialization-stage records. `client.workspaces.watch()` observes the caller's workspaces; `workspace.watch()` restricts the subscription. They return generated messages, preserving timestamps, oneofs, and both old/new resources for updates. Watch supplies future events, not an initial list or a durable event log.
+
+## Resource collections
+
+| Collection | Operations |
+| --- | --- |
+| `workspaces` | create/run/get/list/all/update/delete/watch |
+| `spaces` | create/get/list/all/update/modify/delete/leave |
+| `templates` | create/get/list/all/update/modify/delete/build/cancel_build/wait_for_build |
+| `snapshots` | create/get/list/all/delete/wait_until_ready |
+| `volumes` | create/get/list/all/update/modify/delete/grow/wait_until_ready |
+| `secrets` | create/get/list/all/delete |
+| `user_secrets` | create/create_ssh_key/get/list/all/update/modify/set/delete |
+| `git_providers` | create/create_oauth/create_oauth2/get/list/all/update/modify/delete |
+| `memberships` | add/mine/get/list/all/update/modify/set_role/delete |
+| `regions` | list/all |
+| `user_config` | get/update/modify/set_preferred_region/set_dotfiles |
+| `management` | get_cluster_config/update_cluster_config/modify_cluster_config |
+
+Resource collections return documented generated protobuf messages. List methods return `Page` with `items`, `page`, `page_size`, `total_count`, and `has_more`. Pages start at zero. `page_size=0` uses the server default; `.all()` defaults to 100 and fetches lazily. Its timeout applies per page. Use the supported `space=`, `workspace=`, or `template=` filters; mutually exclusive filters are rejected. Server permissions always apply.
+
+```python
+with client.templates.all(space="team.cordium") as templates:
+    for template in templates:
+        print(template.metadata.name)
+
+client.templates.create(
+    "python.team.cordium", image="python:3.13",
+    tasks=[Task(name="prepare", command="python -m pip install requests")],
+)
+started = client.templates.build("python.team.cordium", tags=("release",))
+build_id = started.status.build_info.current_running_build_id
+client.templates.wait_for_build("python.team.cordium", build_id)
+```
+
+Build waits use an explicit build ID so a previous success cannot satisfy a new build's wait. Snapshot creation is asynchronous; wait until ready before restoring via `workspaces.run(snapshot="...")`. Snapshots of running workspaces are crash-consistent; coordinate application writes for application-level consistency. Volume size is megabytes. `grow()` rejects shrinking below requested or observed capacity; expansion support depends on the backend. Some volumes become ready only after first attachment.
+
+Secrets accept text, bytes, or JSON attributes. Structured numbers must be finite; integers outside ±2**53 are rejected. Secret values are write-only. `user_secrets.create_ssh_key()` asks the Cluster to generate a key pair; it does not upload a private key. OAuth Git providers reference a Space Secret **name** for `client_secret`.
+
+For updates, fetch the resource, edit its spec, then pass it to `update()`, preserving metadata/version. `modify(ref, callback)` performs this sequence under one deadline and writes only if the synchronous callback succeeds. It does not retry conflicts or repeat callbacks. In the blocking client callbacks execute on the SDK's loop thread and must not call blocking methods on that same client. `workspace.modify(callback)` also refreshes the handle.
+
+## Authentication, HTTP, errors, and deadlines
+
+Explicit credentials override the environment:
+
+```python
+from cordium import AccessToken, Assertion, AssertionFile, AuthenticationToken, Cordium
+
+client = Cordium("example.com", auth=AuthenticationToken("one-time-token"))
+# Other options:
+# AccessToken("externally-managed-token")
+# AccessToken(callable_returning_current_token)  # sync or async callable
+# Assertion(callable_returning_assertion, scopes=("scope",))
+# AssertionFile("/var/run/secrets/workload/token")
+```
+
+Close the client when finished. Authentication tokens are attempted once, then the returned session is refreshed. Assertion files are reread for reauthentication. Concurrent callers share one session refresh; cancellation of one caller does not cancel authentication needed by other callers. Refresh has a 30-second internal deadline. Access-token providers run on each request and may be async; synchronous providers should avoid blocking I/O. Do not log tokens or returned `access_token()` values.
+
+Environment precedence: `OCTELIUM_ACCESS_TOKEN`, `OCTELIUM_ASSERTION_FILE`, `OCTELIUM_ASSERTION`, then `OCTELIUM_AUTH_TOKEN` (or `OCTELIUM_AUTHENTICATION_TOKEN`). Domain precedence is explicit argument, `CORDIUM_DOMAIN`, then `OCTELIUM_DOMAIN`.
+
+```python
+response = client.request("GET", workspace.app_url("api") + "/health")
+response.raise_for_status()
+print(response.json())
+```
+
+`request()` attaches the current token only to HTTPS Cluster-domain/subdomain destinations or `authorized_http_hosts`. It supports underscore application routes. Redirects are returned without following. Userinfo and unauthorized destinations are rejected before authentication/network I/O. HTTP non-success statuses are returned for caller handling. Responses are buffered up to `max_response_bytes` (16 MiB default); deadlines include authentication and full-body reads. `allow_insecure_http=True` and `tls=False` explicitly enable insecure local testing. `host=`, `port=`, and an `ssl.SSLContext` support custom deployments.
+
+Timeouts are positive finite **seconds**, with `None` disabling the deadline. Unary operations default to 30 seconds, readiness/run waits to 300 seconds, and exec/event streams to no deadline. Composite operations use one total budget. Local disk completion may delay cancellation until an in-flight write finishes safely. No automatic retries are performed for resource operations or executions; this avoids duplicate side effects. Errors preserve gRPC status names in `CordiumError.code`; SDK codes include `CLIENT_CLOSED`, `PROTOCOL_ERROR`, `WORKSPACE_STOPPED`, `WORKSPACE_FAILED`, `BUILD_FAILED`, `SNAPSHOT_FAILED`, `VOLUME_FAILED`, and `COMMAND_FAILED`. Async caller cancellation remains `asyncio.CancelledError`.
+
+## Generated API escape hatch
+
+```python
+from cordium import meta, proto
+
+# Native async client, inside its owning event loop:
+resource = await async_client.raw.main.get_workspace(
+    meta.GetOptions(name="abc"), timeout=10,
+)
+
+# Blocking client: callbacks run on its owned loop.
+resource = client.call(
+    lambda c: c.raw.main.get_workspace(meta.GetOptions(name="abc"), timeout=10)
+)
+```
+
+`raw.main`, `raw.workspace`, and `raw.management` expose the generated stubs. Raw calls preserve native `grpclib` errors; callers own their deadlines and streaming cleanup. They share authentication with high-level methods. The async constructor accepts an already-authenticated `grpclib.Channel` or an `httpx.AsyncClient`; injected transports remain caller-owned. Token/HTTP helpers require SDK-managed credentials and cannot extract credentials from an injected gRPC channel.
+
+See the [API reference](docs/api.md), [runnable examples](examples), and [development notes](docs/development.md). Every public method has a docstring available through `help()` and editor tooltips. Both packages carry PEP 561 typing markers.