fastbpmn 0.1.0__py3-none-any.whl

fastbpmn/__init__.py

@@ -0,0 +1,15 @@
+"""Top-level package for yio-minions."""
+
+import importlib.metadata
+from .fastbpmn import FastBPMN
+from .process import Process
+from .task import TaskHandler
+from .task_group import TaskGroup
+
+__version__ = importlib.metadata.version("fastbpmn")
+__author__ = """yio gmbh"""
+__email__ = "hello@yio.at"
+
+# Later we will include all types and definitions here that are really required to implement external tasks
+# to keep the interface probably as simple as possible.
+__all__ = ["FastBPMN", "Process", "TaskGroup", "TaskHandler"]

fastbpmn/aetpi/logonly.py

@@ -0,0 +1,262 @@
+import asyncio
+import logging
+import uuid
+from asyncio import Queue
+from pathlib import Path
+from random import choice
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+import pydantic.v1
+from aetpiref.typing import (
+    AETPIApplication,
+    AETPIReceiveCallable,
+    AETPISendCallable,
+    ExternalTaskScope,
+    TaskScope,
+)
+
+from fastbpmn.aetpi import protocol as event
+from fastbpmn.aetpi import utils
+
+if TYPE_CHECKING:
+    from fastbpmn.context import Context
+
+logger = logging.getLogger(__name__)
+# An AETPI protocol implementation that does nothing but log the events
+# and sometimes sleep a little bit
+
+
+class LogOnlyExternalTaskProcessor:
+    """
+    External Task Processor for Camunda 7
+    """
+
+    def __init__(
+        self,
+    ):
+        self._lock_duration = 10000
+
+    async def _handle_lock_request(
+        self, _event: event.ExternalTaskLockRequestEvent, send: AETPISendCallable
+    ) -> None:
+        """
+        Handle the lock request
+        """
+        if bool(choice([True, True, True, False])):
+            await send(utils.create_event_lock_accept(self._lock_duration))
+        else:
+            await send(
+                utils.create_event_lock_reject(
+                    "CUSTOM", "Flipped the coin ... and I don't want to"
+                )
+            )
+
+    async def _handle_execute_request(
+        self, _event: event.ExternalTaskExecuteRequestEvent, send: AETPISendCallable
+    ) -> None:
+        """
+        Handle the execute request
+        """
+        if bool(choice([True, True, True, False])):
+            await send(utils.create_event_execute_accept())
+        else:
+            await send(
+                utils.create_event_execute_reject(
+                    "CUSTOM", "Flipped the coin ... and I don't want to"
+                )
+            )
+
+    async def simulate_work(self, _event: event.ExternalTaskExecuteStartEvent):
+
+        class VarsV1(pydantic.v1.BaseModel):
+            x: int
+            y: int
+            z: int
+
+        class VarsV2(pydantic.BaseModel):
+            x: int
+            y: int
+            z: int
+            sub_guid: UUID = pydantic.Field(default_factory=uuid.uuid4)
+
+            @pydantic.computed_field
+            def path_to_var(self) -> Path:
+                return Path(__file__).parent
+
+            @pydantic.computed_field
+            def sum(self) -> int:
+                return self.x + self.y + self.z
+
+        class Test:
+            def __init__(self, x: int, y: int, z: int):
+                self.x = x
+                self.y = y
+                self.z = z
+
+        class OutputModel(pydantic.BaseModel):
+            vars_v2: VarsV2
+
+            guid: UUID = pydantic.Field(default_factory=uuid.uuid4)
+
+            @pydantic.computed_field
+            def sum_v2(self) -> int:
+                return self.vars_v2.x + self.vars_v2.y + self.vars_v2.z
+
+            @pydantic.computed_field
+            def path_to_var(self) -> Path:
+                return Path(__file__)
+
+        class InputModel(pydantic.BaseModel):
+            x: int
+            y: int
+            z: int
+
+        input_model = InputModel(**_event["variables"])
+        _ = VarsV1(**input_model.model_dump(mode="python"))
+        vars_v2 = VarsV2(**input_model.model_dump(mode="python"))
+
+        output_model = OutputModel(vars_v2=vars_v2)
+
+        all_values = output_model.model_dump(mode="python")
+        all_values.update(dict(output_model))
+
+        return output_model.model_dump(mode="python")
+
+    async def _handle_execute_start_event(
+        self,
+        _task_scope: TaskScope,
+        _event: event.ExternalTaskExecuteStartEvent,
+        send: AETPISendCallable,
+    ):
+        """
+        Handle the execute start event
+        """
+
+        match choice([0, 0, 0, 0, 1, 2]):
+            case 0:
+                logger.info(f"Doing things for {_task_scope} - {_event}")
+                await asyncio.sleep((self._lock_duration / 4) / 1000)
+
+                result = await self.simulate_work(_event)
+
+                await send(utils.create_event_execute_complete(variables=result))
+            case 1:
+                await send(
+                    utils.create_event_execute_failure(
+                        error_message="I don't like the color of the sky today",
+                        error_details="The error was random ... please try again later",
+                        variables={"error": "random", "location": Path(__file__)},
+                    )
+                )
+            case _:
+                await send(
+                    utils.create_event_execute_business_error(
+                        error_code="business_error_101",
+                        error_message="Processes are here to face with errors as well",
+                        variables={"error": "business", "location": Path(__file__)},
+                    )
+                )
+
+    async def __call__(
+        self,
+        scope: ExternalTaskScope,
+        context: "Context",
+        receive: AETPIReceiveCallable,
+        send: AETPISendCallable,
+    ) -> None:
+        """
+        Process the external task
+        """
+        # Check if the protocol is supported
+        if scope["type"] != "externaltask":  # pragma: no cover
+            await self.app(scope, context, receive, send)
+            return
+
+        # The tasks properties are crucial so lets extract them now
+        task_scope: TaskScope = scope.get("task")
+
+        while (event := await receive()) is not None:
+            # a more sophisticated implementation would use a state machine
+            # and check if the event is valid in the current state
+            # but for testing thats ok.
+            match event:
+                case {"type": "externaltask.start"}:
+                    logger.info(f"External Task started: {task_scope}")
+                case {"type": "externaltask.lock.request"}:
+                    logger.info(f"External Task lock request: {task_scope}")
+                    await self._handle_lock_request(event, send)
+                case {"type": "externaltask.execute.request"}:
+                    logger.info(f"External Task execute request: {task_scope}")
+                    await self._handle_execute_request(event, send)
+                case {"type": "externaltask.execute.start"}:
+                    logger.info(f"External Task execute start: {task_scope}")
+                    await self._handle_execute_start_event(task_scope, event, send)
+                case {"type": "externaltask.end"}:
+                    logger.info(f"External Task end: {task_scope}")
+                    break
+                case _:
+                    logger.warning(f"Unexpected event: {event}")
+
+
+async def server(app: AETPIApplication, topic: str):
+    send_queue: Queue[event.AETPIReceiveEvent] = Queue()
+
+    # First indicate the start of an arbitrary external task
+    await send_queue.put(utils.create_event_start())
+    await send_queue.put(utils.create_event_lock_request())
+
+    async def receive() -> event.AETPIReceiveEvent:
+        return await send_queue.get()
+
+    # The send callable is actually where get the responses from
+
+    async def send(event: event.AETPISendEvent) -> None:
+
+        match event:
+            case {"type": "externaltask.lock.accept"}:
+                logger.info("<server-receive> Lock accepted")
+                logger.info(event)
+                await send_queue.put(utils.create_event_execute_request())
+            case {"type": "externaltask.execute.accept"}:
+                logger.info("<server-receive> Execute accepted")
+                logger.info(event)
+                await send_queue.put(
+                    utils.create_event_execute_start({"x": 1, "y": 2, "z": 3})
+                )
+            case {"type": "externaltask.execute.complete"}:
+                logger.info("Execute complete")
+                logger.info(event)
+                await send_queue.put(utils.create_event_end())
+
+            case {"type": "externaltask.lock.reject"}:
+                logger.info("Lock rejected")
+                logger.info(event)
+                await send_queue.put(utils.create_event_end())
+            case {"type": "externaltask.execute.reject"}:
+                logger.info("Execute rejected")
+                logger.info(event)
+                await send_queue.put(utils.create_event_end())
+            case {"type": "externaltask.execute.failure"}:
+                logger.info("Execute failure")
+                logger.info(event)
+                await send_queue.put(utils.create_event_end())
+            case {"type": "externaltask.execute.error"}:
+                logger.info("Execute business error")
+                logger.info(event)
+                await send_queue.put(utils.create_event_end())
+            case _:
+                logger.info(event)
+                logger.warning(f"Unexpected event: {event}")
+
+    await app(
+        {
+            "type": "externaltask",
+            "protocol": "camunda7",
+            "aetpi": {"version": "1.0", "spec_version": "1.0"},
+            "task": {"id": "12345678-1234-5678-1234-567812345678", "topic": topic},
+        },
+        None,
+        receive,
+        send,
+    )

