flo-python 0.1.0.dev4__py3-none-any.whl → 0.1.2__py3-none-any.whl

flo/retry.py

@@ -0,0 +1,124 @@
+"""Retrying requests the server refused without running them."""
+
+import asyncio
+import contextlib
+import math
+import random
+from dataclasses import dataclass
+
+from .exceptions import ServerError, raise_for_status
+from .types import Ran, StatusCode
+
+_RETRYABLE = (StatusCode.OVERLOADED, StatusCode.UNAVAILABLE)
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """How often a request the server refused without running it is sent again.
+
+    Only a refusal whose status is overloaded or unavailable and whose ``ran``
+    is ``Ran.NO`` is retried: the server says it never ran, so resending is
+    safe for any operation, writes included. Each retry is a new request with
+    a new id; the server routes it afresh.
+
+    Attributes:
+        max_attempts: Tries in all, the first included; 1 (or less) turns
+            retrying off.
+        initial_backoff_ms: Ceiling of the first wait, in milliseconds; each
+            later ceiling doubles, up to ``max_backoff_ms``. Each wait is
+            uniform in [0, ceiling].
+        max_backoff_ms: Largest ceiling, in milliseconds.
+
+    A negative or non-finite ``initial_backoff_ms`` counts as 0; a
+    ``max_backoff_ms`` that is non-finite or below ``initial_backoff_ms``
+    counts as ``initial_backoff_ms``; a non-finite ``max_attempts`` counts
+    as 1, and a fractional one is truncated.
+    """
+
+    max_attempts: int = 4
+    initial_backoff_ms: float = 50
+    max_backoff_ms: float = 1000
+
+    def __post_init__(self) -> None:
+        # A negative or non-finite bound would reach random.uniform or
+        # asyncio.sleep (where nan and inf never return), a max below the
+        # initial would make the ceiling jump down after the first wait, and
+        # a nan attempt count would never be reached.
+        initial = _finite_or(self.initial_backoff_ms, 0.0)
+        initial = max(initial, 0.0)
+        top = max(_finite_or(self.max_backoff_ms, initial), initial)
+        attempts = self.max_attempts
+        attempts = int(attempts) if math.isfinite(attempts) else 1
+        object.__setattr__(self, "initial_backoff_ms", initial)
+        object.__setattr__(self, "max_backoff_ms", top)
+        object.__setattr__(self, "max_attempts", attempts)
+
+
+def _finite_or(v: float, default: float) -> float:
+    return v if math.isfinite(v) else default
+
+
+# The default waits at most about 350 ms in all before giving back the refusal.
+DEFAULT_RETRY_POLICY = RetryPolicy()
+
+
+def _refused_unrun(status: StatusCode, data: bytes) -> bool:
+    """Whether a response is a refusal the server says it didn't run, of a
+    kind worth sending again. A refusal whose body doesn't say whether it ran
+    is not retried."""
+    if status not in _RETRYABLE:
+        return False
+    try:
+        raise_for_status(status, data)
+    except ServerError as e:
+        return e.ran == Ran.NO
+    except Exception:
+        return False
+    return False
+
+
+def is_refused_unrun(exc: BaseException) -> bool:
+    """Whether exc is a refusal the server says it didn't run, of a kind worth
+    trying again later."""
+    return isinstance(exc, ServerError) and exc.status_code in _RETRYABLE and exc.ran == Ran.NO
+
+
+class _Backoff:
+    """A capped, doubling, fully jittered wait, in seconds."""
+
+    def __init__(self, initial_s: float, max_s: float) -> None:
+        self._initial = max(initial_s, 0.0)
+        self._max = max(max_s, self._initial)
+        self._ceiling = 0.0
+
+    def next(self) -> float:
+        """The next wait; doubles the ceiling for the one after."""
+        if self._ceiling == 0:
+            self._ceiling = self._initial
+        d = random.uniform(0, self._ceiling)
+        self._ceiling = min(self._ceiling * 2, self._max)
+        return d
+
+    def reset(self) -> None:
+        """Start the waits again from the initial ceiling."""
+        self._ceiling = 0.0
+
+
+def _policy_backoff(policy: RetryPolicy) -> _Backoff:
+    return _Backoff(policy.initial_backoff_ms / 1000.0, policy.max_backoff_ms / 1000.0)
+
+
+# Worker poll loops wait this way after a failed poll, and start again from
+# the bottom after a poll that succeeds.
+_WORKER_INITIAL_BACKOFF_S = 0.1
+_WORKER_MAX_BACKOFF_S = 5.0
+
+
+def _worker_backoff() -> _Backoff:
+    return _Backoff(_WORKER_INITIAL_BACKOFF_S, _WORKER_MAX_BACKOFF_S)
+
+
+async def _sleep_unless_stopped(stop: asyncio.Event, seconds: float) -> None:
+    """Wait seconds, or until stop is set."""
+    with contextlib.suppress(asyncio.TimeoutError):
+        await asyncio.wait_for(stop.wait(), timeout=seconds)

