dbos 0.5.0a11__tar.gz → 0.6.0a0__tar.gz

dbos-0.6.0a0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: dbos
+Version: 0.6.0a0
+Summary: Ultra-lightweight durable execution in Python
+Author-Email: "DBOS, Inc." <contact@dbos.dev>
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: alembic>=1.13.2
+Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: typing-extensions>=4.12.2; python_version < "3.10"
+Requires-Dist: typer>=0.12.3
+Requires-Dist: jsonpickle>=3.2.2
+Requires-Dist: opentelemetry-api>=1.26.0
+Requires-Dist: opentelemetry-sdk>=1.26.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.26.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: fastapi[standard]>=0.112.1
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: tomlkit>=0.13.2
+Description-Content-Type: text/markdown
+
+## 🚀 DBOS Transact - Ultra-Lightweight Durable Execution in Python 🚀
+
+---
+
+📚 **Documentation**: Under Construction 🚧
+
+💬 **Join the Discussion**: [Discord Community](https://discord.gg/fMwQjeW5zg)
+
+---
+
+
+**DBOS Python is under construction! 🚧🚧🚧 Check back regularly for updates, release coming in mid-September!**
+
+DBOS Transact is a **Python library** providing ultra-lightweight durable execution.
+For example:
+
+```python
+@DBOS.step()
+def step_one():
+    ...
+
+@DBOS.step()
+def step_two():
+    ...
+
+@DBOS.workflow()
+def workflow()
+    step_one()
+    step_two()
+```
+
+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!
+
+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).
+
+Some more cool features include:
+
+- 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.
+
+## Getting Started
+
+To try out the latest pre-release version, install and configure with:
+
+```shell
+pip install --pre dbos
+dbos init --config
+```
+
+Try it out with this simple program (requires Postgres):
+
+```python
+from fastapi import FastAPI
+from dbos import DBOS
+
+app = FastAPI()
+DBOS(fastapi=app)
+
+@DBOS.step()
+def step_one():
+    print("Step one completed!")
+
+@DBOS.step()
+def step_two():
+    print("Step two completed!")
+
+@DBOS.workflow()
+def workflow():
+    step_one()
+    for _ in range(5):
+        print("Press Control + \ to stop the app...")
+        DBOS.sleep(1)
+    step_two()
+
+@app.get("/")
+def endpoint():
+    workflow()
+```
+
+Save the program into `main.py`, tell it your local Postgres password via `export PGPASSWORD=<your password>` and start it with `fastapi run`.
+Visit `localhost:8000` in your browser (or curl it) 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 examples, see our programming guide (coming soon).
+
+## Documentation
+
+Coming soon! 🚧
+
+## Examples
+
+Check out some cool demo apps here: [https://github.com/dbos-inc/dbos-demo-apps/tree/main/python](https://github.com/dbos-inc/dbos-demo-apps/tree/main/python)
+
+## Community
+
+If you're interested in building with us, please star our repository and join our community on [Discord](https://discord.gg/fMwQjeW5zg)!
+If you see a bug or have a feature request, don't hesitate to open an issue here on GitHub.
+If you're interested in contributing, check out our [contributions guide](./CONTRIBUTING.md).

dbos-0.6.0a0/README.md

@@ -0,0 +1,107 @@
+## 🚀 DBOS Transact - Ultra-Lightweight Durable Execution in Python 🚀
+
+---
+
+📚 **Documentation**: Under Construction 🚧
+
+💬 **Join the Discussion**: [Discord Community](https://discord.gg/fMwQjeW5zg)
+
+---
+
+
+**DBOS Python is under construction! 🚧🚧🚧 Check back regularly for updates, release coming in mid-September!**
+
+DBOS Transact is a **Python library** providing ultra-lightweight durable execution.
+For example:
+
+```python
+@DBOS.step()
+def step_one():
+    ...
+
+@DBOS.step()
+def step_two():
+    ...
+
+@DBOS.workflow()
+def workflow()
+    step_one()
+    step_two()
+```
+
+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!
+
+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—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).
+
+Some more cool features include:
+
+- Scheduled jobs—run your workflows exactly-once per time interval.
+- Exactly-once event processing—use workflows to process incoming events (for example, from a Kafka topic) exactly-once.
+- Observability—all workflows automatically emit [OpenTelemetry](https://opentelemetry.io/) traces.
+
+## Getting Started
+
+To try out the latest pre-release version, install and configure with:
+
+```shell
+pip install --pre dbos
+dbos init --config
+```
+
+Try it out with this simple program (requires Postgres):
+
+```python
+from fastapi import FastAPI
+from dbos import DBOS
+
+app = FastAPI()
+DBOS(fastapi=app)
+
+@DBOS.step()
+def step_one():
+    print("Step one completed!")
+
+@DBOS.step()
+def step_two():
+    print("Step two completed!")
+
+@DBOS.workflow()
+def workflow():
+    step_one()
+    for _ in range(5):
+        print("Press Control + \ to stop the app...")
+        DBOS.sleep(1)
+    step_two()
+
+@app.get("/")
+def endpoint():
+    workflow()
+```
+
+Save the program into `main.py`, tell it your local Postgres password via `export PGPASSWORD=<your password>` and start it with `fastapi run`.
+Visit `localhost:8000` in your browser (or curl it) 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 examples, see our programming guide (coming soon).
+
+## Documentation
+
+Coming soon! 🚧
+
+## Examples
+
+Check out some cool demo apps here: [https://github.com/dbos-inc/dbos-demo-apps/tree/main/python](https://github.com/dbos-inc/dbos-demo-apps/tree/main/python)
+
+## Community
+
+If you're interested in building with us, please star our repository and join our community on [Discord](https://discord.gg/fMwQjeW5zg)!
+If you see a bug or have a feature request, don't hesitate to open an issue here on GitHub.
+If you're interested in contributing, check out our [contributions guide](./CONTRIBUTING.md).

dbos-0.6.0a0/dbos/__init__.py

@@ -0,0 +1,20 @@
+from . import error as error
+from .context import DBOSContextEnsure, SetWorkflowID
+from .dbos import DBOS, DBOSConfiguredInstance, WorkflowHandle, WorkflowStatus
+from .dbos_config import ConfigFile, get_dbos_database_url, load_config
+from .system_database import GetWorkflowsInput, WorkflowStatusString
+
+__all__ = [
+    "ConfigFile",
+    "DBOS",
+    "DBOSConfiguredInstance",
+    "DBOSContextEnsure",
+    "GetWorkflowsInput",
+    "SetWorkflowID",
+    "WorkflowHandle",
+    "WorkflowStatus",
+    "WorkflowStatusString",
+    "load_config",
+    "get_dbos_database_url",
+    "error",
+]

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/admin_sever.py

@@ -28,11 +28,11 @@ class AdminServer:
         self.server_thread = threading.Thread(target=self.server.serve_forever)
         self.server_thread.daemon = True
 
-        dbos_logger.info("Starting DBOS admin server on port %d", self.port)
+        dbos_logger.debug("Starting DBOS admin server on port %d", self.port)
         self.server_thread.start()
 
     def stop(self) -> None:
-        dbos_logger.info("Stopping DBOS admin server")
+        dbos_logger.debug("Stopping DBOS admin server")
         self.server.shutdown()
         self.server.server_close()
         self.server_thread.join()

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/cli.py

@@ -119,7 +119,7 @@ def copy_template_dir(src_dir: str, dst_dir: str, ctx: dict[str, str]) -> None:
                 shutil.copy(src, dst)
 
 
-def copy_template(src_dir: str, project_name: str) -> None:
+def copy_template(src_dir: str, project_name: str, config_mode: bool) -> None:
 
     dst_dir = path.abspath(".")
 
@@ -131,10 +131,17 @@ def copy_template(src_dir: str, project_name: str) -> None:
         "db_name": db_name,
     }
 
-    copy_template_dir(src_dir, dst_dir, ctx)
-    copy_template_dir(
-        path.join(src_dir, "__package"), path.join(dst_dir, package_name), ctx
-    )
+    if config_mode:
+        copy_dbos_template(
+            os.path.join(src_dir, "dbos-config.yaml.dbos"),
+            os.path.join(dst_dir, "dbos-config.yaml"),
+            ctx,
+        )
+    else:
+        copy_template_dir(src_dir, dst_dir, ctx)
+        copy_template_dir(
+            path.join(src_dir, "__package"), path.join(dst_dir, package_name), ctx
+        )
 
 
 def get_project_name() -> typing.Union[str, None]:
@@ -173,6 +180,10 @@ def init(
         typing.Optional[str],
         typer.Option("--template", "-t", help="Specify template to use"),
     ] = None,
+    config: Annotated[
+        bool,
+        typer.Option("--config", "-c", help="Only add dbos-config.yaml"),
+    ] = False,
 ) -> None:
     try:
         if project_name is None:
@@ -199,7 +210,9 @@ def init(
             if template not in templates:
                 raise Exception(f"template {template} not found in {templates_dir}")
 
-        copy_template(path.join(templates_dir, template), project_name)
+        copy_template(
+            path.join(templates_dir, template), project_name, config_mode=config
+        )
     except Exception as e:
         print(f"[red]{e}[/red]")
 

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/context.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 import uuid
 from contextvars import ContextVar
@@ -39,6 +40,9 @@ class TracedAttributes(TypedDict, total=False):
     applicationID: Optional[str]
     applicationVersion: Optional[str]
     executorID: Optional[str]
+    authenticatedUser: Optional[str]
+    authenticatedUserRoles: Optional[str]
+    authenticatedUserAssumedRole: Optional[str]
 
 
 class DBOSContext:
@@ -159,6 +163,13 @@ class DBOSContext:
         attributes["operationUUID"] = (
             self.workflow_id if len(self.workflow_id) > 0 else None
         )
+        attributes["authenticatedUser"] = self.authenticated_user
+        attributes["authenticatedUserRoles"] = (
+            json.dumps(self.authenticated_roles)
+            if self.authenticated_roles is not None
+            else ""
+        )
+        attributes["authenticatedUserAssumedRole"] = self.assumed_role
         span = dbos_tracer.start_span(
             attributes, parent=self.spans[-1] if len(self.spans) > 0 else None
         )
@@ -178,6 +189,11 @@ class DBOSContext:
     ) -> None:
         self.authenticated_user = user
         self.authenticated_roles = roles
+        if user is not None and len(self.spans) > 0:
+            self.spans[-1].set_attribute("authenticatedUser", user)
+            self.spans[-1].set_attribute(
+                "authenticatedUserRoles", json.dumps(roles) if roles is not None else ""
+            )
 
 
 ##############################################################
@@ -217,13 +233,13 @@ class DBOSContextEnsure:
     def __init__(self) -> None:
         self.created_ctx = False
 
-    def __enter__(self) -> DBOSContextEnsure:
+    def __enter__(self) -> DBOSContext:
         # Code to create a basic context
         ctx = get_local_dbos_context()
         if ctx is None:
             self.created_ctx = True
             set_local_dbos_context(DBOSContext())
-        return self
+        return assert_current_dbos_context()
 
     def __exit__(
         self,

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/core.py

@@ -1,9 +1,20 @@
+import json
 import sys
 import time
 import traceback
 from concurrent.futures import Future
 from functools import wraps
-from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, Tuple, TypeVar, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    List,
+    Optional,
+    Tuple,
+    TypeVar,
+    cast,
+)
 
 from dbos.application_database import ApplicationDatabase, TransactionResultInternal
 
@@ -134,6 +145,11 @@ def _init_workflow(
         "executor_id": ctx.executor_id,
         "request": (utils.serialize(ctx.request) if ctx.request is not None else None),
         "recovery_attempts": None,
+        "authenticated_user": ctx.authenticated_user,
+        "authenticated_roles": (
+            json.dumps(ctx.authenticated_roles) if ctx.authenticated_roles else None
+        ),
+        "assumed_role": ctx.assumed_role,
     }
 
     # If we have a class name, the first arg is the instance and do not serialize

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/dbos.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import atexit
+import json
 import os
 import sys
 import threading
@@ -19,6 +20,7 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
+    cast,
 )
 
 from opentelemetry.trace import Span
