flo-python 0.1.2__tar.gz → 0.1.3__tar.gz

{flo_python-0.1.2 → flo_python-0.1.3}/.github/flo-ref.env

@@ -1,4 +1,4 @@
 # The flo commit the live tests run against: CI checks floruntime/flo out at
 # this commit, builds it and starts it. Bump it in the same commit as
 # TABLE_HASH, so the SDK and the server agree.
-FLO_REF=b02486074eb42eadb777133ee585e2a01cd4dfc9
+FLO_REF=51735a8132c7826b175e53a9b690d120dd9cf52d

{flo_python-0.1.2 → flo_python-0.1.3}/.github/workflows/ci.yml

@@ -52,10 +52,16 @@ jobs:
       - name: Build flo
         working-directory: flo-src
         run: zig build --release=safe -Dcpu=x86_64_v2
+      # The server's status codes and refusal reasons, for the drift test.
+      - name: Write ops.json
+        working-directory: flo-src
+        run: zig build gen
       - uses: actions/upload-artifact@v4
         with:
           name: flo
-          path: flo-src/zig-out/bin/flo
+          path: |
+            flo-src/zig-out/bin/flo
+            flo-src/zig-out/gen/ops.json
           retention-days: 1
 
   test:
@@ -81,14 +87,15 @@ jobs:
       - name: Start the pinned flo
         run: |
           cd "$RUNNER_TEMP"
-          chmod +x flo-bin/flo
-          echo "FLO_BINARY=$RUNNER_TEMP/flo-bin/flo" >> "$GITHUB_ENV"
+          chmod +x flo-bin/bin/flo
+          echo "FLO_BINARY=$RUNNER_TEMP/flo-bin/bin/flo" >> "$GITHUB_ENV"
+          echo "FLO_OPS_JSON=$RUNNER_TEMP/flo-bin/gen/ops.json" >> "$GITHUB_ENV"
           mkdir -p flo-data flo-expiry-data
-          ./flo-bin/flo server start --port 4453 --data-dir "$RUNNER_TEMP/flo-data" > flo-server.log 2>&1 &
+          ./flo-bin/bin/flo server start --port 4453 --data-dir "$RUNNER_TEMP/flo-data" > flo-server.log 2>&1 &
           # A second server that removes a worker a second after its last
           # heartbeat, for the re-register test.
           printf '[workers]\nheartbeat_timeout_ms = 1000\nremove_after_ms = 1000\n' > flo-fast-expiry.toml
-          ./flo-bin/flo server start --port 4463 --data-dir "$RUNNER_TEMP/flo-expiry-data" \
+          ./flo-bin/bin/flo server start --port 4463 --data-dir "$RUNNER_TEMP/flo-expiry-data" \
             --config "$RUNNER_TEMP/flo-fast-expiry.toml" > flo-expiry-server.log 2>&1 &
           for port in 4453 4463; do
             for _ in $(seq 1 50); do
@@ -99,7 +106,8 @@ jobs:
           done
       - name: Run tests
         # CI=1 turns a missing server into a failure, not a skip; FLO_BINARY
-        # runs the version test against the pinned flo.
+        # runs the version test against the pinned flo, FLO_OPS_JSON the
+        # status and reason drift test.
         env:
           CI: "1"
           FLO_ENDPOINT: localhost:4453

