flo-python 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev3__py3-none-any.whl

flo/__init__.py

@@ -24,7 +24,7 @@ Example:
             await client.action.invoke("process", b'{}')
 
             # Worker (created from client)
-            worker = client.new_worker(concurrency=5)
+            worker = client.new_action_worker(concurrency=5)
             worker.register_action("my-action", handler)
             await worker.start()
 
@@ -45,6 +45,7 @@ from .exceptions import (
     InvalidMagicError,
     KeyTooLargeError,
     NamespaceTooLargeError,
+    NonRetryableError,
     NotConnectedError,
     NotFoundError,
     OverloadedError,
@@ -57,11 +58,11 @@ from .exceptions import (
     UnsupportedVersionError,
     ValidationError,
     ValueTooLargeError,
+    is_connection_error,
 )
+from .processing import ProcessingOperations
 from .types import (
-    # KV types
     AckOptions,
-    # Action types
     ActionDeleteOptions,
     ActionInfo,
     ActionInvokeOptions,
@@ -86,11 +87,22 @@ from .types import (
     OpCode,
     OptionTag,
     PeekOptions,
+    ProcessingCancelOptions,
+    ProcessingListEntry,
+    ProcessingListOptions,
+    ProcessingRescaleOptions,
+    ProcessingRestoreOptions,
+    ProcessingSavepointOptions,
+    ProcessingStatusOptions,
+    ProcessingStatusResult,
+    ProcessingStopOptions,
+    ProcessingSubmitOptions,
+    ProcessingSyncOptions,
+    ProcessingSyncResult,
     PutOptions,
     ScanOptions,
     ScanResult,
     StatusCode,
-    # Stream types
     StorageTier,
     StreamAppendOptions,
     StreamAppendResult,
@@ -105,7 +117,6 @@ from .types import (
     StreamReadResult,
     StreamRecord,
     StreamTrimOptions,
-    # Worker types
     TaskAssignment,
     TouchOptions,
     VersionEntry,
@@ -119,8 +130,31 @@ from .types import (
     WorkerRegisterOptions,
     WorkerTask,
     WorkerTouchOptions,
+    WorkflowCancelOptions,
+    WorkflowCreateOptions,
+    WorkflowDisableOptions,
+    WorkflowEnableOptions,
+    WorkflowGetDefinitionOptions,
+    WorkflowHistoryOptions,
+    WorkflowListDefinitionsOptions,
+    WorkflowListRunsOptions,
+    WorkflowSignalOptions,
+    WorkflowStartOptions,
+    WorkflowStatusOptions,
+    WorkflowSyncOptions,
+    WorkflowSyncResult,
+)
+from .worker import (
+    ActionContext,
+    ActionResult,
+    ActionWorker,
+    ActionWorkerOptions,
+    StreamContext,
+    StreamRecordHandler,
+    StreamWorker,
+    StreamWorkerOptions,
 )
-from .worker import ActionContext, Worker, WorkerOptions
+from .workflows import WorkflowOperations
 
 __version__ = "0.1.0"
 
@@ -128,11 +162,19 @@ __all__ = [
     # Client
     "FloClient",
     # High-level Worker API
-    "Worker",
-    "WorkerOptions",
+    "ActionWorker",
+    "ActionWorkerOptions",
     "ActionContext",
+    "ActionResult",
+    "StreamWorker",
+    "StreamWorkerOptions",
+    "StreamContext",
+    "StreamRecordHandler",
+    "WorkflowOperations",
+    "ProcessingOperations",
     # Exceptions
     "FloError",
+    "NonRetryableError",
     "NotConnectedError",
     "ConnectionFailedError",
     "InvalidEndpointError",
@@ -156,6 +198,7 @@ __all__ = [
     "RateLimitedError",
     "InternalServerError",
     "GenericServerError",
+    "is_connection_error",
     # Types
     "OpCode",
     "StatusCode",
@@ -221,4 +264,33 @@ __all__ = [
     "WorkerCompleteOptions",
     "WorkerFailOptions",
     "WorkerListOptions",
+    # Workflow types
+    "WorkflowOperations",
+    "WorkflowCreateOptions",
+    "WorkflowGetDefinitionOptions",
+    "WorkflowStartOptions",
+    "WorkflowStatusOptions",
+    "WorkflowSignalOptions",
+    "WorkflowCancelOptions",
+    "WorkflowHistoryOptions",
+    "WorkflowListRunsOptions",
+    "WorkflowListDefinitionsOptions",
+    "WorkflowDisableOptions",
+    "WorkflowEnableOptions",
+    "WorkflowSyncOptions",
+    "WorkflowSyncResult",
+    # Processing types
+    "ProcessingOperations",
+    "ProcessingSubmitOptions",
+    "ProcessingStatusOptions",
+    "ProcessingListOptions",
+    "ProcessingStopOptions",
+    "ProcessingCancelOptions",
+    "ProcessingSavepointOptions",
+    "ProcessingRestoreOptions",
+    "ProcessingRescaleOptions",
+    "ProcessingSyncOptions",
+    "ProcessingStatusResult",
+    "ProcessingListEntry",
+    "ProcessingSyncResult",
 ]

flo/actions.py

@@ -68,7 +68,7 @@ class ActionOperations:
 
         Args:
             name: Action name.
-            action_type: Type of action (USER or WASM).
+            action_type: Type of action (USER only).
             options: Optional registration options.
         """
         opts = options or ActionRegisterOptions()
@@ -231,7 +231,12 @@ class WorkerOperations:
         opts = options or WorkerRegisterOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_register_value(task_types)
+        value = serialize_worker_register_value(
+            task_types,
+            max_concurrency=opts.concurrency,
+            metadata=opts.metadata,
+            machine_id=opts.machine_id,
+        )
 
         await self._client._send_and_check(
             OpCode.WORKER_REGISTER,
@@ -240,6 +245,30 @@ class WorkerOperations:
             value,
         )
 
+    async def heartbeat(
+        self,
+        worker_id: str,
+        current_load: int = 0,
+        namespace: str | None = None,
+    ) -> None:
+        """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.
+        """
+        import struct
+
+        ns = self._client.get_namespace(namespace)
+        value = struct.pack("<I", current_load)
+        await self._client._send_and_check(
+            OpCode.WORKER_HEARTBEAT,
+            ns,
+            worker_id.encode("utf-8"),
+            value,
+        )
+
     async def await_task(
         self,
         worker_id: str,
@@ -269,7 +298,7 @@ class WorkerOperations:
             options_builder.add_u32(OptionTag.TIMEOUT_MS, opts.timeout_ms)
 
         response = await self._client._send_and_check(
-            OpCode.WORKER_AWAIT,
+            OpCode.ACTION_AWAIT,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -287,6 +316,7 @@ class WorkerOperations:
     async def touch(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         options: WorkerTouchOptions | None = None,
     ) -> None:
@@ -294,16 +324,17 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier to extend.
             options: Optional touch options (extend_ms).
         """
         opts = options or WorkerTouchOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_touch_value(task_id, opts.extend_ms)
+        value = serialize_worker_touch_value(action_name, task_id, opts.extend_ms)
 
         await self._client._send_and_check(
-            OpCode.WORKER_TOUCH,
+            OpCode.ACTION_TOUCH,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -312,6 +343,7 @@ class WorkerOperations:
     async def complete(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         result: bytes,
         options: WorkerCompleteOptions | None = None,
@@ -320,6 +352,7 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier to complete.
             result: Result data from the task.
             options: Optional complete options.
@@ -327,10 +360,10 @@ class WorkerOperations:
         opts = options or WorkerCompleteOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_complete_value(task_id, result)
+        value = serialize_worker_complete_value(action_name, task_id, result, opts.outcome)
 
         await self._client._send_and_check(
-            OpCode.WORKER_COMPLETE,
+            OpCode.ACTION_COMPLETE,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -339,6 +372,7 @@ class WorkerOperations:
     async def fail(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         error_message: str,
         options: WorkerFailOptions | None = None,
@@ -347,6 +381,7 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier that failed.
             error_message: Error message describing the failure.
             options: Optional fail options (retry flag).
@@ -354,19 +389,13 @@ class WorkerOperations:
         opts = options or WorkerFailOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_fail_value(task_id, error_message)
-
-        # Retry flag goes in TLV options (matches Go SDK)
-        options_builder = OptionsBuilder()
-        if opts.retry:
-            options_builder.add_flag(OptionTag.RETRY)
+        value = serialize_worker_fail_value(action_name, task_id, error_message, opts.retry)
 
         await self._client._send_and_check(
-            OpCode.WORKER_FAIL,
+            OpCode.ACTION_FAIL,
             namespace,
             worker_id.encode("utf-8"),
             value,
-            options_builder.build(),
         )
 
     async def list(

flo/client.py

@@ -19,7 +19,7 @@ from .types import HEADER_SIZE, OpCode, StatusCode
 from .wire import RawResponse, parse_response_header, serialize_request
 
 if TYPE_CHECKING:
-    from .worker import Worker
+    from .worker import ActionWorker, StreamRecordHandler, StreamWorker
 
 logger = logging.getLogger("flo")
 
@@ -65,14 +65,18 @@ class FloClient:
         # Initialize operation mixins (will be set after import to avoid circular deps)
         from .actions import ActionOperations, WorkerOperations
         from .kv import KVOperations
+        from .processing import ProcessingOperations
         from .queue import QueueOperations
         from .streams import StreamOperations
+        from .workflows import WorkflowOperations
 
         self.kv = KVOperations(self)
         self.queue = QueueOperations(self)
         self.stream = StreamOperations(self)
         self.action = ActionOperations(self)
         self.worker = WorkerOperations(self)
+        self.workflow = WorkflowOperations(self)
+        self.processing = ProcessingOperations(self)
 
         if debug:
             logging.basicConfig(level=logging.DEBUG)
@@ -133,14 +137,73 @@ class FloClient:
 
     async def close(self) -> None:
         """Close the connection."""
-        if self._writer:
-            self._writer.close()
-            with contextlib.suppress(Exception):
-                await self._writer.wait_closed()
-            self._writer = None
-            self._reader = None
-            if self._debug:
-                logger.debug("[flo] Disconnected")
+        async with self._lock:
+            if self._writer:
+                self._writer.close()
+                with contextlib.suppress(Exception):
+                    await self._writer.wait_closed()
+                self._writer = None
+                self._reader = None
+                if self._debug:
+                    logger.debug("[flo] Disconnected")
+
+    def interrupt(self) -> None:
+        """Forcibly close the underlying connection without acquiring the lock.
+
+        This unblocks any in-flight ``_send_request`` that is holding the lock
+        (e.g. a blocking Await). The interrupted call will raise an error, and
+        the caller should reconnect before reusing the client.
+        """
+        writer = self._writer
+        if writer is not None:
+            writer.close()
+
+    async def reconnect(self, *, timeout: float = 300.0) -> None:
+        """Close and re-establish the connection with exponential back-off.
+
+        Retries from 1 s up to 30 s intervals until *timeout* seconds elapse.
+
+        Args:
+            timeout: Maximum total time to keep retrying (default 5 min).
+        """
+        async with self._lock:
+            # Close existing connection
+            if self._writer:
+                self._writer.close()
+                with contextlib.suppress(Exception):
+                    await self._writer.wait_closed()
+                self._writer = None
+                self._reader = None
+
+        backoff = 1.0
+        max_backoff = 30.0
+        deadline = asyncio.get_event_loop().time() + timeout
+        attempt = 0
+
+        while True:
+            attempt += 1
+            try:
+                self._reader, self._writer = await asyncio.wait_for(
+                    asyncio.open_connection(self._host, self._port),
+                    timeout=self._timeout,
+                )
+                if self._debug:
+                    logger.debug(f"[flo] Reconnected to {self._endpoint} (attempt {attempt})")
+                return
+            except (asyncio.TimeoutError, OSError) as exc:
+                now = asyncio.get_event_loop().time()
+                if now >= deadline:
+                    raise ConnectionFailedError(
+                        f"Failed to reconnect to {self._endpoint} after {attempt} attempts"
+                    ) from exc
+                logger.warning(
+                    "[flo] Reconnect attempt %d failed: %s, retrying in %.0fs...",
+                    attempt,
+                    exc,
+                    backoff,
+                )
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, max_backoff)
 
     async def __aenter__(self) -> "FloClient":
         """Async context manager entry."""
@@ -287,15 +350,15 @@ class FloClient:
         """Get effective namespace, using override if provided."""
         return override if override is not None else self._namespace
 
-    def new_worker(
+    def new_action_worker(
         self,
         *,
         worker_id: str | None = None,
         concurrency: int = 10,
         action_timeout: float = 300.0,
         block_ms: int = 30000,
-    ) -> "Worker":
-        """Create a new Worker from this client.
+    ) -> "ActionWorker":
+        """Create a new ActionWorker from this client.
 
         The worker inherits the client's endpoint and namespace, and creates
         a dedicated connection for polling tasks.
@@ -307,20 +370,78 @@ class FloClient:
             block_ms: Timeout for blocking dequeue in milliseconds.
 
         Returns:
-            A new Worker instance ready to register actions and start.
+            A new ActionWorker instance ready to register actions and start.
 
         Example:
             async with FloClient("localhost:3000", namespace="myapp") as client:
-                worker = client.new_worker(concurrency=5)
+                worker = client.new_action_worker(concurrency=5)
                 worker.register_action("process-order", process_order)
                 await worker.start()
         """
-        from .worker import Worker
+        from .worker import ActionWorker
 
-        return Worker(
+        return ActionWorker(
             self,
             worker_id=worker_id,
             concurrency=concurrency,
             action_timeout=action_timeout,
             block_ms=block_ms,
         )
+
+    def new_stream_worker(
+        self,
+        *,
+        stream: str,
+        group: str,
+        handler: "StreamRecordHandler",
+        consumer: str | None = None,
+        worker_id: str | None = None,
+        concurrency: int = 10,
+        batch_size: int = 10,
+        block_ms: int = 30000,
+        message_timeout: float = 300.0,
+    ) -> "StreamWorker":
+        """Create a new StreamWorker from this client.
+
+        The worker joins a consumer group on the specified stream, polls for
+        records, and dispatches them to the handler. Records are auto-acked
+        on success and auto-nacked on error.
+
+        Args:
+            stream: Stream name to consume from.
+            group: Consumer group name.
+            handler: Async callable that processes each StreamContext.
+            consumer: Consumer ID (auto-generated if not provided).
+            worker_id: Unique worker identifier (auto-generated if not provided).
+            concurrency: Maximum number of concurrent record handlers.
+            batch_size: Number of records to fetch per poll.
+            block_ms: Timeout for blocking read in milliseconds.
+            message_timeout: Timeout for record handlers in seconds.
+
+        Returns:
+            A new StreamWorker instance ready to start.
+
+        Example:
+            async def process_event(ctx):
+                event = ctx.json()
+                print(f"Got: {event}")
+
+            worker = client.new_stream_worker(
+                stream="events", group="processors", handler=process_event
+            )
+            await worker.start()
+        """
+        from .worker import StreamWorker
+
+        return StreamWorker(
+            self,
+            handler,
+            stream=stream,
+            group=group,
+            consumer=consumer,
+            worker_id=worker_id,
+            concurrency=concurrency,
+            batch_size=batch_size,
+            block_ms=block_ms,
+            message_timeout=message_timeout,
+        )

flo/exceptions.py

@@ -14,6 +14,19 @@ class FloError(Exception):
     pass
 
 
+class NonRetryableError(FloError):
+    """Marks an action error as non-retryable.
+
+    When raised from an action handler, the task will be failed with
+    retry=False, so the server will not re-queue it.
+
+    Example:
+        raise NonRetryableError("invalid input, will never succeed")
+    """
+
+    pass
+
+
 # =============================================================================
 # Connection Errors
 # =============================================================================
@@ -190,6 +203,14 @@ class GenericServerError(ServerError):
         super().__init__(message, StatusCode.ERROR_GENERIC)
 
 
+def is_connection_error(exc: BaseException) -> bool:
+    """Return True if the exception indicates a broken connection.
+
+    Connection errors may be resolved by reconnecting.
+    """
+    return isinstance(exc, (UnexpectedEofError, NotConnectedError))
+
+
 def raise_for_status(status: StatusCode, data: bytes = b"") -> None:
     """Raise appropriate exception for non-OK status codes.
 

flo/kv.py

@@ -3,6 +3,7 @@
 Key-value store operations for Flo client.
 """
 
+import struct
 from typing import TYPE_CHECKING
 
 from .types import (
@@ -194,17 +195,16 @@ class KVOperations:
 
         prefix_bytes = prefix.encode("utf-8") if isinstance(prefix, str) else prefix
 
-        # Build TLV options
+        # Build TLV options (keys_only only — limit is in value now)
         builder = OptionsBuilder()
 
-        if opts.limit is not None:
-            builder.add_u32(OptionTag.LIMIT, opts.limit)
-
         if opts.keys_only:
             builder.add_u8(OptionTag.KEYS_ONLY, 1)
 
-        # Cursor goes in value field
-        value = opts.cursor if opts.cursor is not None else b""
+        # Value: [limit:u32][cursor...]
+        limit = opts.limit if opts.limit is not None else 0  # 0 = server default
+        cursor = opts.cursor if opts.cursor is not None else b""
+        value = struct.pack("<I", limit) + cursor
 
         response = await self._client._send_and_check(
             OpCode.KV_SCAN,