@@ -53,6 +55,7 @@ from .tracer import dbos_tracer
 if TYPE_CHECKING:
     from fastapi import FastAPI
     from .request import Request
+    from flask import Flask
 
 from sqlalchemy.orm import Session
 
@@ -205,6 +208,7 @@ class DBOS:
         *,
         config: Optional[ConfigFile] = None,
         fastapi: Optional["FastAPI"] = None,
+        flask: Optional["Flask"] = None,
     ) -> DBOS:
         global _dbos_global_instance
         global _dbos_global_registry
@@ -219,7 +223,7 @@ class DBOS:
                     )
                 config = _dbos_global_registry.config
             _dbos_global_instance = super().__new__(cls)
-            _dbos_global_instance.__init__(fastapi=fastapi, config=config)  # type: ignore
+            _dbos_global_instance.__init__(fastapi=fastapi, config=config, flask=flask)  # type: ignore
         else:
             if (config is not None and _dbos_global_instance.config is not config) or (
                 _dbos_global_instance.fastapi is not fastapi
@@ -243,6 +247,7 @@ class DBOS:
         *,
         config: Optional[ConfigFile] = None,
         fastapi: Optional["FastAPI"] = None,
+        flask: Optional["Flask"] = None,
     ) -> None:
         if hasattr(self, "_initialized") and self._initialized:
             return