fastbpmn/aetpi/middleware/__init__.py

@@ -0,0 +1,5 @@
+from .variables import BaseSyncVariableHandlerMiddleware
+
+__all__ = [
+    "BaseSyncVariableHandlerMiddleware",
+]

fastbpmn/aetpi/middleware/variables.py

@@ -0,0 +1,90 @@
+"""
+Middleware to handle variables in the AETPI
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from aetpiref.typing import (
+    AETPIApplication,
+    AETPIReceiveCallable,
+    AETPIReceiveEvent,
+    AETPISendCallable,
+    AETPISendEvent,
+    ExternalTaskScope,
+)
+
+if TYPE_CHECKING:
+    pass
+
+
+class BaseSyncVariableHandlerMiddleware:
+    """
+    Base class for variable handlers
+    """
+
+    def __init__(self, app: AETPIApplication):
+        self.app = app
+
+    def process_application_variables(
+        self, variables: dict[str, Any] | None
+    ) -> dict[str, Any] | None:
+        """
+        Process variables, that are passed from the server to the application
+        (from process engine -> to your task handlers)
+        """
+        return variables
+
+    def process_server_variables(
+        self, variables: dict[str, Any] | None
+    ) -> dict[str, Any] | None:
+        """
+        Process variables, that are passed from the application to the server
+        (from your task handlers -> to process engine)
+        """
+        return variables
+
+    async def __call__(
+        self,
+        scope: ExternalTaskScope,
+        receive: AETPIReceiveCallable,
+        send: AETPISendCallable,
+    ) -> None:
+        if scope["type"] != "externaltask":  # pragma: no cover
+            return await self.app(scope, receive, send)
+
+        # Now lets see interest is only in the variable a like events
+        # - exter
+
+        async def receive_wrapper() -> AETPIReceiveEvent:
+
+            event = await receive()
+
+            match event:
+                case {"type": "externaltask.execute.start", "variables": variables}:
+                    variables = self.process_application_variables(variables)
+                    event["variables"] = variables
+
+            return event
+
+        async def send_wrapper(event: AETPISendEvent) -> None:
+
+            match event:
+                case {"type": "externaltask.execute.complete", "variables": variables}:
+                    variables = self.process_server_variables(variables)
+                    event["variables"] = variables
+                case {
+                    "type": "externaltask.execute.failure",
+                    "variables": variables,
+                    "local_variables": local_variables,
+                }:
+                    variables = self.process_server_variables(variables)
+                    local_variables = self.process_server_variables(local_variables)
+                    event["variables"] = variables
+                    event["local_variables"] = local_variables
+                case {"type": "externaltask.execute.error", "variables": variables}:
+                    variables = self.process_server_variables(variables)
+                    event["variables"] = variables
+
+            return await send(event)
+
+        return await self.app(scope, receive_wrapper, send_wrapper)

fastbpmn/aetpi/servers/camunda7/__init__.py

@@ -0,0 +1,45 @@
+import logging
+import re
+
+from aetpiref.typing import AETPIApplication
+from pydantic import HttpUrl
+
+from .server import Camunda7Server
+
+logger = logging.getLogger(__name__)
+
+
+def run(
+    app: AETPIApplication,
+    *,
+    name: str,
+    parallelism: int = 10,
+    shuffle_pending: bool = True,
+    tenant_ids: list[str] | None = None,
+    business_key_alike: re.Pattern | None = None,
+    camunda_base_url: HttpUrl | str = None,
+    camunda_username: str | None = None,
+    camunda_password: str | None = None,
+    camunda_timeout: float | None = None,
+):
+
+    if business_key_alike is not None:
+        logger.warning(
+            "[DEPRECATED] consider using tenants instead of business_key_alike"
+        )
+
+    Camunda7Server(
+        app,
+        name=name,
+        parallelism=parallelism,
+        shuffle_pending=shuffle_pending,
+        tenant_ids=tenant_ids,
+        business_key_alike=business_key_alike,
+        camunda_base_url=camunda_base_url,
+        camunda_username=camunda_username,
+        camunda_password=camunda_password,
+        camunda_timeout=camunda_timeout,
+    ).run()
+
+
+__all__ = ["run"]

fastbpmn/aetpi/servers/camunda7/decoder.py

@@ -0,0 +1,214 @@
+from typing import TYPE_CHECKING, Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, Field, Json, TypeAdapter, WrapValidator, field_validator
+from pydantic_core.core_schema import ValidationInfo
+
+from fastbpmn.models.base import FileInfo
+
+if TYPE_CHECKING:
+    pass
+
+BooleanTypeLiteral = Literal["boolean", "Boolean"]
+IntegerTypeLiteral = Literal["integer", "Integer"]
+ShortTypeLiteral = Literal["short", "Short"]
+LongTypeLiteral = Literal["long", "Long"]
+DoubleTypeLiteral = Literal["double", "Double"]
+StringTypeLiteral = Literal["string", "String"]
+JsonTypeLiteral = Literal["json", "Json"]
+NullTypeLiteral = Literal["null", "Null"]
+FileTypeLiteral = Literal["file", "File"]
+
+
+DecodedPythonTypes = Union[bool, int, float, str, None, Json, FileInfo]
+
+
+class Camunda7Primitive(BaseModel):
+    """
+    Handling for primitive types
+    """
+
+    name: str
+    value_type: str = Field(..., alias="type")
+    value: DecodedPythonTypes
+
+
+class Camunda7Boolean(Camunda7Primitive):
+    """
+    Handling for boolean values
+    """
+
+    name: str
+    value_type: BooleanTypeLiteral = Field(..., alias="type")
+    value: bool
+
+
+class Camunda7Integer(Camunda7Primitive):
+    """
+    Handling for integer values
+    """
+
+    name: str
+    value_type: IntegerTypeLiteral = Field(..., alias="type")
+    value: int
+
+
+class Camunda7Short(Camunda7Primitive):
+    """
+    Handling for short values
+    """
+
+    name: str
+    value_type: ShortTypeLiteral = Field(..., alias="type")
+    value: int
+
+
+class Camunda7Long(Camunda7Primitive):
+    """
+    Handling for long values
+    """
+
+    name: str
+    value_type: LongTypeLiteral = Field(..., alias="type")
+    value: int
+
+
+class Camunda7Double(Camunda7Primitive):
+    """
+    Handling for double values
+    """
+
+    name: str
+    value_type: DoubleTypeLiteral = Field(..., alias="type")
+    value: float
+
+
+class Camunda7String(Camunda7Primitive):
+    """
+    Handling for string values
+    """
+
+    name: str
+    value_type: StringTypeLiteral = Field(..., alias="type")
+    # Check if = None is required as default assignment
+    value: str | None
+
+
+class Camunda7Json(Camunda7Primitive):
+    """
+    Handling for json values
+    """
+
+    name: str
+    value_type: JsonTypeLiteral = Field(..., alias="type")
+    value: Json
+
+
+class Camunda7Null(Camunda7Primitive):
+    """
+    Handling for null values
+    """
+
+    name: str
+    value_type: Literal["null", "Null"] = Field(..., alias="type")
+    value: Any = None
+
+
+class Camunda7FileInfo(Camunda7Primitive):
+    """
+    Handling for file values
+    """
+
+    name: str
+    value_type: Literal["file", "File"] = Field(..., alias="type")
+    value: FileInfo = Field(None, alias="valueInfo", validate_default=True)
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def validate_value(cls, value: dict[str, Any], info: ValidationInfo):
+
+        value = value or {}
+        variable_name = info.data.get("name")
+
+        return {
+            **value,
+            "variable_name": variable_name,
+        }
+
+
+# Annotated Union to parse single camunda7 variables
+# easily
+Camunda7VariableType = Union[
+    Camunda7Boolean,
+    Camunda7Integer,
+    Camunda7Short,
+    Camunda7Long,
+    Camunda7Double,
+    Camunda7String,
+    Camunda7Json,
+    Camunda7Null,
+    Camunda7FileInfo,
+]
+AnnotatedCamunda7VariableType = Annotated[
+    Union[
+        Camunda7Boolean,
+        Camunda7Integer,
+        Camunda7Short,
+        Camunda7Long,
+        Camunda7Double,
+        Camunda7String,
+        Camunda7Json,
+        Camunda7Null,
+        Camunda7FileInfo,
+    ],
+    Field(discriminator="value_type"),
+]
+
+
+# We want / or need ... the variable name and value together
+# so we need to list that somehow ...
+Camunda7Variables = list[AnnotatedCamunda7VariableType]
+
+
+def preprocess_var_dict(rest_vars: dict[str, Any]) -> list[dict[str, Any]]:
+    """
+    Create a list that is suitable to be used with provided type adapter
+    """
+    return [{"name": key, **value} for (key, value) in rest_vars.items()]
+
+
+# TypeAdapters useful for parsing camunda7 variables
+Camunda7TypeAdapter = TypeAdapter(AnnotatedCamunda7VariableType)
+Camunda7VariableAdapter = TypeAdapter(Camunda7Variables)  # Todo: Remove
+Camunda7VariablesAdapter = TypeAdapter(Camunda7Variables)
+
+# Conversion layer to more python friendly types
+# for camunda7 variables
+DecodedVariableTypes = Union[bool, int, float, str, dict, None, FileInfo]
+
+
+def primitive_validator(
+    v: Camunda7VariableType, handler, info: ValidationInfo
+) -> DecodedVariableTypes:
+    if isinstance(v, Camunda7VariableType):
+        return v.value
+    handler(v)
+
+
+CamundaVariables = dict[
+    str, Annotated[DecodedPythonTypes, WrapValidator(primitive_validator)]
+]
+CamundaVariableAdapter = TypeAdapter(CamundaVariables)
+
+
+def decode_variables(variables: dict[str, Any]) -> CamundaVariables:
+    """
+    Read camunda variables from a dict
+    """
+    preprocessed = preprocess_var_dict(variables)
+
+    variables = Camunda7VariablesAdapter.validate_python(preprocessed)
+    variables_dict = {v.name: v for v in variables}
+
+    minion_variables = CamundaVariableAdapter.validate_python(variables_dict)
+
+    return minion_variables