flo/streams.py

@@ -4,13 +4,16 @@ Stream (append-only log) operations for Flo client.
 Uses StreamID-native positioning (timestamp_ms + sequence).
 """
 
+import struct
 from typing import TYPE_CHECKING
 
 from .types import (
     OpCode,
     OptionTag,
+    PendingEntry,
     StreamAppendOptions,
     StreamAppendResult,
+    StreamClaimResult,
     StreamGroupAckOptions,
     StreamGroupJoinOptions,
     StreamGroupNackOptions,
@@ -21,16 +24,25 @@ from .types import (
     StreamReadOptions,
     StreamReadResult,
     StreamTrimOptions,
+    StreamTrimResult,
 )
 from .wire import (
     OptionsBuilder,
+    build_stream_batch_value,
+    parse_pending_entries,
     parse_stream_append_response,
     parse_stream_info_response,
     parse_stream_read_response,
     serialize_group_ack_value,
+    serialize_group_claim_value,
+    serialize_group_pending_value,
     serialize_group_value,
 )
 
+# u64 max sentinel: group_claim returns StreamID.MAX when the PEL is fully
+# scanned (mirrors Go's math.MaxUint64 check).
+_U64_MAX = 0xFFFFFFFFFFFFFFFF
+
 if TYPE_CHECKING:
     from .client import FloClient
 
@@ -63,12 +75,13 @@ class StreamOperations:
         """
         opts = options or StreamAppendOptions()
         namespace = self._client.get_namespace(opts.namespace)
+        value = build_stream_batch_value(payload, opts.headers)
 
         response = await self._client._send_and_check(
             OpCode.STREAM_APPEND,
             namespace,
             stream.encode("utf-8"),
-            payload,
+            value,
             allow_not_found=True,
         )
 
@@ -182,21 +195,19 @@ class StreamOperations:
         self,
         stream: str,
         options: StreamTrimOptions | None = None,
-    ) -> None:
-        """Trim a stream based on retention policy.
+    ) -> StreamTrimResult:
+        """Remove a stream's oldest records by exactly one bound.
 
-        Args:
-            stream: Stream name.
-            options: Trim options (max_len, max_age_seconds, max_bytes, dry_run).
+        Set one of ``before``, ``max_len`` or ``max_age_seconds``; the server
+        refuses none or several. Trim cuts whole append batches, so ``max_len``
+        may keep a few more records than asked. With ``dry_run`` nothing is
+        removed and the result says what would be.
 
         Example:
-            # Keep only last 1000 records
+            # Keep only the newest 1000 records
             await client.stream.trim("events", StreamTrimOptions(max_len=1000))
 