{flo_python-0.1.2 → flo_python-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flo-python
-Version: 0.1.2
+Version: 0.1.3
 Summary: Python SDK for the Flo distributed systems platform
 Project-URL: Homepage, https://github.com/floruntime/flo-python
 Project-URL: Documentation, https://github.com/floruntime/flo-python#readme
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Classifier: Topic :: System :: Distributed Computing
 Requires-Python: >=3.10
+Requires-Dist: google-crc32c>=1.7.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
@@ -131,14 +132,16 @@ await client.kv.delete("lock:resource", DeleteOptions(cas_version=held_version))
 ```python
 from flo import ScanOptions
 
-# Names of keys with a prefix ("" for all), up to 1024 per page by default
-result = await client.kv.scan("user:")
-for name in result.names:
-    print(name)
-
-# Next pages: the cursor is None on the last page (limit is 1..1024)
-while result.cursor is not None:
-    result = await client.kv.scan("user:", ScanOptions(cursor=result.cursor, limit=100))
+# Names of keys with a prefix ("" for all), a page at a time (limit 1..1024,
+# default 1024); the cursor is None on the last page
+opts = ScanOptions(limit=100)
+while True:
+    result = await client.kv.scan("user:", opts)
+    for name in result.names:
+        print(name)
+    if result.cursor is None or not result.names:
+        break
+    opts = ScanOptions(cursor=result.cursor, limit=100)
 ```
 
 ### MGet
@@ -161,13 +164,21 @@ await client.kv.mget(["user:1:name", "user:1:email"], KVMGetOptions(routing_key=
 ```python
 from flo import HistoryOptions
 
-# Versions newest first (limit 1..65, default 10), each with its write time in ms;
-# empty for a missing key
-history = await client.kv.history("user:123", HistoryOptions(limit=10))
-for entry in history:
-    print(f"v{entry.version} at {entry.at_ms}: {entry.value.decode()}")
+# A page of versions newest first (limit 1..65, default 10), each with its write
+# time in ms and whether it was a delete; empty for a missing key. `more` says
+# older kept versions follow: ask again from before the last one.
+opts = HistoryOptions(limit=10)
+while True:
+    page = await client.kv.history("user:123", opts)
+    for entry in page.versions:
+        print(f"v{entry.version} at {entry.at_ms}: {entry.value.decode()}")
+    if not page.more or not page.versions:
+        break
+    opts = HistoryOptions(limit=10, before_version=page.versions[-1].version)
 ```
 
+A key keeps at most 64 older versions, and 64 KiB of them; the oldest go first.
+
 ### Counters, TTL and exists
 
 ```python
@@ -182,8 +193,9 @@ await client.kv.expire("session:abc", 60_000)
 await client.kv.expire("lease", 30_000, KVExpireOptions(cas_version=lease_version))
 await client.kv.expire("session:abc", 0)
 
-if await client.kv.exists("session:abc"):
-    ...
+res = await client.kv.exists("session:abc")
+if res:  # truthy when the key exists; res.exists says the same
+    print(res.version)
 ```
 
 ### JSON documents
@@ -423,6 +435,34 @@ await client.worker.register(
 )
 ```
 
+### Inspect a Worker
+
+```python
+# Its row (as client.worker.list shows it), its metadata and its processes
+info = await client.worker.info("worker-1")
+print(info.worker.status, info.worker.machine_id)
+print(info.metadata)  # bytes as registered, or None; decode it if you know it's text
+for p in info.processes:  # p.kind: ProcessKind.ACTION or STREAM_CONSUMER
+    print(p.name, p.kind.name, p.run_count, p.fail_count, p.last_run_at_ms)
+```
+
+List the namespace's workers a page at a time, optionally only those that run an action:
+
+```python
+from flo import WorkerListOptions
+
+opts = WorkerListOptions(limit=100, action="process-image")
+while True:
+    page = await client.worker.list(opts)
+    for w in page.workers:
+        print(w.worker_id, w.status)
+    if page.cursor is None or not page.workers:
+        break
+    opts = WorkerListOptions(limit=100, action="process-image", cursor=page.cursor)
+```
+
+The server allows at most 1024 processes per worker and refuses a registration past its limits; the refusal comes back as a `BadRequestError` carrying its reason (`OUT_OF_RANGE` for too many processes, `FIELD_TOO_LONG` for a process name, the processes together or a machine id too long) and message.
+
 ### Await and Process Tasks
 
 ```python
@@ -491,7 +531,9 @@ A run whose handler goes past the action's `timeout_ms` without touching it is t
 
 Delivery is at-least-once: a result lost to a dropped connection is resent, and one that never arrives lets the lease run out, so a handler may see the same task or record again. `worker.stop()` waits for running handlers, and their results are still sent.
 
-An action worker heartbeats every 30 s, reporting the handlers it is running. One the server removed after missed heartbeats registers again, with the same options, when its next heartbeat is answered not found. One the server has drained stops taking work, and `start()` returns once its running handlers finish.
+Both workers register in the worker registry and heartbeat every 30 s, reporting the handlers they are running. One the server removed after missed heartbeats registers again, with the same options, when its next heartbeat is answered not found.
+
+`worker.drain()` stops taking work and lets the running handlers finish, heartbeats going on; the server is told, so it assigns the worker nothing more, and `start()` returns once the last handler has reported. A drain started on the server does the same. Neither waits out `block_ms`: `drain()` interrupts the worker's own poll connection, so an action worker's held await and a stream worker's held read end at once. A drain started on the server answers an action worker's held await at once, refused as `WORKER_DRAINING`; it doesn't wake a stream worker's held group read, so a stream worker learns of it from its next heartbeat (every 30 s) and only then interrupts its read and leaves. `worker.stop()` ends polling at once, also mid-reconnect or mid-drain; running handlers still finish, and a stream worker hands back the records of its last batch it hasn't started. Either one before or during `start()` ends that run, and a worker can be started again afterwards.
 
 ### StreamWorker Example
 
@@ -582,11 +624,13 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
 | `UnauthorizedError` | Authentication failed |
 | `OverloadedError` | Server is overloaded, and the client's retries ran out |
 | `UnavailableError` | No leader, or the shard isn't taking writes or is offline, and the client's retries ran out (the message says why, and whether an operator must act first) |
+| `StaleNotFoundError` | `kv.get` or `kv.json_get` found no key, but a halted shard answered: absent only as of the entry it halted at |
+| `OutcomePendingError` | The write committed but hasn't applied: its shard halted at or before it (reason `SHARD_HALTED`, ran `UNKNOWN`; the message says whether it applies when the shard resumes). Never retried |
 | `InternalServerError` | Server internal error; not retryable (may mean committed but not applied) |
 | `GenericServerError` | Any other error status, including one this SDK doesn't know (`status_code` carries it) |
 | `ConnectionFailedError` | Failed to connect |
 | `RequestTimeoutError` | No response within the timeout |
-| `InvalidChecksumError` | Response CRC32 mismatch |
+| `InvalidChecksumError` | Response CRC32C mismatch |
 
 ### Retries
 
@@ -596,6 +640,27 @@ new request, after a jittered wait. Because the server never ran it, this is
 safe for writes too. Any other refusal, or one that may have run, comes
 straight back.
 
+Two refusals from a halted shard are never retried, and come back after one
+attempt for the caller to decide:
+
+- `OutcomePendingError`: the write committed, so resending it would write it
+  twice, or halt the shard again.
+- `UnavailableError` with `error.reason == Reason.SHARD_HALTED`: the shard
+  takes no writes until an operator repairs it. The reason tells it apart from
+  a leader change.
+
+A halted shard still answers reads, from its state just before the entry it
+halted at. Such a read succeeds; its result says so with `stale=True` (on
+`GetResult`, `GetJsonResult`, each `MGetEntry`, `ScanResult`, `HistoryResult`,
+`ExistsResult`, and the raw response). It is not an error. A key absent on
+such an answer is absent only as of the halt, so `kv.get` and `kv.json_get`
+raise `StaleNotFoundError` (a `NotFoundError` with `stale` True) instead of
+returning `None`; `kv.history` returns an empty page with `stale=True`, and
+`kv.exists` and `kv.mget` entries say `stale` too. A refusal from a halted
+shard carries `error.stale` as well. Reads other than KV ones (streams,
+queues, workers and the rest) don't surface the flag yet; they drop it this
+release.
+
 | `RetryPolicy` field | Default | |
 |---|---|---|
 | `max_attempts` | 4 | Tries in all, the first included; 1 turns retrying off |
@@ -613,6 +678,18 @@ between failed polls, from 100 ms up to 5 s, starting again from 100 ms after a
 poll that succeeds; `stop()` cuts the wait short. A stream worker retries a
 group join refused this way instead of stopping.
 
+Workers are the exception to the halted-shard rule: registering, polling and
+joining a group are safe to repeat, so on `SHARD_HALTED` either worker's
+registration at start and poll, and a stream worker's group join, keep
+trying, waiting from 100 ms up to 30 s, logging each refusal at
+warning with the server's message. A worker started during a halt comes up,
+and one running through it resumes, by itself once the shard is repaired; no
+restart is needed. They wait only on a write the shard refused without running it
+(`UNAVAILABLE`, ran `NO`); an `OutcomePendingError` (an action registration or
+group join that committed but hasn't applied) ends `start()` after one try,
+with the server's message, since sending it again could halt the shard again.
+Results and acks the shard refuses are not resent.
+
 ```python
 from flo import FloClient, RetryPolicy
 

{flo_python-0.1.2 → flo_python-0.1.3}/README.md

@@ -101,14 +101,16 @@ await client.kv.delete("lock:resource", DeleteOptions(cas_version=held_version))
 ```python
 from flo import ScanOptions
 
-# Names of keys with a prefix ("" for all), up to 1024 per page by default
-result = await client.kv.scan("user:")
-for name in result.names:
-    print(name)
-
-# Next pages: the cursor is None on the last page (limit is 1..1024)
-while result.cursor is not None:
-    result = await client.kv.scan("user:", ScanOptions(cursor=result.cursor, limit=100))
+# Names of keys with a prefix ("" for all), a page at a time (limit 1..1024,
+# default 1024); the cursor is None on the last page
+opts = ScanOptions(limit=100)
+while True:
+    result = await client.kv.scan("user:", opts)
+    for name in result.names:
+        print(name)
+    if result.cursor is None or not result.names:
+        break
+    opts = ScanOptions(cursor=result.cursor, limit=100)
 ```
 
 ### MGet
@@ -131,13 +133,21 @@ await client.kv.mget(["user:1:name", "user:1:email"], KVMGetOptions(routing_key=
 ```python
 from flo import HistoryOptions
 
-# Versions newest first (limit 1..65, default 10), each with its write time in ms;
-# empty for a missing key
-history = await client.kv.history("user:123", HistoryOptions(limit=10))
-for entry in history:
-    print(f"v{entry.version} at {entry.at_ms}: {entry.value.decode()}")
+# A page of versions newest first (limit 1..65, default 10), each with its write
+# time in ms and whether it was a delete; empty for a missing key. `more` says
+# older kept versions follow: ask again from before the last one.
+opts = HistoryOptions(limit=10)
+while True:
+    page = await client.kv.history("user:123", opts)
+    for entry in page.versions:
+        print(f"v{entry.version} at {entry.at_ms}: {entry.value.decode()}")
+    if not page.more or not page.versions:
+        break
+    opts = HistoryOptions(limit=10, before_version=page.versions[-1].version)
 ```
 
+A key keeps at most 64 older versions, and 64 KiB of them; the oldest go first.
+
 ### Counters, TTL and exists
 
 ```python
@@ -152,8 +162,9 @@ await client.kv.expire("session:abc", 60_000)
 await client.kv.expire("lease", 30_000, KVExpireOptions(cas_version=lease_version))
 await client.kv.expire("session:abc", 0)
 
-if await client.kv.exists("session:abc"):
-    ...
+res = await client.kv.exists("session:abc")
+if res:  # truthy when the key exists; res.exists says the same
+    print(res.version)
 ```
 
 ### JSON documents
@@ -393,6 +404,34 @@ await client.worker.register(
 )
 ```
 
+### Inspect a Worker
+
+```python
+# Its row (as client.worker.list shows it), its metadata and its processes
+info = await client.worker.info("worker-1")
+print(info.worker.status, info.worker.machine_id)
+print(info.metadata)  # bytes as registered, or None; decode it if you know it's text
+for p in info.processes:  # p.kind: ProcessKind.ACTION or STREAM_CONSUMER
+    print(p.name, p.kind.name, p.run_count, p.fail_count, p.last_run_at_ms)
+```
+
+List the namespace's workers a page at a time, optionally only those that run an action:
+
+```python
+from flo import WorkerListOptions
+
+opts = WorkerListOptions(limit=100, action="process-image")
+while True:
+    page = await client.worker.list(opts)
+    for w in page.workers:
+        print(w.worker_id, w.status)
+    if page.cursor is None or not page.workers:
+        break
+    opts = WorkerListOptions(limit=100, action="process-image", cursor=page.cursor)
+```
+
+The server allows at most 1024 processes per worker and refuses a registration past its limits; the refusal comes back as a `BadRequestError` carrying its reason (`OUT_OF_RANGE` for too many processes, `FIELD_TOO_LONG` for a process name, the processes together or a machine id too long) and message.
+
 ### Await and Process Tasks
 
 ```python
@@ -461,7 +500,9 @@ A run whose handler goes past the action's `timeout_ms` without touching it is t
 
 Delivery is at-least-once: a result lost to a dropped connection is resent, and one that never arrives lets the lease run out, so a handler may see the same task or record again. `worker.stop()` waits for running handlers, and their results are still sent.
 
-An action worker heartbeats every 30 s, reporting the handlers it is running. One the server removed after missed heartbeats registers again, with the same options, when its next heartbeat is answered not found. One the server has drained stops taking work, and `start()` returns once its running handlers finish.
+Both workers register in the worker registry and heartbeat every 30 s, reporting the handlers they are running. One the server removed after missed heartbeats registers again, with the same options, when its next heartbeat is answered not found.
+
+`worker.drain()` stops taking work and lets the running handlers finish, heartbeats going on; the server is told, so it assigns the worker nothing more, and `start()` returns once the last handler has reported. A drain started on the server does the same. Neither waits out `block_ms`: `drain()` interrupts the worker's own poll connection, so an action worker's held await and a stream worker's held read end at once. A drain started on the server answers an action worker's held await at once, refused as `WORKER_DRAINING`; it doesn't wake a stream worker's held group read, so a stream worker learns of it from its next heartbeat (every 30 s) and only then interrupts its read and leaves. `worker.stop()` ends polling at once, also mid-reconnect or mid-drain; running handlers still finish, and a stream worker hands back the records of its last batch it hasn't started. Either one before or during `start()` ends that run, and a worker can be started again afterwards.
 
 ### StreamWorker Example
 
@@ -552,11 +593,13 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
 | `UnauthorizedError` | Authentication failed |
 | `OverloadedError` | Server is overloaded, and the client's retries ran out |
 | `UnavailableError` | No leader, or the shard isn't taking writes or is offline, and the client's retries ran out (the message says why, and whether an operator must act first) |
+| `StaleNotFoundError` | `kv.get` or `kv.json_get` found no key, but a halted shard answered: absent only as of the entry it halted at |
+| `OutcomePendingError` | The write committed but hasn't applied: its shard halted at or before it (reason `SHARD_HALTED`, ran `UNKNOWN`; the message says whether it applies when the shard resumes). Never retried |
 | `InternalServerError` | Server internal error; not retryable (may mean committed but not applied) |
 | `GenericServerError` | Any other error status, including one this SDK doesn't know (`status_code` carries it) |
 | `ConnectionFailedError` | Failed to connect |
 | `RequestTimeoutError` | No response within the timeout |
-| `InvalidChecksumError` | Response CRC32 mismatch |
+| `InvalidChecksumError` | Response CRC32C mismatch |
 
 ### Retries
 
@@ -566,6 +609,27 @@ new request, after a jittered wait. Because the server never ran it, this is
 safe for writes too. Any other refusal, or one that may have run, comes
 straight back.
 
+Two refusals from a halted shard are never retried, and come back after one
+attempt for the caller to decide:
+
+- `OutcomePendingError`: the write committed, so resending it would write it
+  twice, or halt the shard again.
+- `UnavailableError` with `error.reason == Reason.SHARD_HALTED`: the shard
+  takes no writes until an operator repairs it. The reason tells it apart from
+  a leader change.
+
+A halted shard still answers reads, from its state just before the entry it
+halted at. Such a read succeeds; its result says so with `stale=True` (on
+`GetResult`, `GetJsonResult`, each `MGetEntry`, `ScanResult`, `HistoryResult`,
+`ExistsResult`, and the raw response). It is not an error. A key absent on
+such an answer is absent only as of the halt, so `kv.get` and `kv.json_get`
+raise `StaleNotFoundError` (a `NotFoundError` with `stale` True) instead of
+returning `None`; `kv.history` returns an empty page with `stale=True`, and
+`kv.exists` and `kv.mget` entries say `stale` too. A refusal from a halted
+shard carries `error.stale` as well. Reads other than KV ones (streams,
+queues, workers and the rest) don't surface the flag yet; they drop it this
+release.
+
 | `RetryPolicy` field | Default | |
 |---|---|---|
 | `max_attempts` | 4 | Tries in all, the first included; 1 turns retrying off |
@@ -583,6 +647,18 @@ between failed polls, from 100 ms up to 5 s, starting again from 100 ms after a
 poll that succeeds; `stop()` cuts the wait short. A stream worker retries a
 group join refused this way instead of stopping.
 
+Workers are the exception to the halted-shard rule: registering, polling and
+joining a group are safe to repeat, so on `SHARD_HALTED` either worker's
+registration at start and poll, and a stream worker's group join, keep
+trying, waiting from 100 ms up to 30 s, logging each refusal at
+warning with the server's message. A worker started during a halt comes up,
+and one running through it resumes, by itself once the shard is repaired; no
+restart is needed. They wait only on a write the shard refused without running it
+(`UNAVAILABLE`, ran `NO`); an `OutcomePendingError` (an action registration or
+group join that committed but hasn't applied) ends `start()` after one try,
+with the server's message, since sending it again could halt the shard again.
+Results and acks the shard refuses are not resent.
+
 ```python
 from flo import FloClient, RetryPolicy
 

{flo_python-0.1.2 → flo_python-0.1.3}/pyproject.toml

@@ -4,12 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flo-python"
-version = "0.1.2"
+version = "0.1.3"
 description = "Python SDK for the Flo distributed systems platform"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
+# Frame checksums: a C CRC32C, with its own pure-Python fallback where no
+# wheel fits.
+dependencies = ["google-crc32c>=1.7.0"]
 authors = [
     { name = "Flo Team" }
 ]

{flo_python-0.1.2 → flo_python-0.1.3}/src/flo/__init__.py

@@ -49,12 +49,14 @@ from .exceptions import (
     NonRetryableError,
     NotConnectedError,
     NotFoundError,
+    OutcomePendingError,
     OverloadedError,
     PayloadTooLargeError,
     ProtocolError,
     RateLimitedError,
     RequestTimeoutError,
     ServerError,
+    StaleNotFoundError,
     TableMismatchError,
     UnauthorizedError,
     UnavailableError,
@@ -85,10 +87,12 @@ from .types import (
     DlqListOptions,
     DlqRequeueOptions,
     EnqueueOptions,
+    ExistsResult,
     GetJsonResult,
     GetOptions,
     GetResult,
     HistoryOptions,
+    HistoryResult,
     IncrResult,
     KVBeginResult,
     KVCommitResult,
@@ -113,6 +117,7 @@ from .types import (
     ProcessingSubmitOptions,
     ProcessingSyncOptions,
     ProcessingSyncResult,
+    ProcessKind,
     PutOptions,
     PutResult,
     Ran,
@@ -143,10 +148,12 @@ from .types import (
     WorkerAwaitOptions,
     WorkerAwaitResult,
     WorkerCompleteOptions,
+    WorkerDetails,
     WorkerFailOptions,
     WorkerInfo,
     WorkerListOptions,
     WorkerListResult,
+    WorkerProcess,
     WorkerRegisterOptions,
     WorkerStatus,
     WorkerTouchOptions,
@@ -177,7 +184,7 @@ from .worker import (
 )
 from .workflows import WorkflowOperations
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
     "Transaction",
@@ -191,6 +198,8 @@ __all__ = [
     "KVMGetOptions",
     "KVExpireOptions",
     "GetResult",
+    "HistoryResult",
+    "ExistsResult",
     "GetJsonResult",
     "MGetEntry",
     "PutResult",
@@ -235,6 +244,8 @@ __all__ = [
     "ConflictError",
     "UnauthorizedError",
     "OverloadedError",
+    "OutcomePendingError",
+    "StaleNotFoundError",
     "UnavailableError",
     "RateLimitedError",
     "InternalServerError",
@@ -301,7 +312,10 @@ __all__ = [
     # Worker types
     "TaskAssignment",
     "WorkerAwaitResult",
+    "ProcessKind",
+    "WorkerDetails",
     "WorkerInfo",
+    "WorkerProcess",
     "WorkerListResult",
     "WorkerStatus",
     "WorkerType",

{flo_python-0.1.2 → flo_python-0.1.3}/src/flo/actions.py

@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING
 from .kv_body import (
     decode_action_invoke_answer,
     decode_action_status_answer,
+    decode_worker_info_answer,
     decode_worker_list_answer,
     encode_worker_list_body,
 )
@@ -30,10 +31,12 @@ from .types import (
     WorkerAwaitOptions,
     WorkerAwaitResult,
     WorkerCompleteOptions,
+    WorkerDetails,
     WorkerFailOptions,
     WorkerListOptions,
     WorkerListResult,
     WorkerRegisterOptions,
+    WorkerStatus,
     WorkerTouchOptions,
 )
 from .wire import (
@@ -229,6 +232,7 @@ class WorkerOperations:
 
         value = serialize_worker_register_value(
             task_types,
+            worker_type=int(opts.worker_type),
             max_concurrency=opts.concurrency,
             metadata=opts.metadata,
             machine_id=opts.machine_id,
@@ -246,24 +250,57 @@ class WorkerOperations:
         worker_id: str,
         current_load: int = 0,
         namespace: str | None = None,
-    ) -> None:
+    ) -> WorkerStatus:
         """Send a worker heartbeat to keep the registration alive.
 
         Args:
             worker_id: Worker identifier.
             current_load: Current number of active tasks.
             namespace: Optional namespace override.
+
+        Returns:
+            The worker's status on the server: DRAINING once it is drained.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker (it never
+                registered, or was removed after going silent).
         """
         import struct
 
         ns = self._client.get_namespace(namespace)
         value = struct.pack("<I", current_load)
-        await self._client._send_and_check(
+        response = await self._client._send_and_check(
             OpCode.WORKER_HEARTBEAT,
             ns,
             worker_id.encode("utf-8"),
             value,
         )
+        if len(response.data) != 1:
+            raise ValueError(f"heartbeat answer is {len(response.data)} bytes, want 1")
+        return WorkerStatus(response.data[0])
+
+    async def drain(self, worker_id: str, namespace: str | None = None) -> None:
+        """Mark a worker draining: the server gives it no more work, and
+        its heartbeats answer DRAINING until it deregisters.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker.
+        """
+        await self._client._send_and_check(
+            OpCode.WORKER_DRAIN,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
+
+    async def deregister(self, worker_id: str, namespace: str | None = None) -> None:
+        """Remove a worker from the registry."""
+        await self._client._send_and_check(
+            OpCode.WORKER_DEREGISTER,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
 
     async def await_task(
         self,
@@ -412,8 +449,23 @@ class WorkerOperations:
             OpCode.WORKER_LIST,
             namespace,
             b"",
-            encode_worker_list_body(opts.limit, opts.cursor),
+            encode_worker_list_body(opts.limit, opts.cursor, opts.action),
         )
 
         workers, cursor = decode_worker_list_answer(response.data)
         return WorkerListResult(workers=workers, cursor=cursor)
+
+    async def info(self, worker_id: str, namespace: str | None = None) -> WorkerDetails:
+        """A worker's record: its row, as :meth:`list` shows it, the metadata
+        it registered with, and its processes with their run and fail counts.
+
+        Raises:
+            NotFoundError: The server doesn't know the worker.
+        """
+        response = await self._client._send_and_check(
+            OpCode.WORKER_INFO,
+            self._client.get_namespace(namespace),
+            worker_id.encode("utf-8"),
+            b"",
+        )
+        return decode_worker_info_answer(response.data)