dbos 0.19.0a4__py3-none-any.whl → 0.20.0a2__py3-none-any.whl

dbos/_admin_server.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import re
 import threading
 from functools import partial
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -15,6 +16,9 @@ if TYPE_CHECKING:
 _health_check_path = "/dbos-healthz"
 _workflow_recovery_path = "/dbos-workflow-recovery"
 _deactivate_path = "/deactivate"
+# /workflows/:workflow_id/cancel
+# /workflows/:workflow_id/resume
+# /workflows/:workflow_id/restart
 
 
 class AdminServer:
@@ -79,12 +83,51 @@ class AdminRequestHandler(BaseHTTPRequestHandler):
             self._end_headers()
             self.wfile.write(json.dumps(workflow_ids).encode("utf-8"))
         else:
-            self.send_response(404)
-            self._end_headers()
+
+            restart_match = re.match(
+                r"^/workflows/(?P<workflow_id>[^/]+)/restart$", self.path
+            )
+            resume_match = re.match(
+                r"^/workflows/(?P<workflow_id>[^/]+)/resume$", self.path
+            )
+            cancel_match = re.match(
+                r"^/workflows/(?P<workflow_id>[^/]+)/cancel$", self.path
+            )
+
+            if restart_match:
+                workflow_id = restart_match.group("workflow_id")
+                self._handle_restart(workflow_id)
+            elif resume_match:
+                workflow_id = resume_match.group("workflow_id")
+                self._handle_resume(workflow_id)
+            elif cancel_match:
+                workflow_id = cancel_match.group("workflow_id")
+                self._handle_cancel(workflow_id)
+            else:
+                self.send_response(404)
+                self._end_headers()
 
     def log_message(self, format: str, *args: Any) -> None:
         return  # Disable admin server request logging
 
+    def _handle_restart(self, workflow_id: str) -> None:
+        self.dbos.restart_workflow(workflow_id)
+        print("Restarting workflow", workflow_id)
+        self.send_response(204)
+        self._end_headers()
+
+    def _handle_resume(self, workflow_id: str) -> None:
+        print("Resuming workflow", workflow_id)
+        self.dbos.resume_workflow(workflow_id)
+        self.send_response(204)
+        self._end_headers()
+
+    def _handle_cancel(self, workflow_id: str) -> None:
+        print("Cancelling workflow", workflow_id)
+        self.dbos.cancel_workflow(workflow_id)
+        self.send_response(204)
+        self._end_headers()
+
 
 # Be consistent with DBOS-TS response.
 class PerfUtilization(TypedDict):

dbos/_context.py

@@ -57,6 +57,7 @@ class DBOSContext:
         self.request: Optional["Request"] = None
 
         self.id_assigned_for_next_workflow: str = ""
+        self.is_within_set_workflow_id_block: bool = False
 
         self.parent_workflow_id: str = ""
         self.parent_workflow_fid: int = -1
@@ -78,6 +79,7 @@ class DBOSContext:
         rv.logger = self.logger
         rv.id_assigned_for_next_workflow = self.id_assigned_for_next_workflow
         self.id_assigned_for_next_workflow = ""
+        rv.is_within_set_workflow_id_block = self.is_within_set_workflow_id_block
         rv.parent_workflow_id = self.workflow_id
         rv.parent_workflow_fid = self.function_id
         rv.in_recovery = self.in_recovery
@@ -95,6 +97,10 @@ class DBOSContext:
         if len(self.id_assigned_for_next_workflow) > 0:
             wfid = self.id_assigned_for_next_workflow
         else:
+            if self.is_within_set_workflow_id_block:
+                self.logger.warning(
+                    f"Multiple workflows started in the same SetWorkflowID block. Only the first workflow is assigned the specified workflow ID; subsequent workflows will use a generated workflow ID."
+                )
             wfid = str(uuid.uuid4())
         return wfid
 