@@ -264,14 +269,44 @@ class DBOS:
         self._admin_server: Optional[AdminServer] = None
         self.stop_events: List[threading.Event] = []
         self.fastapi: Optional["FastAPI"] = fastapi
+        self.flask: Optional["Flask"] = flask
         self._executor: Optional[ThreadPoolExecutor] = None
+
+        # If using FastAPI, set up middleware and lifecycle events
         if self.fastapi is not None:
+            from fastapi.requests import Request as FARequest
+            from fastapi.responses import JSONResponse
+
+            async def dbos_error_handler(
+                request: FARequest, gexc: Exception
+            ) -> JSONResponse:
+                exc: DBOSException = cast(DBOSException, gexc)
+                status_code = 500
+                if exc.status_code is not None:
+                    status_code = exc.status_code
+                return JSONResponse(
+                    status_code=status_code,
+                    content={
+                        "message": str(exc.message),
+                        "dbos_error_code": str(exc.dbos_error_code),
+                        "dbos_error": str(exc.__class__.__name__),
+                    },
+                )
+
+            self.fastapi.add_exception_handler(DBOSException, dbos_error_handler)
+
             from dbos.fastapi import setup_fastapi_middleware
 
             setup_fastapi_middleware(self.fastapi)
             self.fastapi.on_event("startup")(self._launch)
             self.fastapi.on_event("shutdown")(self._destroy)
 