-            # Delete records older than 1 day
-            await client.stream.trim("events", StreamTrimOptions(max_age_seconds=86400))
-
-            # Preview what would be deleted
+            # Count what that would remove, removing nothing
             await client.stream.trim("events", StreamTrimOptions(max_len=1000, dry_run=True))
         """
         opts = options or StreamTrimOptions()
@@ -204,26 +215,29 @@ class StreamOperations:
 
         builder = OptionsBuilder()
 
+        if opts.before is not None:
+            builder.add_bytes(OptionTag.STREAM_START, opts.before.to_bytes())
+
         if opts.max_len is not None:
-            builder.add_u64(OptionTag.RETENTION_COUNT, opts.max_len)
+            builder.add_u64(OptionTag.LIMIT, opts.max_len)
 
         if opts.max_age_seconds is not None:
-            builder.add_u64(OptionTag.RETENTION_AGE, opts.max_age_seconds)
-
-        if opts.max_bytes is not None:
-            builder.add_u64(OptionTag.RETENTION_BYTES, opts.max_bytes)
+            builder.add_u64(OptionTag.MAX_AGE_SECONDS, opts.max_age_seconds)
 
         if opts.dry_run:
             builder.add_flag(OptionTag.DRY_RUN)
 
-        await self._client._send_and_check(
+        response = await self._client._send_and_check(
             OpCode.STREAM_TRIM,
             namespace,
             stream.encode("utf-8"),
             b"",
             builder.build(),
-            allow_not_found=True,
         )
+        if len(response.data) != 16:
+            raise ValueError(f"stream trim: response is {len(response.data)} bytes, want 16")
+        removed, first_seq = struct.unpack("<QQ", response.data)
+        return StreamTrimResult(removed=removed, first_seq=first_seq)
 
     async def group_join(
         self,
@@ -294,11 +308,18 @@ class StreamOperations:
         consumer: str,
         options: StreamGroupReadOptions | None = None,
     ) -> StreamReadResult:
-        """Read records from a consumer group.
+        """Read new records from a consumer group, advancing last_delivered_id.
+
+        Records are distributed among consumers in the group; each record is
+        delivered to only one consumer and added to that consumer's Pending
+        Entry List (PEL) until acked. Unacknowledged records are redelivered.
 
-        Records are distributed among consumers in the group. Each record
-        is delivered to only one consumer. Unacknowledged records will be
-        redelivered.
+        Crash recovery: ``group_read`` alone is NOT sufficient. It only returns
+        records past ``last_delivered_id``, so a record delivered-but-unacked at
+        crash time is never re-surfaced by a later ``group_read``. To re-process
+        in-flight work after a reconnect, drain the PEL with :meth:`group_claim`
+        (StreamWorker does this automatically — see
+        ``redeliver_pending_on_reconnect``).
 
         Args:
             stream: Stream name.
@@ -340,6 +361,99 @@ class StreamOperations:
 
         return parse_stream_read_response(response.data)
 
+    async def group_pending(
+        self,
+        stream: str,
+        group: str,
+        consumer: str = "",
+        options: StreamGroupReadOptions | None = None,
+    ) -> list[PendingEntry]:
+        """List a consumer group's pending (delivered-but-unacked) entries.
+
+        If ``consumer`` is non-empty, only that consumer's entries are returned;
+        otherwise the whole group's PEL is returned.
+
+        Returns:
+            A list of :class:`PendingEntry`.
+        """
+        opts = options or StreamGroupReadOptions()
+        namespace = self._client.get_namespace(opts.namespace)
+
+        value = serialize_group_pending_value(group, consumer)
+
+        response = await self._client._send_and_check(
+            OpCode.STREAM_GROUP_PENDING,
+            namespace,
+            stream.encode("utf-8"),
+            value,
+            allow_not_found=True,
+        )
+
+        return parse_pending_entries(response.data)
+
+    async def group_claim(
+        self,
+        stream: str,
+        group: str,
+        consumer: str,
+        min_idle_ms: int,
+        start_id: StreamID,
+        count: int,
+        options: StreamGroupReadOptions | None = None,
+    ) -> StreamClaimResult:
+        """Claim a page of a consumer group's pending entries for ``consumer``.
+
+        Scans the PEL in StreamID order from ``start_id`` and takes up to
+        ``count`` entries idle for at least ``min_idle_ms``. Returns the claimed
+        records (payload + headers) plus a cursor for the next page.
+
+        * Drain own pending (reconnect): ``min_idle_ms=0``, ``start_id=StreamID()``.
+        * Steal from idle consumers (rebalance): ``min_idle_ms > 0``.
+
+        Loop until ``result.done`` to fully drain::
+
+            cursor = StreamID()
+            while True:
+                r = await client.stream.group_claim(
+                    stream, group, consumer, 0, cursor, 100)
+                for rec in r.records:
+                    process(rec)
+                if r.done or not r.records:
+                    break
+                cursor = r.next_cursor
+        """
+        opts = options or StreamGroupReadOptions()
+        namespace = self._client.get_namespace(opts.namespace)
+
+        value = serialize_group_claim_value(group, consumer, min_idle_ms, start_id, count)
+
+        response = await self._client._send_and_check(
+            OpCode.STREAM_GROUP_CLAIM,
+            namespace,
+            stream.encode("utf-8"),
+            value,
+            allow_not_found=True,
+        )
+
+        # Response = <records blob> + [next_ts:u64][next_seq:u64] trailer.
+        data = response.data or b""
+        if len(data) < 16:
+            return StreamClaimResult(records=[], next_cursor=StreamID(), done=True)
+
+        cursor_off = len(data) - 16
+        next_ts = int.from_bytes(data[cursor_off : cursor_off + 8], "little")
+        next_seq = int.from_bytes(data[cursor_off + 8 : cursor_off + 16], "little")
+
+        read = parse_stream_read_response(data[:cursor_off])
+
+        # StreamID.MAX (max, max) is the "fully scanned" sentinel.
+        done = next_ts == _U64_MAX and next_seq == _U64_MAX
+        return StreamClaimResult(
+            records=read.records,
+            next_cursor=StreamID(timestamp_ms=next_ts, sequence=next_seq),
+            done=done,
+        )
+
     async def group_ack(
         self,
         stream: str,
@@ -355,6 +469,10 @@ class StreamOperations:
             ids: StreamIDs of records to acknowledge.
             options: Optional ack options (including consumer name).
 
+        Raises:
+            NotFoundError: If the stream or group does not exist, so the ack
+                did not take effect.
+
         Example:
             result = await client.stream.group_read("events", "processors", "worker-1")
             for record in result.records:
@@ -378,7 +496,6 @@ class StreamOperations:
             namespace,
             stream.encode("utf-8"),
             value,
-            allow_not_found=True,
         )
 
     async def group_nack(
@@ -394,7 +511,11 @@ class StreamOperations:
             stream: Stream name.
             group: Consumer group name.
             ids: StreamIDs of records to negatively acknowledge.
-            options: Optional nack options (consumer name, redelivery delay).
+            options: Optional nack options (consumer name).
+
+        Raises:
+            NotFoundError: If the stream or group does not exist, so the nack
+                did not take effect.
 
         Example:
             result = await client.stream.group_read("events", "processors", "worker-1")
@@ -403,7 +524,7 @@ class StreamOperations:
                     process(record.payload)
                 except Exception:
                     await client.stream.group_nack("events", "processors", [record.id],
-                        StreamGroupNackOptions(consumer="worker-1", redelivery_delay_ms=5000))
+                        StreamGroupNackOptions(consumer="worker-1"))
         """
         if not ids:
             return
@@ -413,15 +534,9 @@ class StreamOperations:
 
         value = serialize_group_ack_value(group, ids, consumer=opts.consumer)
 
-        builder = OptionsBuilder()
-        if opts.redelivery_delay_ms is not None:
-            builder.add_u32(OptionTag.REDELIVERY_DELAY_MS, opts.redelivery_delay_ms)
-
         await self._client._send_and_check(
             OpCode.STREAM_GROUP_NACK,
             namespace,
             stream.encode("utf-8"),
             value,
-            builder.build(),
-            allow_not_found=True,
         )