@@ -286,7 +292,7 @@ class DBOSContextSwap:
 
 class SetWorkflowID:
     """
-    Set the workflow ID to be used for the enclosed workflow invocation.
+    Set the workflow ID to be used for the enclosed workflow invocation. Note: Only the first workflow will be started with the specified workflow ID within a `with SetWorkflowID` block.
 
     Typical Usage
         ```
@@ -311,7 +317,9 @@ class SetWorkflowID:
         if ctx is None:
             self.created_ctx = True
             _set_local_dbos_context(DBOSContext())
-        assert_current_dbos_context().id_assigned_for_next_workflow = self.wfid
+        ctx = assert_current_dbos_context()
+        ctx.id_assigned_for_next_workflow = self.wfid
+        ctx.is_within_set_workflow_id_block = True
         return self
 
     def __exit__(
@@ -321,6 +329,7 @@ class SetWorkflowID:
         traceback: Optional[TracebackType],
     ) -> Literal[False]:
         # Code to clean up the basic context if we created it
+        assert_current_dbos_context().is_within_set_workflow_id_block = False
         if self.created_ctx:
             _clear_local_dbos_context()
         return False  # Did not handle

dbos/_core.py

@@ -188,6 +188,7 @@ def _init_workflow(
         wf_status = dbos._sys_db.update_workflow_status(
             status, False, ctx.in_recovery, max_recovery_attempts=max_recovery_attempts
         )
+        # TODO: Modify the inputs if they were changed by `update_workflow_inputs`
         dbos._sys_db.update_workflow_inputs(wfid, _serialization.serialize_args(inputs))
     else:
         # Buffer the inputs for single-transaction workflows, but don't buffer the status
@@ -265,7 +266,9 @@ def _execute_workflow_wthread(
                 raise
 
 
-def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[Any]":
+def execute_workflow_by_id(
+    dbos: "DBOS", workflow_id: str, startNew: bool = False
+) -> "WorkflowHandle[Any]":
     status = dbos._sys_db.get_workflow_status(workflow_id)
     if not status:
         raise DBOSRecoveryError(workflow_id, "Workflow status not found")
@@ -292,7 +295,8 @@ def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[An
                     workflow_id,
                     f"Cannot execute workflow because instance '{iname}' is not registered",
                 )
-            with SetWorkflowID(workflow_id):
+
+            if startNew:
                 return start_workflow(
                     dbos,
                     wf_func,
@@ -302,6 +306,17 @@ def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[An
                     *inputs["args"],
                     **inputs["kwargs"],
                 )
+            else:
+                with SetWorkflowID(workflow_id):
+                    return start_workflow(
+                        dbos,
+                        wf_func,
+                        status["queue_name"],
+                        True,
+                        dbos._registry.instance_info_map[iname],
+                        *inputs["args"],
+                        **inputs["kwargs"],
+                    )
         elif status["class_name"] is not None:
             class_name = status["class_name"]
             if class_name not in dbos._registry.class_info_map:
@@ -309,7 +324,8 @@ def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[An
                     workflow_id,
                     f"Cannot execute workflow because class '{class_name}' is not registered",
                 )
-            with SetWorkflowID(workflow_id):
+
+            if startNew:
                 return start_workflow(
                     dbos,
                     wf_func,
@@ -319,8 +335,19 @@ def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[An
                     *inputs["args"],
                     **inputs["kwargs"],
                 )
+            else:
+                with SetWorkflowID(workflow_id):
+                    return start_workflow(
+                        dbos,
+                        wf_func,
+                        status["queue_name"],
+                        True,
+                        dbos._registry.class_info_map[class_name],
+                        *inputs["args"],
+                        **inputs["kwargs"],
+                    )
         else:
-            with SetWorkflowID(workflow_id):
+            if startNew:
                 return start_workflow(
                     dbos,
                     wf_func,
@@ -329,6 +356,16 @@ def execute_workflow_by_id(dbos: "DBOS", workflow_id: str) -> "WorkflowHandle[An
                     *inputs["args"],
                     **inputs["kwargs"],
                 )
+            else:
+                with SetWorkflowID(workflow_id):
+                    return start_workflow(
+                        dbos,
+                        wf_func,
+                        status["queue_name"],
+                        True,
+                        *inputs["args"],
+                        **inputs["kwargs"],
+                    )
 
 
 @overload
@@ -422,6 +459,9 @@ def start_workflow(
         or wf_status == WorkflowStatusString.ERROR.value
         or wf_status == WorkflowStatusString.SUCCESS.value
     ):
+        dbos.logger.debug(
+            f"Workflow {new_wf_id} already completed with status {wf_status}. Directly returning a workflow handle."
+        )
         return WorkflowHandlePolling(new_wf_id, dbos)
 
     if fself is not None:
@@ -494,7 +534,7 @@ def workflow_wrapper(
                 temp_wf_type=get_temp_workflow_type(func),
                 max_recovery_attempts=max_recovery_attempts,
             )
-
+            # TODO: maybe modify the parameters if they've been changed by `_init_workflow`
             dbos.logger.debug(
                 f"Running workflow, id: {ctx.workflow_id}, name: {get_dbos_func_name(func)}"
             )

dbos/_dbos.py

@@ -56,6 +56,7 @@ from ._registrations import (
 )
 from ._roles import default_required_roles, required_roles
 from ._scheduler import ScheduledWorkflow, scheduled
+from ._sys_db import WorkflowStatusString
 from ._tracer import dbos_tracer
 
 if TYPE_CHECKING:
@@ -231,6 +232,7 @@ class DBOS:
                         f"DBOS configured multiple times with conflicting information"
                     )
                 config = _dbos_global_registry.config
+
             _dbos_global_instance = super().__new__(cls)
             _dbos_global_instance.__init__(fastapi=fastapi, config=config, flask=flask)  # type: ignore
         else:
@@ -767,6 +769,11 @@ class DBOS:
         """Execute a workflow by ID (for recovery)."""
         return execute_workflow_by_id(_get_dbos_instance(), workflow_id)
 
+    @classmethod
+    def restart_workflow(cls, workflow_id: str) -> None:
+        """Execute a workflow by ID (for recovery)."""
+        execute_workflow_by_id(_get_dbos_instance(), workflow_id, True)
+
     @classmethod
     def recover_pending_workflows(
         cls, executor_ids: List[str] = ["local"]
@@ -774,6 +781,18 @@ class DBOS:
         """Find all PENDING workflows and execute them."""
         return recover_pending_workflows(_get_dbos_instance(), executor_ids)
 
+    @classmethod
+    def cancel_workflow(cls, workflow_id: str) -> None:
+        """Cancel a workflow by ID."""
+        _get_dbos_instance()._sys_db.set_workflow_status(
+            workflow_id, WorkflowStatusString.CANCELLED, False
+        )
+
+    @classmethod
+    def resume_workflow(cls, workflow_id: str) -> None:
+        """Resume a workflow by ID."""
+        execute_workflow_by_id(_get_dbos_instance(), workflow_id, False)
+
     @classproperty
     def logger(cls) -> Logger:
         """Return the DBOS `Logger` for the current context."""

dbos/_error.py

@@ -35,6 +35,7 @@ class DBOSErrorCode(Enum):
     DeadLetterQueueError = 6
     MaxStepRetriesExceeded = 7
     NotAuthorized = 8
+    ConflictingWorkflowError = 9
 
 
 class DBOSWorkflowConflictIDError(DBOSException):
@@ -47,6 +48,16 @@ class DBOSWorkflowConflictIDError(DBOSException):
         )
 
 
+class DBOSConflictingWorkflowError(DBOSException):
+    """Exception raised different workflows started with the same workflow ID."""
+
+    def __init__(self, workflow_id: str, message: Optional[str] = None):
+        super().__init__(
+            f"Conflicting workflow invocation with the same ID ({workflow_id}): {message}",
+            dbos_error_code=DBOSErrorCode.ConflictingWorkflowError.value,
+        )
+
+
 class DBOSRecoveryError(DBOSException):
     """Exception raised when a workflow recovery fails."""
 

dbos/_fastapi.py

@@ -94,7 +94,11 @@ def setup_fastapi_middleware(app: FastAPI, dbos: DBOS) -> None:
         with EnterDBOSHandler(attributes):
             ctx = assert_current_dbos_context()
             ctx.request = _make_request(request)
-            workflow_id = request.headers.get("dbos-idempotency-key", "")
-            with SetWorkflowID(workflow_id):
+            workflow_id = request.headers.get("dbos-idempotency-key")
+            if workflow_id is not None:
+                # Set the workflow ID for the handler
+                with SetWorkflowID(workflow_id):
+                    response = await call_next(request)
+            else:
                 response = await call_next(request)
         return response

dbos/_flask.py

@@ -34,8 +34,12 @@ class FlaskMiddleware:
         with EnterDBOSHandler(attributes):
             ctx = assert_current_dbos_context()
             ctx.request = _make_request(request)
-            workflow_id = request.headers.get("dbos-idempotency-key", "")
-            with SetWorkflowID(workflow_id):
+            workflow_id = request.headers.get("dbos-idempotency-key")
+            if workflow_id is not None:
+                # Set the workflow ID for the handler
+                with SetWorkflowID(workflow_id):
+                    response = self.app(environ, start_response)
+            else:
                 response = self.app(environ, start_response)
         return response
 

dbos/_kafka.py

@@ -1,3 +1,4 @@
+import re
 import threading
 from typing import TYPE_CHECKING, Any, Callable, NoReturn
 
@@ -19,6 +20,14 @@ _kafka_queue: Queue
 _in_order_kafka_queues: dict[str, Queue] = {}
 
 
+def safe_group_name(method_name: str, topics: list[str]) -> str:
+    safe_group_id = "-".join(
+        re.sub(r"[^a-zA-Z0-9\-]", "", str(r)) for r in [method_name, *topics]
+    )
+
+    return f"dbos-kafka-group-{safe_group_id}"[:255]
+
+
 def _kafka_consumer_loop(
     func: _KafkaConsumerWorkflow,
     config: dict[str, Any],
@@ -34,6 +43,12 @@ def _kafka_consumer_loop(
     if "auto.offset.reset" not in config:
         config["auto.offset.reset"] = "earliest"
 
+    if config.get("group.id") is None:
+        config["group.id"] = safe_group_name(func.__qualname__, topics)
+        dbos_logger.warning(
+            f"Consumer group ID not found. Using generated group.id {config['group.id']}"
+        )
+
     consumer = Consumer(config)
     try:
         consumer.subscribe(topics)
@@ -71,8 +86,9 @@ def _kafka_consumer_loop(
                     topic=cmsg.topic(),
                     value=cmsg.value(),
                 )
+                groupID = config.get("group.id")
                 with SetWorkflowID(
-                    f"kafka-unique-id-{msg.topic}-{msg.partition}-{msg.offset}"
+                    f"kafka-unique-id-{msg.topic}-{msg.partition}-{groupID}-{msg.offset}"
                 ):
                     if in_order:
                         assert msg.topic is not None

dbos/_queue.py

@@ -36,6 +36,7 @@ class Queue:
         name: str,
         concurrency: Optional[int] = None,
         limiter: Optional[QueueRateLimit] = None,
+        *,  # Disable positional arguments from here on
         worker_concurrency: Optional[int] = None,
     ) -> None:
         if (

dbos/_sys_db.py

@@ -28,6 +28,7 @@ from sqlalchemy.exc import DBAPIError
 from . import _serialization
 from ._dbos_config import ConfigFile
 from ._error import (
+    DBOSConflictingWorkflowError,
     DBOSDeadLetterQueueError,
     DBOSException,
     DBOSNonExistentWorkflowError,
@@ -288,8 +289,14 @@ class SystemDatabase:
                 ),
             )
         else:
-            cmd = cmd.on_conflict_do_nothing()
-        cmd = cmd.returning(SystemSchema.workflow_status.c.recovery_attempts, SystemSchema.workflow_status.c.status)  # type: ignore
+            # A blank update so that we can return the existing status
+            cmd = cmd.on_conflict_do_update(
+                index_elements=["workflow_uuid"],
+                set_=dict(
+                    recovery_attempts=SystemSchema.workflow_status.c.recovery_attempts
+                ),
+            )
+        cmd = cmd.returning(SystemSchema.workflow_status.c.recovery_attempts, SystemSchema.workflow_status.c.status, SystemSchema.workflow_status.c.name, SystemSchema.workflow_status.c.class_name, SystemSchema.workflow_status.c.config_name, SystemSchema.workflow_status.c.queue_name)  # type: ignore
 
         if conn is not None:
             results = conn.execute(cmd)
@@ -297,37 +304,53 @@ class SystemDatabase:
             with self.engine.begin() as c:
                 results = c.execute(cmd)
 
-        if in_recovery:
-            row = results.fetchone()
-            if row is not None:
-                recovery_attempts: int = row[0]
-                wf_status = row[1]
-                if recovery_attempts > max_recovery_attempts:
-                    with self.engine.begin() as c:
-                        c.execute(
-                            sa.delete(SystemSchema.workflow_queue).where(
-                                SystemSchema.workflow_queue.c.workflow_uuid
-                                == status["workflow_uuid"]
-                            )
+        row = results.fetchone()
+        if row is not None:
+            # Check the started workflow matches the expected name, class_name, config_name, and queue_name
+            # A mismatch indicates a workflow starting with the same UUID but different functions, which would throw an exception.
+            recovery_attempts: int = row[0]
+            wf_status = row[1]
+            err_msg: Optional[str] = None
+            if row[2] != status["name"]:
+                err_msg = f"Workflow already exists with a different function name: {row[2]}, but the provided function name is: {status['name']}"
+            elif row[3] != status["class_name"]:
+                err_msg = f"Workflow already exists with a different class name: {row[3]}, but the provided class name is: {status['class_name']}"
+            elif row[4] != status["config_name"]:
+                err_msg = f"Workflow already exists with a different config name: {row[4]}, but the provided config name is: {status['config_name']}"
+            elif row[5] != status["queue_name"]:
+                # This is a warning because a different queue name is not necessarily an error.
+                dbos_logger.warning(
+                    f"Workflow already exists in queue: {row[5]}, but the provided queue name is: {status['queue_name']}. The queue is not updated."
+                )
+            if err_msg is not None:
+                raise DBOSConflictingWorkflowError(status["workflow_uuid"], err_msg)
+
+            if in_recovery and recovery_attempts > max_recovery_attempts:
+                with self.engine.begin() as c:
+                    c.execute(
+                        sa.delete(SystemSchema.workflow_queue).where(
+                            SystemSchema.workflow_queue.c.workflow_uuid
+                            == status["workflow_uuid"]
                         )
-                        c.execute(
-                            sa.update(SystemSchema.workflow_status)
-                            .where(
-                                SystemSchema.workflow_status.c.workflow_uuid
-                                == status["workflow_uuid"]
-                            )
-                            .where(
-                                SystemSchema.workflow_status.c.status
-                                == WorkflowStatusString.PENDING.value
-                            )
-                            .values(
-                                status=WorkflowStatusString.RETRIES_EXCEEDED.value,
-                                queue_name=None,
-                            )
+                    )
+                    c.execute(
+                        sa.update(SystemSchema.workflow_status)
+                        .where(
+                            SystemSchema.workflow_status.c.workflow_uuid
+                            == status["workflow_uuid"]
+                        )
+                        .where(
+                            SystemSchema.workflow_status.c.status
+                            == WorkflowStatusString.PENDING.value
+                        )
+                        .values(
+                            status=WorkflowStatusString.RETRIES_EXCEEDED.value,
+                            queue_name=None,
                         )
-                    raise DBOSDeadLetterQueueError(
-                        status["workflow_uuid"], max_recovery_attempts
                     )
+                raise DBOSDeadLetterQueueError(
+                    status["workflow_uuid"], max_recovery_attempts
+                )
 
         # Record we have exported status for this single-transaction workflow
         if status["workflow_uuid"] in self._temp_txn_wf_ids:
@@ -356,7 +379,7 @@ class SystemDatabase:
                 stmt = (
                     sa.update(SystemSchema.workflow_status)
                     .where(
-                        SystemSchema.workflow_inputs.c.workflow_uuid == workflow_uuid
+                        SystemSchema.workflow_status.c.workflow_uuid == workflow_uuid
                     )
                     .values(recovery_attempts=reset_recovery_attempts)
                 )
@@ -538,18 +561,27 @@ class SystemDatabase:
                 workflow_uuid=workflow_uuid,
                 inputs=inputs,
             )
-            .on_conflict_do_nothing()
+            .on_conflict_do_update(
+                index_elements=["workflow_uuid"],
+                set_=dict(workflow_uuid=SystemSchema.workflow_inputs.c.workflow_uuid),
+            )
+            .returning(SystemSchema.workflow_inputs.c.inputs)
         )
         if conn is not None:
-            conn.execute(cmd)
+            row = conn.execute(cmd).fetchone()
         else:
             with self.engine.begin() as c:
-                c.execute(cmd)
-
+                row = c.execute(cmd).fetchone()
+        if row is not None and row[0] != inputs:
+            dbos_logger.warning(
+                f"Workflow inputs for {workflow_uuid} changed since the first call! Use the original inputs."
+            )
+            # TODO: actually changing the input
         if workflow_uuid in self._temp_txn_wf_ids:
             # Clean up the single-transaction tracking sets
             self._exported_temp_txn_wf_status.discard(workflow_uuid)
             self._temp_txn_wf_ids.discard(workflow_uuid)
+        return
 
     def get_workflow_inputs(
         self, workflow_uuid: str
@@ -582,12 +614,12 @@ class SystemDatabase:
         if input.start_time:
             query = query.where(
                 SystemSchema.workflow_status.c.created_at
-                >= datetime.datetime.fromisoformat(input.start_time).timestamp()
+                >= datetime.datetime.fromisoformat(input.start_time).timestamp() * 1000
             )
         if input.end_time:
             query = query.where(
                 SystemSchema.workflow_status.c.created_at
-                <= datetime.datetime.fromisoformat(input.end_time).timestamp()
+                <= datetime.datetime.fromisoformat(input.end_time).timestamp() * 1000
             )
         if input.status:
             query = query.where(SystemSchema.workflow_status.c.status == input.status)

dbos/_workflow_commands.py

@@ -0,0 +1,171 @@
+import importlib
+import os
+import sys
+from typing import Any, List, Optional, cast
+
+import typer
+from rich import print
+
+from dbos import DBOS
+
+from . import _serialization, load_config
+from ._core import execute_workflow_by_id
+from ._dbos_config import ConfigFile, _is_valid_app_name
+from ._sys_db import (
+    GetWorkflowsInput,
+    GetWorkflowsOutput,
+    SystemDatabase,
+    WorkflowStatuses,
+    WorkflowStatusInternal,
+    WorkflowStatusString,
+)
+
+
+class WorkflowInformation:
+    workflowUUID: str
+    status: WorkflowStatuses
+    workflowName: str
+    workflowClassName: Optional[str]
+    workflowConfigName: Optional[str]
+    input: Optional[_serialization.WorkflowInputs]  # JSON (jsonpickle)
+    output: Optional[str]  # JSON (jsonpickle)
+    error: Optional[str]  # JSON (jsonpickle)
+    executor_id: Optional[str]
+    app_version: Optional[str]
+    app_id: Optional[str]
+    request: Optional[str]  # JSON (jsonpickle)
+    recovery_attempts: Optional[int]
+    authenticated_user: Optional[str]
+    assumed_role: Optional[str]
+    authenticated_roles: Optional[str]  # JSON list of roles.
+    queue_name: Optional[str]
+
+
+def _list_workflows(
+    config: ConfigFile,
+    li: int,
+    user: Optional[str],
+    starttime: Optional[str],
+    endtime: Optional[str],
+    status: Optional[str],
+    request: bool,
+    appversion: Optional[str],
+) -> List[WorkflowInformation]:
+
+    sys_db = None
+
+    try:
+        sys_db = SystemDatabase(config)
+
+        input = GetWorkflowsInput()
+        input.authenticated_user = user
+        input.start_time = starttime
+        input.end_time = endtime
+        if status is not None:
+            input.status = cast(WorkflowStatuses, status)
+        input.application_version = appversion
+        input.limit = li
+
+        output: GetWorkflowsOutput = sys_db.get_workflows(input)
+
+        infos: List[WorkflowInformation] = []
+
+        if output.workflow_uuids is None:
+            typer.echo("No workflows found")
+            return {}
+
+        for workflow_id in output.workflow_uuids:
+            info = _get_workflow_info(
+                sys_db, workflow_id, request
+            )  # Call the method for each ID
+
+            if info is not None:
+                infos.append(info)
+
+        return infos
+    except Exception as e:
+        typer.echo(f"Error listing workflows: {e}")
+        return []
+    finally:
+        if sys_db:
+            sys_db.destroy()
+
+
+def _get_workflow(
+    config: ConfigFile, uuid: str, request: bool
+) -> Optional[WorkflowInformation]:
+    sys_db = None
+
+    try:
+        sys_db = SystemDatabase(config)
+
+        info = _get_workflow_info(sys_db, uuid, request)
+        return info
+
+    except Exception as e:
+        typer.echo(f"Error getting workflow: {e}")
+        return None
+    finally:
+        if sys_db:
+            sys_db.destroy()
+
+
+def _cancel_workflow(config: ConfigFile, uuid: str) -> None:
+    # config = load_config()
+    sys_db = None
+
+    try:
+        sys_db = SystemDatabase(config)
+        sys_db.set_workflow_status(uuid, WorkflowStatusString.CANCELLED, False)
+        return
+
+    except Exception as e:
+        typer.echo(f"Failed to connect to DBOS system database: {e}")
+        return None
+    finally:
+        if sys_db:
+            sys_db.destroy()
+
+
+def _get_workflow_info(
+    sys_db: SystemDatabase, workflowUUID: str, getRequest: bool
+) -> Optional[WorkflowInformation]:
+
+    info = sys_db.get_workflow_status(workflowUUID)
+    if info is None:
+        return None
+
+    winfo = WorkflowInformation()
+
+    winfo.workflowUUID = workflowUUID
+    winfo.status = info["status"]
+    winfo.workflowName = info["name"]
+    winfo.workflowClassName = info["class_name"]
+    winfo.workflowConfigName = info["config_name"]
+    winfo.executor_id = info["executor_id"]
+    winfo.app_version = info["app_version"]
+    winfo.app_id = info["app_id"]
+    winfo.recovery_attempts = info["recovery_attempts"]
+    winfo.authenticated_user = info["authenticated_user"]
+    winfo.assumed_role = info["assumed_role"]
+    winfo.authenticated_roles = info["authenticated_roles"]
+    winfo.queue_name = info["queue_name"]
+
+    # no input field
+    input_data = sys_db.get_workflow_inputs(workflowUUID)
+    if input_data is not None:
+        winfo.input = input_data
+
+    if info.get("status") == "SUCCESS":
+        result = sys_db.await_workflow_result(workflowUUID)
+        winfo.output = result
+    elif info.get("status") == "ERROR":
+        try:
+            sys_db.await_workflow_result(workflowUUID)
+        except Exception as e:
+            winfo.error = str(e)
+
+    if not getRequest:
+        winfo.request = None
+
+    return winfo

dbos/cli.py

@@ -8,6 +8,8 @@ import typing
 from os import path
 from typing import Any
 
+import jsonpickle  # type: ignore
+import requests
 import sqlalchemy as sa
 import tomlkit
 import typer
@@ -17,12 +19,16 @@ from typing_extensions import Annotated
 
 from dbos._schemas.system_database import SystemSchema
 
-from . import load_config
+from . import _serialization, load_config
 from ._app_db import ApplicationDatabase
 from ._dbos_config import _is_valid_app_name
 from ._sys_db import SystemDatabase
+from ._workflow_commands import _cancel_workflow, _get_workflow, _list_workflows
 
 app = typer.Typer()
+workflow = typer.Typer()
+
+app.add_typer(workflow, name="workflow", help="Manage DBOS workflows")
 
 
 def _on_windows() -> bool:
@@ -333,5 +339,138 @@ def reset(
             sys_db.destroy()
 
 
+@workflow.command(help="List workflows for your application")
+def list(
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Limit the results returned"),
+    ] = 10,
+    user: Annotated[
+        typing.Optional[str],
+        typer.Option("--user", "-u", help="Retrieve workflows run by this user"),
+    ] = None,
+    starttime: Annotated[
+        typing.Optional[str],
+        typer.Option(
+            "--start-time",
+            "-s",
+            help="Retrieve workflows starting after this timestamp (ISO 8601 format)",
+        ),
+    ] = None,
+    endtime: Annotated[
+        typing.Optional[str],
+        typer.Option(
+            "--end-time",
+            "-e",
+            help="Retrieve workflows starting before this timestamp (ISO 8601 format)",
+        ),
+    ] = None,
+    status: Annotated[
+        typing.Optional[str],
+        typer.Option(
+            "--status",
+            "-S",
+            help="Retrieve workflows with this status (PENDING, SUCCESS, ERROR, RETRIES_EXCEEDED, ENQUEUED, or CANCELLED)",
+        ),
+    ] = None,
+    appversion: Annotated[
+        typing.Optional[str],
+        typer.Option(
+            "--application-version",
+            "-v",
+            help="Retrieve workflows with this application version",
+        ),
+    ] = None,
+    request: Annotated[
+        bool,
+        typer.Option("--request", help="Retrieve workflow request information"),
+    ] = True,
+    appdir: Annotated[
+        typing.Optional[str],
+        typer.Option("--app-dir", "-d", help="Specify the application root directory"),
+    ] = None,
+) -> None:
+    config = load_config()
+    workflows = _list_workflows(
+        config, limit, user, starttime, endtime, status, request, appversion
+    )
+    print(jsonpickle.encode(workflows, unpicklable=False))
+
+
+@workflow.command(help="Retrieve the status of a workflow")
+def get(
+    uuid: Annotated[str, typer.Argument()],
+    appdir: Annotated[
+        typing.Optional[str],
+        typer.Option("--app-dir", "-d", help="Specify the application root directory"),
+    ] = None,
+    request: Annotated[
+        bool,
+        typer.Option("--request", help="Retrieve workflow request information"),
+    ] = True,
+) -> None:
+    config = load_config()
+    print(jsonpickle.encode(_get_workflow(config, uuid, request), unpicklable=False))
+
+
+@workflow.command(
+    help="Cancel a workflow so it is no longer automatically retried or restarted"
+)
+def cancel(
+    uuid: Annotated[str, typer.Argument()],
+    appdir: Annotated[
+        typing.Optional[str],
+        typer.Option("--app-dir", "-d", help="Specify the application root directory"),
+    ] = None,
+) -> None:
+    config = load_config()
+    _cancel_workflow(config, uuid)
+    print(f"Workflow {uuid} has been cancelled")
+
+
+@workflow.command(help="Resume a workflow that has been cancelled")
+def resume(
+    uuid: Annotated[str, typer.Argument()],
+    host: Annotated[
+        typing.Optional[str],
+        typer.Option("--host", "-h", help="Specify the admin host"),
+    ] = "localhost",
+    port: Annotated[
+        typing.Optional[int],
+        typer.Option("--port", "-p", help="Specify the admin port"),
+    ] = 3001,
+) -> None:
+    response = requests.post(
+        f"http://{host}:{port}/workflows/{uuid}/resume", json=[], timeout=5
+    )
+
+    if response.status_code == 200:
+        print(f"Workflow {uuid} has been resumed")
+    else:
+        print(f"Failed to resume workflow {uuid}. Status code: {response.status_code}")
+
+
+@workflow.command(help="Restart a workflow from the beginning with a new id")
+def restart(
+    uuid: Annotated[str, typer.Argument()],
+    host: Annotated[
+        typing.Optional[str],
+        typer.Option("--host", "-h", help="Specify the admin host"),
+    ] = "localhost",
+    port: Annotated[
+        typing.Optional[int],
+        typer.Option("--port", "-p", help="Specify the admin port"),
+    ] = 3001,
+) -> None:
+    response = requests.post(
+        f"http://{host}:{port}/workflows/{uuid}/restart", json=[], timeout=5
+    )
+
+    if response.status_code == 200:
+        print(f"Workflow {uuid} has been restarted")
+    else:
+        print(f"Failed to resume workflow {uuid}. Status code: {response.status_code}")
+
+
 if __name__ == "__main__":
     app()

{dbos-0.19.0a4.dist-info → dbos-0.20.0a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dbos
-Version: 0.19.0a4
+Version: 0.20.0a2
 Summary: Ultra-lightweight durable execution in Python
 Author-Email: "DBOS, Inc." <contact@dbos.dev>
 License: MIT
@@ -28,14 +28,14 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-# DBOS Transact: Ultra-Lightweight Durable Execution
+# DBOS Transact: A Lightweight Durable Execution Library Built on Postgres
 
 #### [Documentation](https://docs.dbos.dev/) &nbsp;&nbsp;•&nbsp;&nbsp;  [Examples](https://docs.dbos.dev/examples) &nbsp;&nbsp;•&nbsp;&nbsp; [Github](https://github.com/dbos-inc) &nbsp;&nbsp;•&nbsp;&nbsp; [Discord](https://discord.com/invite/jsmC6pXGgX)
 </div>
 
 ---
 
-DBOS Transact is a Python library providing **ultra-lightweight durable execution**.
+DBOS Transact is a Python library for **ultra-lightweight durable execution**.
 For example:
 
 ```python
@@ -55,18 +55,23 @@ def workflow()
 
 Durable execution means your program is **resilient to any failure**.
 If it is ever interrupted or crashes, all your workflows will automatically resume from the last completed step.
-If you want to see durable execution in action, check out [this demo app](https://demo-widget-store.cloud.dbos.dev/) (source code [here](https://github.com/dbos-inc/dbos-demo-apps/tree/main/python/widget-store)).
-No matter how many times you try to crash it, it always resumes from exactly where it left off!
+Durable execution helps solve many common problems:
 
-Under the hood, DBOS Transact works by storing your program's execution state (which workflows are currently executing and which steps they've completed) in a Postgres database.
-So all you need to use it is a Postgres database to connect to&mdash;there's no need for a "workflow server."
-This approach is also incredibly fast, for example [25x faster than AWS Step Functions](https://www.dbos.dev/blog/dbos-vs-aws-step-functions-benchmark).
+- Orchestrating long-running or business-critical workflows so they seamlessly recover from any failure.
+- Running reliable background jobs with no timeouts.
+- Processing incoming events (e.g. from Kafka) exactly once.
+- Running a fault-tolerant distributed task queue.
+- Running a reliable cron scheduler.
+- Operating an AI agent, or anything that connects to an unreliable or non-deterministic API.
 
-Some more cool features include:
+What’s unique about DBOS's implementation of durable execution is that it’s implemented in a **lightweight library** that’s **totally backed by Postgres**.
+To use DBOS, just `pip install` it and annotate your program with DBOS decorators.
+Under the hood, those decorators store your program's execution state (which workflows are currently executing and which steps they've completed) in a Postgres database.
+If your program crashes or is interrupted, they automatically recover its workflows from their stored state.
+So all you need to use DBOS is Postgres&mdash;there are no other dependencies you have to manage, no separate workflow server.
 
-- Scheduled jobs&mdash;run your workflows exactly-once per time interval.
-- Exactly-once event processing&mdash;use workflows to process incoming events (for example, from a Kafka topic) exactly-once.
-- Observability&mdash;all workflows automatically emit [OpenTelemetry](https://opentelemetry.io/) traces.
+One big advantage of this approach is that you can add DBOS to **any** Python application&mdash;**it’s just a library**.
+You can use DBOS to add reliable background jobs or cron scheduling or queues to your app with no external dependencies except Postgres.
 
 ## Getting Started
 
@@ -77,7 +82,7 @@ pip install dbos
 dbos init --config
 ```
 
-Then, try it out with this simple program (requires Postgres):
+Then, try it out with this simple program:
 
 ```python
 from fastapi import FastAPI
@@ -107,14 +112,14 @@ def fastapi_endpoint():
     dbos_workflow()
 ```
 
-Save the program into `main.py`, edit `dbos-config.yaml` to configure your Postgres connection settings, and start it with `fastapi run`.
+Save the program into `main.py` and start it with `fastapi run`.
 Visit `localhost:8000` in your browser to start the workflow.
 When prompted, press `Control + \` to force quit your application.
 It should crash midway through the workflow, having completed step one but not step two.
 Then, restart your app with `fastapi run`.
 It should resume the workflow from where it left off, completing step two without re-executing step one.
 
-To learn how to build more complex workflows, see our [programming guide](https://docs.dbos.dev/python/programming-guide) or [examples](https://docs.dbos.dev/examples).
+To learn how to build more complex workflows, see the [programming guide](https://docs.dbos.dev/python/programming-guide) or [examples](https://docs.dbos.dev/examples).
 
 ## Documentation
 
@@ -125,7 +130,7 @@ To learn how to build more complex workflows, see our [programming guide](https:
 
 - [**AI-Powered Slackbot**](https://docs.dbos.dev/python/examples/rag-slackbot) &mdash; A Slackbot that answers questions about previous Slack conversations, using DBOS to durably orchestrate its RAG pipeline.
 - [**Widget Store**](https://docs.dbos.dev/python/examples/widget-store) &mdash; An online storefront that uses DBOS durable workflows to be resilient to any failure.
-- [**Earthquake Tracker**](https://docs.dbos.dev/python/examples/earthquake-tracker) &mdash; A real-time earthquake dashboard that uses DBOS to stream data from the USGS into Postgres, then visualizes it with Streamlit.
+- [**Scheduled Reminders**](https://docs.dbos.dev/python/examples/scheduled-reminders) &mdash; In just three lines of code, schedule an email to send days, weeks, or months in the future.
 
 More examples [here](https://docs.dbos.dev/examples)!
 

{dbos-0.19.0a4.dist-info → dbos-0.20.0a2.dist-info}/RECORD

@@ -1,24 +1,24 @@
-dbos-0.19.0a4.dist-info/METADATA,sha256=NOwdv7iSopa_WvJkvQ3-AJ-peRmVMFW3E5D7SfxERqI,5144
-dbos-0.19.0a4.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-dbos-0.19.0a4.dist-info/entry_points.txt,sha256=z6GcVANQV7Uw_82H9Ob2axJX6V3imftyZsljdh-M1HU,54
-dbos-0.19.0a4.dist-info/licenses/LICENSE,sha256=VGZit_a5-kdw9WT6fY5jxAWVwGQzgLFyPWrcVVUhVNU,1067
+dbos-0.20.0a2.dist-info/METADATA,sha256=HuHOltiSuDZN-RYCA22G-kTSVYlfK9bksxlPiAamZuo,5309
+dbos-0.20.0a2.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+dbos-0.20.0a2.dist-info/entry_points.txt,sha256=z6GcVANQV7Uw_82H9Ob2axJX6V3imftyZsljdh-M1HU,54
+dbos-0.20.0a2.dist-info/licenses/LICENSE,sha256=VGZit_a5-kdw9WT6fY5jxAWVwGQzgLFyPWrcVVUhVNU,1067
 dbos/__init__.py,sha256=CxRHBHEthPL4PZoLbZhp3rdm44-KkRTT2-7DkK9d4QQ,724
-dbos/_admin_server.py,sha256=DOgzVp9kmwiebQqmJB1LcrZnGTxSMbZiGXdenc1wZDg,3163
+dbos/_admin_server.py,sha256=PJgneZG9-64TapZrPeJtt73puAswRImCE5uce2k2PKU,4750
 dbos/_app_db.py,sha256=_tv2vmPjjiaikwgxH3mqxgJ4nUUcG2-0uMXKWCqVu1c,5509
 dbos/_classproperty.py,sha256=f0X-_BySzn3yFDRKB2JpCbLYQ9tLwt1XftfshvY7CBs,626
 dbos/_cloudutils/authentication.py,sha256=V0fCWQN9stCkhbuuxgPTGpvuQcDqfU3KAxPAh01vKW4,5007
 dbos/_cloudutils/cloudutils.py,sha256=5e3CW1deSW-dI5G3QN0XbiVsBhyqT8wu7fuV2f8wtGU,7688
 dbos/_cloudutils/databases.py,sha256=x4187Djsyoa-QaG3Kog8JT2_GERsnqa93LIVanmVUmg,8393
-dbos/_context.py,sha256=KV3fd3-Rv6EWrYDUdHARxltSlNZGNtQtNSqeQ-gkXE8,18049
-dbos/_core.py,sha256=dbG8573iSzB_WITWOh6yOV-w32BM8UbJcOB4Fr0e-lw,34456
+dbos/_context.py,sha256=RH08s_nee95vgxdz6AsYuVWF1LuJSVtOyIifblsa4pw,18760
+dbos/_core.py,sha256=dmVve1YZyQmAfwKsxqz6N3bXBowsMBmLxBDsymoWKsA,35956
 dbos/_croniter.py,sha256=hbhgfsHBqclUS8VeLnJ9PSE9Z54z6mi4nnrr1aUXn0k,47561
 dbos/_db_wizard.py,sha256=xgKLna0_6Xi50F3o8msRosXba8NScHlpJR5ICVCkHDQ,7534
-dbos/_dbos.py,sha256=LWFa48CPt7bsNAnMZrNDzHHTFCyMrY-nKbMZwCG_dqY,34710
+dbos/_dbos.py,sha256=Kgnity6JxjThIf1L8CQbeobQMiJqUUeWlRf36_eGu2g,35385
 dbos/_dbos_config.py,sha256=h_q1gzudhsAMVkGMD0qQ6kLic6YhdJgzm50YFSIx9Bo,8196
-dbos/_error.py,sha256=UETk8CoZL-TO2Utn1-E7OSWelhShWmKM-fOlODMR9PE,3893
-dbos/_fastapi.py,sha256=iyefCZq-ZDKRUjN_rgYQmFmyvWf4gPrSlC6CLbfq4a8,3419
-dbos/_flask.py,sha256=z1cijbTi5Dpq6kqikPCx1LcR2YHHv2oc41NehOWjw74,2431
-dbos/_kafka.py,sha256=OmOKfO7_3Z2FUFv_sJaIfebd7xnqtuRRndzNTTufgb8,3654
+dbos/_error.py,sha256=vtaSsG0QW6cRlwfZ4zzZWy_IHCZlomwSlrDyGWuyn8c,4337
+dbos/_fastapi.py,sha256=yRHrCwul2iYBxAAYuBQLcn9LMYUS6PE4CU9y1vUSPR8,3587
+dbos/_flask.py,sha256=DZKUZR5-xOzPI7tYZ53r2PvvHVoAb8SYwLzMVFsVfjI,2608
+dbos/_kafka.py,sha256=o6DbwnsYRDtvVTZVsN7BAK8cdP79AfoWX3Q7CGY2Yuo,4199
 dbos/_kafka_message.py,sha256=NYvOXNG3Qn7bghn1pv3fg4Pbs86ILZGcK4IB-MLUNu0,409
 dbos/_logger.py,sha256=iYwbA7DLyXalWa2Yu07HO6Xm301nRuenMU64GgwUMkU,3576
 dbos/_migrations/env.py,sha256=38SIGVbmn_VV2x2u1aHLcPOoWgZ84eCymf3g_NljmbU,1626
@@ -31,7 +31,7 @@ dbos/_migrations/versions/d76646551a6b_job_queue_limiter.py,sha256=8PyFi8rd6CN-m
 dbos/_migrations/versions/d76646551a6c_workflow_queue.py,sha256=G942nophZ2uC2vc4hGBC02Ptng1715roTjY3xiyzZU4,729
 dbos/_migrations/versions/eab0cc1d9a14_job_queue.py,sha256=uvhFOtqbBreCePhAxZfIT0qCAI7BiZTou9wt6QnbY7c,1412
 dbos/_outcome.py,sha256=FDMgWVjZ06vm9xO-38H17mTqBImUYQxgKs_bDCSIAhE,6648
-dbos/_queue.py,sha256=VSaF-BTv2tm-44O_690omo0pE31NQAhOT3ARL4VLRzY,2723
+dbos/_queue.py,sha256=o_aczwualJTMoXb0XXL-Y5QH77OEukWzuerogbWi2ho,2779
 dbos/_recovery.py,sha256=jbzGYxICA2drzyzlBSy2UiXhKV_16tBVacKQdTkqf-w,2008
 dbos/_registrations.py,sha256=mei6q6_3R5uei8i_Wo_TqGZs85s10shOekDX41sFYD0,6642
 dbos/_request.py,sha256=cX1B3Atlh160phgS35gF1VEEV4pD126c9F3BDgBmxZU,929
@@ -41,7 +41,7 @@ dbos/_schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dbos/_schemas/application_database.py,sha256=KeyoPrF7hy_ODXV7QNike_VFSD74QBRfQ76D7QyE9HI,966
 dbos/_schemas/system_database.py,sha256=rwp4EvCSaXcUoMaRczZCvETCxGp72k3-hvLyGUDkih0,5163
 dbos/_serialization.py,sha256=YCYv0qKAwAZ1djZisBC7khvKqG-5OcIv9t9EC5PFIog,1743
-dbos/_sys_db.py,sha256=2W3ta0Q-isESMjyGbXCPfaoll-vyPQg1innBEeNfg2c,50088
+dbos/_sys_db.py,sha256=ha5E11P83oi78L4R7cX_OL_N1Tf2Ir0Xr30GK1_27SA,52290
 dbos/_templates/hello/README.md,sha256=GhxhBj42wjTt1fWEtwNriHbJuKb66Vzu89G4pxNHw2g,930
 dbos/_templates/hello/__package/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dbos/_templates/hello/__package/main.py,sha256=eI0SS9Nwj-fldtiuSzIlIG6dC91GXXwdRsoHxv6S_WI,2719
@@ -53,8 +53,9 @@ dbos/_templates/hello/migrations/script.py.mako,sha256=MEqL-2qATlST9TAOeYgscMn1u
 dbos/_templates/hello/migrations/versions/2024_07_31_180642_init.py,sha256=U5thFWGqNN4QLrNXT7wUUqftIFDNE5eSdqD8JNW1mec,942
 dbos/_templates/hello/start_postgres_docker.py,sha256=lQVLlYO5YkhGPEgPqwGc7Y8uDKse9HsWv5fynJEFJHM,1681
 dbos/_tracer.py,sha256=rvBY1RQU6DO7rL7EnaJJxGcmd4tP_PpGqUEE6imZnhY,2518
-dbos/cli.py,sha256=em1uAxrp5yyg53V7ZpmHFtqD6OJp2cMJkG9vGJPoFTA,10904
+dbos/_workflow_commands.py,sha256=tj-gJARjDJ5aYo0ii2udTAU4l36vbeXwmOYh8Q4y_ac,4625
+dbos/cli.py,sha256=26fowBwpV-U7kuPdGRnAcuUMJIqYvstMX9qJ0t-B6BI,15354
 dbos/dbos-config.schema.json,sha256=X5TpXNcARGceX0zQs0fVgtZW_Xj9uBbY5afPt9Rz9yk,5741
 dbos/py.typed,sha256=QfzXT1Ktfk3Rj84akygc7_42z0lRpCq0Ilh8OXI6Zas,44
 version/__init__.py,sha256=L4sNxecRuqdtSFdpUGX3TtBi9KL3k7YsZVIvv-fv9-A,1678
-dbos-0.19.0a4.dist-info/RECORD,,
+dbos-0.20.0a2.dist-info/RECORD,,