+        # If using Flask, set up middleware
+        if self.flask is not None:
+            from dbos.flask import setup_flask_middleware
+
+            setup_flask_middleware(self.flask)
+
         # Register send_stub as a workflow
         def send_temp_workflow(
             destination_id: str, message: Any, topic: Optional[str]
@@ -502,9 +537,13 @@ class DBOS:
             recovery_attempts=stat["recovery_attempts"],
             class_name=stat["class_name"],
             config_name=stat["config_name"],
-            authenticated_user=None,
-            assumed_role=None,
-            authenticatedRoles=None,
+            authenticated_user=stat["authenticated_user"],
+            assumed_role=stat["assumed_role"],
+            authenticated_roles=(
+                json.loads(stat["authenticated_roles"])
+                if stat["authenticated_roles"] is not None
+                else None
+            ),
         )
 
     @classmethod
@@ -663,6 +702,27 @@ class DBOS:
         ctx = assert_current_dbos_context()
         return ctx.request
 
+    @classproperty
+    def authenticated_user(cls) -> Optional[str]:
+        """Return the current authenticated user, if any, associated with the current context."""
+        ctx = assert_current_dbos_context()
+        return ctx.authenticated_user
+
+    @classproperty
+    def authenticated_roles(cls) -> Optional[List[str]]:
+        """Return the roles granted to the current authenticated user, if any, associated with the current context."""
+        ctx = assert_current_dbos_context()
+        return ctx.authenticated_roles
+
+    @classmethod
+    def set_authentication(
+        cls, authenticated_user: Optional[str], authenticated_roles: Optional[List[str]]
+    ) -> None:
+        """Set the current authenticated user and granted roles into the current context."""
+        ctx = assert_current_dbos_context()
+        ctx.authenticated_user = authenticated_user
+        ctx.authenticated_roles = authenticated_roles
+
 
 @dataclass
 class WorkflowStatus:
