flo-python 0.1.6__tar.gz → 0.1.7__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.
- {flo_python-0.1.6 → flo_python-0.1.7}/.github/flo-ref.env +1 -1
- {flo_python-0.1.6 → flo_python-0.1.7}/CHANGELOG.md +59 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/PKG-INFO +90 -7
- {flo_python-0.1.6 → flo_python-0.1.7}/README.md +89 -6
- {flo_python-0.1.6 → flo_python-0.1.7}/pyproject.toml +1 -1
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/__init__.py +31 -1
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv_body.py +264 -1
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/queue.py +67 -72
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/retry.py +13 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/streams.py +186 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/types.py +209 -24
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/wire.py +7 -3
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/worker.py +35 -5
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_action_ops.py +0 -57
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_action_status.py +12 -3
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_actions_live.py +1 -1
- flo_python-0.1.7/tests/test_dead_letters.py +361 -0
- flo_python-0.1.7/tests/test_dead_letters_live.py +307 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ops_drift.py +23 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_result_resend.py +95 -2
- flo_python-0.1.7/tests/test_stream_settings.py +73 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_trim.py +4 -2
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_wire.py +1 -1
- {flo_python-0.1.6 → flo_python-0.1.7}/.github/workflows/ci.yml +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/.github/workflows/release.yml +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/.gitignore +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/LICENSE +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/examples/basic.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/examples/stream_worker.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/examples/test_decorator.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/examples/worker.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/actions.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/client.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/exceptions.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv_txn.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/processing.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/ts.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/workflows.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/__init__.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/conftest.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/order-workflow.yaml +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_auto_touch.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_block_ms.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_blocking_deadline.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_empty_poll_backoff.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_group_ops.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_groups_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_halts.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_ops.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_table.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_ttl.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_list_paging.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_list_paging_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_missing_answers_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_not_found_answers.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_op_codes.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_poll_loops.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_processing_decode.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_processing_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_protocol_version.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_queue_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_queue_ops.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_read_not_found_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_reconnect_cancel.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_retry.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_status_codes.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_delete.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_delete_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_tier.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_worker_ack.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ts_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ts_ops.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_close.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_close_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_drain.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_info.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_info_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_list.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_liveness.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflow_list_runs.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflow_runs_live.py +0 -0
- {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflows.py +0 -0
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
# The flo commit the live tests run against: CI checks floruntime/flo out at
|
|
2
2
|
# this commit, builds it and starts it. Bump it in the same commit as
|
|
3
3
|
# TABLE_HASH, so the SDK and the server agree.
|
|
4
|
-
FLO_REF=
|
|
4
|
+
FLO_REF=1fd555dcec49985f3bb533ca0a6fb4b95e749341
|
|
@@ -5,6 +5,65 @@ All notable changes to the Flo Python SDK will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.1.7] - 2026-11-18
|
|
9
|
+
|
|
10
|
+
Works with flo v0.1.0-dev.19.
|
|
11
|
+
|
|
12
|
+
The server's op table hash is now `0xac07f1f7338c66bd` (`TABLE_HASH`).
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- `stream.group_steal(stream, group, consumer, records, min_idle_ms)`: take
|
|
17
|
+
records another consumer holds and has left idle that long, each with a new
|
|
18
|
+
delivery and lease, its failures kept. It answers a `GroupStealResult`, a
|
|
19
|
+
delivery acked, nacked or touched as a read's, with `refused` for the
|
|
20
|
+
records it didn't take (`NOT_IDLE` for one its holder touched within the
|
|
21
|
+
idle time)
|
|
22
|
+
- A consumer group's dead letters: `stream.group_dlq_list` (a page, oldest
|
|
23
|
+
dead first, with each one's deliveries, failures, `dead_at_ms` and last
|
|
24
|
+
error; page by the opaque `cursor`), `group_dlq_requeue` (ready again,
|
|
25
|
+
failures reset) and `group_dlq_delete` (with `dry_run`). Requeue and delete
|
|
26
|
+
name up to 100 records by id, or take the oldest with `all`, a batch of up to
|
|
27
|
+
`limit`; they answer `applied`, `refused` (with why and the server's words)
|
|
28
|
+
and `more`
|
|
29
|
+
- `queue.dlq_requeue` and `queue.dlq_delete` (with `dry_run`), by seq or
|
|
30
|
+
`all`, answering a `DlqResult` as the group's do
|
|
31
|
+
- `QueueRefusalReason.NOT_DEAD` (6) and `NOT_IDLE` (7): a requeue or delete
|
|
32
|
+
of one that isn't dead, and a steal of one that isn't idle.
|
|
33
|
+
`GroupRefusal.reason` carries the server's words where it gives them
|
|
34
|
+
- `ActionRunStatus.held`: why a run's lease, past due, isn't ended yet (its
|
|
35
|
+
end waits for room on the calling workflow's shard)
|
|
36
|
+
- `stream.create` (partitions, retention by age and count) and `stream.alter`
|
|
37
|
+
(retention); `StreamInfo.retention_age_s` and `retention_count`
|
|
38
|
+
|
|
39
|
+
### Changed
|
|
40
|
+
|
|
41
|
+
- A worker's complete, fail, ack or nack refused overloaded without being
|
|
42
|
+
run (after the client's own retries) is sent again with a capped backoff
|
|
43
|
+
until the server takes it or answers otherwise, and logged; it used to be
|
|
44
|
+
dropped. A complete or fail that ends a run a workflow step called is
|
|
45
|
+
refused so while the server's writes to the workflow's shard are queued
|
|
46
|
+
full, and the run's lease doesn't run out meanwhile; an ack's or nack's
|
|
47
|
+
lease keeps running, so a long overload can deliver the records again. A
|
|
48
|
+
stopping worker gives up after a couple of seconds, a backoff wait
|
|
49
|
+
included
|
|
50
|
+
- An alter of a stream an append made succeeds; it used to be not found.
|
|
51
|
+
After an alter a create must name the stream's settings as altered, or it
|
|
52
|
+
raises `ConflictError`; a create whose name hashes as another stream's does
|
|
53
|
+
too
|
|
54
|
+
- A workflow step whose action isn't registered waits for one, up to the
|
|
55
|
+
server's missing-action wait, instead of failing at once
|
|
56
|
+
|
|
57
|
+
### Breaking
|
|
58
|
+
|
|
59
|
+
- `queue.dlq_list` sends the new op: `DlqPage` is `messages` and `cursor`
|
|
60
|
+
(a `DlqCursor`, `None` on the last page), replacing `total`, `has_more` and
|
|
61
|
+
`last_seq`; `DlqListOptions.after` takes the cursor, and `limit` defaults
|
|
62
|
+
to 20. `DeadLetter` gains `failures`, `dead_at_ms` and `error`, and loses
|
|
63
|
+
`moved_at_ms`. A queue that doesn't exist raises `NotFoundError`
|
|
64
|
+
- The old dead letter op codes (0x176..0x178) are gone; `OpCode.QUEUE_DLQ_*`
|
|
65
|
+
are the server's 0x185..0x187
|
|
66
|
+
|
|
8
67
|
## [0.1.6] - 2026-11-16
|
|
9
68
|
|
|
10
69
|
The op table hash moves with the server in this release: this SDK talks only
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: flo-python
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.7
|
|
4
4
|
Summary: Python SDK for the Flo distributed systems platform
|
|
5
5
|
Project-URL: Homepage, https://github.com/floruntime/flo-python
|
|
6
6
|
Project-URL: Documentation, https://github.com/floruntime/flo-python#readme
|
|
@@ -306,15 +306,32 @@ result = await client.queue.dequeue("tasks", 10, DequeueOptions(ack=True))
|
|
|
306
306
|
`queue.purge` removes every message of a queue, ready, leased and dead, and
|
|
307
307
|
returns how many.
|
|
308
308
|
|
|
309
|
-
`queue.dlq_list` reads a page of dead letters, oldest first (`limit`
|
|
309
|
+
`queue.dlq_list` reads a page of dead letters, oldest dead first (`limit`
|
|
310
|
+
1..100, default 20), each with up to 4 KiB of its payload (`size` is its
|
|
311
|
+
length), its deliveries and failures, when it died and its last error. Page
|
|
312
|
+
with the answer's opaque `cursor` until it is `None`.
|
|
313
|
+
|
|
314
|
+
`queue.dlq_requeue` makes dead letters ready again at once, failures reset;
|
|
315
|
+
`queue.dlq_delete` deletes them for good (`dry_run` says how many it would).
|
|
316
|
+
Each names up to 100 by seq, or takes the oldest dead with `all`, a batch of
|
|
317
|
+
up to `limit`: `more` says others remain. One that isn't dead comes back in
|
|
318
|
+
`refused` as `NOT_DEAD`, one not there as `GONE`; the call itself succeeds.
|
|
319
|
+
A queue that doesn't exist raises `NotFoundError`.
|
|
310
320
|
|
|
311
321
|
```python
|
|
312
|
-
from flo import DlqListOptions
|
|
322
|
+
from flo import DlqDeleteOptions, DlqListOptions, DlqRequeueOptions
|
|
313
323
|
|
|
314
324
|
page = await client.queue.dlq_list("tasks", DlqListOptions(limit=100))
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
325
|
+
while True:
|
|
326
|
+
for msg in page.messages:
|
|
327
|
+
print(msg.seq, msg.failures, msg.error)
|
|
328
|
+
if page.cursor is None:
|
|
329
|
+
break
|
|
330
|
+
page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.cursor))
|
|
331
|
+
|
|
332
|
+
await client.queue.dlq_requeue("tasks", [msg.seq])
|
|
333
|
+
while (await client.queue.dlq_delete("tasks", options=DlqDeleteOptions(all=True))).more:
|
|
334
|
+
pass
|
|
318
335
|
```
|
|
319
336
|
|
|
320
337
|
### Peek
|
|
@@ -401,7 +418,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
|
|
|
401
418
|
`OverloadedError`, reason `GROUP_HELD_FULL`; the message says which cap).
|
|
402
419
|
Reading again won't help until room is made, so the client doesn't retry it.
|
|
403
420
|
At the group's cap, acks and nacks make room, but dead records count too and
|
|
404
|
-
stay until the group is deleted or a trim of
|
|
421
|
+
stay until they are requeued or deleted, the group is deleted, or a trim of
|
|
422
|
+
the stream cuts them. At the
|
|
405
423
|
shard's cap, this group's own acks free room, as do other groups and queues on
|
|
406
424
|
the shard draining.
|
|
407
425
|
|
|
@@ -463,6 +481,60 @@ members = await client.stream.group_members("events", "processors") # consumers
|
|
|
463
481
|
await client.stream.group_delete("events", "processors")
|
|
464
482
|
```
|
|
465
483
|
|
|
484
|
+
A group's dead letters list a page at a time, oldest dead first, each with its
|
|
485
|
+
deliveries, failures, when it died and its last error; requeue and delete
|
|
486
|
+
take them by id or `all`, as a queue's do (`NOT_DEAD` for one that isn't).
|
|
487
|
+
|
|
488
|
+
```python
|
|
489
|
+
from flo import GroupDlqDeleteOptions, GroupDlqListOptions
|
|
490
|
+
|
|
491
|
+
page = await client.stream.group_dlq_list("events", "processors", GroupDlqListOptions(limit=50))
|
|
492
|
+
await client.stream.group_dlq_requeue("events", "processors", [d.id for d in page.dead])
|
|
493
|
+
await client.stream.group_dlq_delete(
|
|
494
|
+
"events", "processors", options=GroupDlqDeleteOptions(all=True, dry_run=True)
|
|
495
|
+
)
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
`group_steal` is an operator's command: it takes records another consumer
|
|
499
|
+
holds and has left idle for at least `min_idle_ms` (idle is the time since
|
|
500
|
+
its holder last read, stole or touched it), each with a new delivery and
|
|
501
|
+
lease, its failures kept. Name each record with the deliveries its holder has
|
|
502
|
+
(a read's records, or `group_pending`'s entries). The result is a delivery,
|
|
503
|
+
acked, nacked or touched as a read's; records it didn't take come back in
|
|
504
|
+
`refused` (`NOT_IDLE` for one touched within the idle time). A read takes
|
|
505
|
+
expired records by itself, so a steal is for records whose holder is stuck
|
|
506
|
+
but still touching them, or to move work sooner than the lease.
|
|
507
|
+
|
|
508
|
+
```python
|
|
509
|
+
pending = await client.stream.group_pending("events", "processors", "worker-1")
|
|
510
|
+
stolen = await client.stream.group_steal("events", "processors", "worker-2", pending, 60_000)
|
|
511
|
+
await client.stream.group_ack("events", "processors", stolen)
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
### Stream Settings
|
|
515
|
+
|
|
516
|
+
An append creates a stream with no settings. `create` gives one its
|
|
517
|
+
partitions and retention (records older than `retention_age_s`, or past
|
|
518
|
+
`retention_count`, are trimmed); `alter` changes its retention, each setting
|
|
519
|
+
given replacing the stream's, on a stream an append made as on one a create
|
|
520
|
+
made. `info` answers the settings.
|
|
521
|
+
|
|
522
|
+
Once a stream has settings, from a create or an alter, a create that names
|
|
523
|
+
the same ones succeeds (a retry), and one that names others raises
|
|
524
|
+
`ConflictError` ("the stream exists with other settings"): after an alter, a
|
|
525
|
+
create must name the settings as altered. A create of a stream an append made
|
|
526
|
+
and nothing altered gives it the settings named. A create whose name hashes
|
|
527
|
+
as another stream's raises `ConflictError` too; choose another name.
|
|
528
|
+
|
|
529
|
+
```python
|
|
530
|
+
from flo import StreamAlterOptions, StreamCreateOptions
|
|
531
|
+
|
|
532
|
+
await client.stream.create("events", StreamCreateOptions(retention_age_s=86_400))
|
|
533
|
+
await client.stream.alter("events", StreamAlterOptions(retention_count=1_000_000))
|
|
534
|
+
info = await client.stream.info("events")
|
|
535
|
+
print(info.retention_age_s, info.retention_count)
|
|
536
|
+
```
|
|
537
|
+
|
|
466
538
|
## Time-Series Operations
|
|
467
539
|
|
|
468
540
|
Every time and window is Unix nanoseconds, a Python `int`. A point's
|
|
@@ -638,6 +710,8 @@ if status.error_message is not None:
|
|
|
638
710
|
print(f"Error: {status.error_message}")
|
|
639
711
|
if status.outcome is not None: # None for success
|
|
640
712
|
print(f"Outcome: {status.outcome}")
|
|
713
|
+
if status.held is not None: # why a past-due lease isn't ended yet
|
|
714
|
+
print(f"Held: {status.held}")
|
|
641
715
|
|
|
642
716
|
# An action's definition, its runs by status and its completed runs' latency
|
|
643
717
|
info = await client.action.info("process-image")
|
|
@@ -814,6 +888,15 @@ async def run_stream_worker():
|
|
|
814
888
|
asyncio.run(run_stream_worker())
|
|
815
889
|
```
|
|
816
890
|
|
|
891
|
+
A worker's complete, fail, ack or nack refused overloaded without being run
|
|
892
|
+
(once the client's own retries are spent) is sent again with a capped backoff
|
|
893
|
+
until the server takes it or answers otherwise, and logged each time. A
|
|
894
|
+
complete or fail that ends a run a workflow step called is refused so while
|
|
895
|
+
the server's queue of writes to the workflow's shard is full; meanwhile the
|
|
896
|
+
run's lease doesn't run out, and `action.status` says why in `held`. An ack's
|
|
897
|
+
or nack's lease keeps running, so a long overload can deliver the records
|
|
898
|
+
again. A stopping worker gives up on it after a couple of seconds.
|
|
899
|
+
|
|
817
900
|
A stream worker acks each record its handler returns from and nacks each one
|
|
818
901
|
its handler raises on, naming the read's delivery. A record whose handler runs
|
|
819
902
|
past the group's lease is read again elsewhere unless `auto_touch=True`, which
|
|
@@ -275,15 +275,32 @@ result = await client.queue.dequeue("tasks", 10, DequeueOptions(ack=True))
|
|
|
275
275
|
`queue.purge` removes every message of a queue, ready, leased and dead, and
|
|
276
276
|
returns how many.
|
|
277
277
|
|
|
278
|
-
`queue.dlq_list` reads a page of dead letters, oldest first (`limit`
|
|
278
|
+
`queue.dlq_list` reads a page of dead letters, oldest dead first (`limit`
|
|
279
|
+
1..100, default 20), each with up to 4 KiB of its payload (`size` is its
|
|
280
|
+
length), its deliveries and failures, when it died and its last error. Page
|
|
281
|
+
with the answer's opaque `cursor` until it is `None`.
|
|
282
|
+
|
|
283
|
+
`queue.dlq_requeue` makes dead letters ready again at once, failures reset;
|
|
284
|
+
`queue.dlq_delete` deletes them for good (`dry_run` says how many it would).
|
|
285
|
+
Each names up to 100 by seq, or takes the oldest dead with `all`, a batch of
|
|
286
|
+
up to `limit`: `more` says others remain. One that isn't dead comes back in
|
|
287
|
+
`refused` as `NOT_DEAD`, one not there as `GONE`; the call itself succeeds.
|
|
288
|
+
A queue that doesn't exist raises `NotFoundError`.
|
|
279
289
|
|
|
280
290
|
```python
|
|
281
|
-
from flo import DlqListOptions
|
|
291
|
+
from flo import DlqDeleteOptions, DlqListOptions, DlqRequeueOptions
|
|
282
292
|
|
|
283
293
|
page = await client.queue.dlq_list("tasks", DlqListOptions(limit=100))
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
294
|
+
while True:
|
|
295
|
+
for msg in page.messages:
|
|
296
|
+
print(msg.seq, msg.failures, msg.error)
|
|
297
|
+
if page.cursor is None:
|
|
298
|
+
break
|
|
299
|
+
page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.cursor))
|
|
300
|
+
|
|
301
|
+
await client.queue.dlq_requeue("tasks", [msg.seq])
|
|
302
|
+
while (await client.queue.dlq_delete("tasks", options=DlqDeleteOptions(all=True))).more:
|
|
303
|
+
pass
|
|
287
304
|
```
|
|
288
305
|
|
|
289
306
|
### Peek
|
|
@@ -370,7 +387,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
|
|
|
370
387
|
`OverloadedError`, reason `GROUP_HELD_FULL`; the message says which cap).
|
|
371
388
|
Reading again won't help until room is made, so the client doesn't retry it.
|
|
372
389
|
At the group's cap, acks and nacks make room, but dead records count too and
|
|
373
|
-
stay until the group is deleted or a trim of
|
|
390
|
+
stay until they are requeued or deleted, the group is deleted, or a trim of
|
|
391
|
+
the stream cuts them. At the
|
|
374
392
|
shard's cap, this group's own acks free room, as do other groups and queues on
|
|
375
393
|
the shard draining.
|
|
376
394
|
|
|
@@ -432,6 +450,60 @@ members = await client.stream.group_members("events", "processors") # consumers
|
|
|
432
450
|
await client.stream.group_delete("events", "processors")
|
|
433
451
|
```
|
|
434
452
|
|
|
453
|
+
A group's dead letters list a page at a time, oldest dead first, each with its
|
|
454
|
+
deliveries, failures, when it died and its last error; requeue and delete
|
|
455
|
+
take them by id or `all`, as a queue's do (`NOT_DEAD` for one that isn't).
|
|
456
|
+
|
|
457
|
+
```python
|
|
458
|
+
from flo import GroupDlqDeleteOptions, GroupDlqListOptions
|
|
459
|
+
|
|
460
|
+
page = await client.stream.group_dlq_list("events", "processors", GroupDlqListOptions(limit=50))
|
|
461
|
+
await client.stream.group_dlq_requeue("events", "processors", [d.id for d in page.dead])
|
|
462
|
+
await client.stream.group_dlq_delete(
|
|
463
|
+
"events", "processors", options=GroupDlqDeleteOptions(all=True, dry_run=True)
|
|
464
|
+
)
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
`group_steal` is an operator's command: it takes records another consumer
|
|
468
|
+
holds and has left idle for at least `min_idle_ms` (idle is the time since
|
|
469
|
+
its holder last read, stole or touched it), each with a new delivery and
|
|
470
|
+
lease, its failures kept. Name each record with the deliveries its holder has
|
|
471
|
+
(a read's records, or `group_pending`'s entries). The result is a delivery,
|
|
472
|
+
acked, nacked or touched as a read's; records it didn't take come back in
|
|
473
|
+
`refused` (`NOT_IDLE` for one touched within the idle time). A read takes
|
|
474
|
+
expired records by itself, so a steal is for records whose holder is stuck
|
|
475
|
+
but still touching them, or to move work sooner than the lease.
|
|
476
|
+
|
|
477
|
+
```python
|
|
478
|
+
pending = await client.stream.group_pending("events", "processors", "worker-1")
|
|
479
|
+
stolen = await client.stream.group_steal("events", "processors", "worker-2", pending, 60_000)
|
|
480
|
+
await client.stream.group_ack("events", "processors", stolen)
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
### Stream Settings
|
|
484
|
+
|
|
485
|
+
An append creates a stream with no settings. `create` gives one its
|
|
486
|
+
partitions and retention (records older than `retention_age_s`, or past
|
|
487
|
+
`retention_count`, are trimmed); `alter` changes its retention, each setting
|
|
488
|
+
given replacing the stream's, on a stream an append made as on one a create
|
|
489
|
+
made. `info` answers the settings.
|
|
490
|
+
|
|
491
|
+
Once a stream has settings, from a create or an alter, a create that names
|
|
492
|
+
the same ones succeeds (a retry), and one that names others raises
|
|
493
|
+
`ConflictError` ("the stream exists with other settings"): after an alter, a
|
|
494
|
+
create must name the settings as altered. A create of a stream an append made
|
|
495
|
+
and nothing altered gives it the settings named. A create whose name hashes
|
|
496
|
+
as another stream's raises `ConflictError` too; choose another name.
|
|
497
|
+
|
|
498
|
+
```python
|
|
499
|
+
from flo import StreamAlterOptions, StreamCreateOptions
|
|
500
|
+
|
|
501
|
+
await client.stream.create("events", StreamCreateOptions(retention_age_s=86_400))
|
|
502
|
+
await client.stream.alter("events", StreamAlterOptions(retention_count=1_000_000))
|
|
503
|
+
info = await client.stream.info("events")
|
|
504
|
+
print(info.retention_age_s, info.retention_count)
|
|
505
|
+
```
|
|
506
|
+
|
|
435
507
|
## Time-Series Operations
|
|
436
508
|
|
|
437
509
|
Every time and window is Unix nanoseconds, a Python `int`. A point's
|
|
@@ -607,6 +679,8 @@ if status.error_message is not None:
|
|
|
607
679
|
print(f"Error: {status.error_message}")
|
|
608
680
|
if status.outcome is not None: # None for success
|
|
609
681
|
print(f"Outcome: {status.outcome}")
|
|
682
|
+
if status.held is not None: # why a past-due lease isn't ended yet
|
|
683
|
+
print(f"Held: {status.held}")
|
|
610
684
|
|
|
611
685
|
# An action's definition, its runs by status and its completed runs' latency
|
|
612
686
|
info = await client.action.info("process-image")
|
|
@@ -783,6 +857,15 @@ async def run_stream_worker():
|
|
|
783
857
|
asyncio.run(run_stream_worker())
|
|
784
858
|
```
|
|
785
859
|
|
|
860
|
+
A worker's complete, fail, ack or nack refused overloaded without being run
|
|
861
|
+
(once the client's own retries are spent) is sent again with a capped backoff
|
|
862
|
+
until the server takes it or answers otherwise, and logged each time. A
|
|
863
|
+
complete or fail that ends a run a workflow step called is refused so while
|
|
864
|
+
the server's queue of writes to the workflow's shard is full; meanwhile the
|
|
865
|
+
run's lease doesn't run out, and `action.status` says why in `held`. An ack's
|
|
866
|
+
or nack's lease keeps running, so a long overload can deliver the records
|
|
867
|
+
again. A stopping worker gives up on it after a couple of seconds.
|
|
868
|
+
|
|
786
869
|
A stream worker acks each record its handler returns from and nacks each one
|
|
787
870
|
its handler raises on, naming the read's delivery. A record whose handler runs
|
|
788
871
|
past the group's lease is read again elsewhere unless `auto_touch=True`, which
|
|
@@ -91,8 +91,12 @@ from .types import (
|
|
|
91
91
|
DeleteOptions,
|
|
92
92
|
DequeueOptions,
|
|
93
93
|
DequeueResult,
|
|
94
|
+
DlqCursor,
|
|
95
|
+
DlqDeleteOptions,
|
|
94
96
|
DlqListOptions,
|
|
95
97
|
DlqPage,
|
|
98
|
+
DlqRequeueOptions,
|
|
99
|
+
DlqResult,
|
|
96
100
|
EnqueueOptions,
|
|
97
101
|
ExistsResult,
|
|
98
102
|
FloQLPoint,
|
|
@@ -100,11 +104,19 @@ from .types import (
|
|
|
100
104
|
GetJsonResult,
|
|
101
105
|
GetOptions,
|
|
102
106
|
GetResult,
|
|
107
|
+
GroupDeadLetter,
|
|
108
|
+
GroupDlqCursor,
|
|
109
|
+
GroupDlqDeleteOptions,
|
|
110
|
+
GroupDlqListOptions,
|
|
111
|
+
GroupDlqPage,
|
|
112
|
+
GroupDlqRequeueOptions,
|
|
113
|
+
GroupDlqResult,
|
|
103
114
|
GroupMemberState,
|
|
104
115
|
GroupReadResult,
|
|
105
116
|
GroupRecord,
|
|
106
117
|
GroupRefusal,
|
|
107
118
|
GroupReportResult,
|
|
119
|
+
GroupStealResult,
|
|
108
120
|
GroupTouchResult,
|
|
109
121
|
HistoryOptions,
|
|
110
122
|
HistoryResult,
|
|
@@ -153,8 +165,10 @@ from .types import (
|
|
|
153
165
|
ScanResult,
|
|
154
166
|
StatusCode,
|
|
155
167
|
StorageTier,
|
|
168
|
+
StreamAlterOptions,
|
|
156
169
|
StreamAppendOptions,
|
|
157
170
|
StreamAppendResult,
|
|
171
|
+
StreamCreateOptions,
|
|
158
172
|
StreamDeleteOptions,
|
|
159
173
|
StreamGroupAckOptions,
|
|
160
174
|
StreamGroupCreateOptions,
|
|
@@ -165,6 +179,7 @@ from .types import (
|
|
|
165
179
|
StreamGroupMembersResult,
|
|
166
180
|
StreamGroupNackOptions,
|
|
167
181
|
StreamGroupReadOptions,
|
|
182
|
+
StreamGroupStealOptions,
|
|
168
183
|
StreamID,
|
|
169
184
|
StreamInfo,
|
|
170
185
|
StreamInfoOptions,
|
|
@@ -231,7 +246,7 @@ from .worker import (
|
|
|
231
246
|
)
|
|
232
247
|
from .workflows import WorkflowOperations
|
|
233
248
|
|
|
234
|
-
__version__ = "0.1.
|
|
249
|
+
__version__ = "0.1.7"
|
|
235
250
|
|
|
236
251
|
__all__ = [
|
|
237
252
|
"Transaction",
|
|
@@ -325,6 +340,21 @@ __all__ = [
|
|
|
325
340
|
"HistoryOptions",
|
|
326
341
|
"EnqueueOptions",
|
|
327
342
|
"DequeueOptions",
|
|
343
|
+
"DlqCursor",
|
|
344
|
+
"DlqResult",
|
|
345
|
+
"DlqRequeueOptions",
|
|
346
|
+
"DlqDeleteOptions",
|
|
347
|
+
"GroupStealResult",
|
|
348
|
+
"GroupDeadLetter",
|
|
349
|
+
"GroupDlqCursor",
|
|
350
|
+
"GroupDlqPage",
|
|
351
|
+
"GroupDlqResult",
|
|
352
|
+
"StreamCreateOptions",
|
|
353
|
+
"StreamAlterOptions",
|
|
354
|
+
"StreamGroupStealOptions",
|
|
355
|
+
"GroupDlqListOptions",
|
|
356
|
+
"GroupDlqRequeueOptions",
|
|
357
|
+
"GroupDlqDeleteOptions",
|
|
328
358
|
"DlqListOptions",
|
|
329
359
|
"DlqPage",
|
|
330
360
|
"PeekOptions",
|