@@ -679,7 +739,7 @@ class WorkflowStatus:
         config_name(str): For instance member functions, the name of the class instance for the execution
         authenticated_user(str): The user who invoked the workflow
         assumed_role(str): The access role used by the user to allow access to the workflow function
-        authenticatedRoles(List[str]): List of all access roles available to the authenticated user
+        authenticated_roles(List[str]): List of all access roles available to the authenticated user
         recovery_attempts(int): Number of times the workflow has been restarted (usually by recovery)
 
     """
@@ -691,7 +751,7 @@ class WorkflowStatus:
     config_name: Optional[str]
     authenticated_user: Optional[str]
     assumed_role: Optional[str]
-    authenticatedRoles: Optional[List[str]]
+    authenticated_roles: Optional[List[str]]
     recovery_attempts: Optional[int]
 
 

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/dbos_config.py

@@ -2,7 +2,7 @@ import json
 import os
 import re
 from importlib import resources
-from typing import Any, Dict, List, Optional, TypedDict
+from typing import Dict, List, Optional, TypedDict
 
 import yaml
 from jsonschema import ValidationError, validate

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/error.py

@@ -17,6 +17,7 @@ class DBOSException(Exception):
     def __init__(self, message: str, dbos_error_code: Optional[int] = None):
         self.message = message
         self.dbos_error_code = dbos_error_code
+        self.status_code: Optional[int] = None
         super().__init__(self.message)
 
     def __str__(self) -> str:
@@ -104,6 +105,7 @@ class DBOSNotAuthorizedError(DBOSException):
             msg,
             dbos_error_code=DBOSErrorCode.NotAuthorized.value,
         )
+        self.status_code = 403
 
 
 class DBOSMaxStepRetriesExceeded(DBOSException):

{dbos-0.5.0a11 → dbos-0.6.0a0}/dbos/fastapi.py

@@ -11,9 +11,7 @@ from .context import (
     TracedAttributes,
     assert_current_dbos_context,
 )
-from .request import Address, Request
-
-request_id_header = "x-request-id"
+from .request import Address, Request, request_id_header
 
 
 def get_or_generate_request_id(request: FastAPIRequest) -> str:

dbos-0.6.0a0/dbos/flask.py

@@ -0,0 +1,79 @@
+import uuid
+from typing import Any
+from urllib.parse import urlparse
+
+from flask import Flask, request
+from werkzeug.wrappers import Request as WRequest
+
+from dbos.context import (
+    EnterDBOSHandler,
+    OperationType,
+    SetWorkflowID,
+    TracedAttributes,
+    assert_current_dbos_context,
+)
+
+from .request import Address, Request, request_id_header
+
+
+class FlaskMiddleware:
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    def __call__(self, environ: Any, start_response: Any) -> Any:
+        request = WRequest(environ)
+        attributes: TracedAttributes = {
+            "name": urlparse(request.url).path,
+            "requestID": get_or_generate_request_id(request),
+            "requestIP": (
+                request.remote_addr if request.remote_addr is not None else None
+            ),
+            "requestURL": request.url,
+            "requestMethod": request.method,
+            "operationType": OperationType.HANDLER.value,
+        }
+        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):
+                response = self.app(environ, start_response)
+        return response
+
+
+def get_or_generate_request_id(request: WRequest) -> str:
+    request_id = request.headers.get(request_id_header, None)
+    if request_id is not None:
+        return request_id
+    else:
+        return str(uuid.uuid4())
+
+
+def make_request(request: WRequest) -> Request:
+    parsed_url = urlparse(request.url)
+    base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+
+    client = None
+    if request.remote_addr:
+        hostname = request.remote_addr
+        port = request.environ.get("REMOTE_PORT")
+        if port:
+            client = Address(hostname=hostname, port=int(port))
+        else:
+            # If port is not available, use 0 as a placeholder
+            client = Address(hostname=hostname, port=0)
+
+    return Request(
+        headers=dict(request.headers),
+        path_params={},
+        query_params=dict(request.args),
+        url=request.url,
+        base_url=base_url,
+        client=client,
+        cookies=dict(request.cookies),
+        method=request.method,
+    )
+
+
+def setup_flask_middleware(app: Flask) -> None:
+    app.wsgi_app = FlaskMiddleware(app.wsgi_app)  # type: ignore