processcube-etw-library 2026.1.22.145211__py3-none-any.whl → 2026.1.29.103633__py3-none-any.whl

processcube_etw_library/processcube_client/external_task/external_task_client.py

@@ -0,0 +1,195 @@
+import asyncio
+from concurrent import futures
+import errno
+import logging
+import uuid
+import warnings
+
+from ..core import BaseClient, LoopHelper, get_or_create_loop
+from .external_task_worker import ExternalTaskWorker
+
+logger = logging.getLogger(__name__)
+
+
+class ExternalTaskClient(BaseClient):
+    def __init__(self, url, session=None, identity=None, loop=None, **kwargs):
+        super(ExternalTaskClient, self).__init__(url, session, identity)
+
+        new_kwargs = kwargs.copy()
+        new_kwargs["on_shutdown"] = self.__on_shutdown
+
+        if loop is None:
+            loop = get_or_create_loop()
+        else:
+            if "install_signals" not in new_kwargs:
+                new_kwargs["install_signals"] = False
+
+        self.__loop_helper = LoopHelper(loop, **new_kwargs)
+        self.__worker_id = kwargs.get("worker_id", str(uuid.uuid4()))
+
+        self._topic_for_handler = {}
+
+    def subscribe_to_external_task_for_topic(self, topic, handler, **options):
+        warnings.warn(
+            "Please use 'subscribe_to_external_task_topic' instead of 'subscribe_to_external_task_for_topic'.",
+            DeprecationWarning,
+        )
+        self.subscribe_to_external_task_topic(topic, handler, **options)
+
+    def subscribe_to_external_task_topic(self, topic, handler, **options):
+        """
+        task_options:
+            - max_tasks
+            - long_polling_timeout -> long_polling_timeout_in_ms
+            - lock_duration -> lock_duration_in_ms
+            #- additional_duration
+            #- extend_lock_timeout
+            - payload_filter
+        """
+
+        task_options = options.copy()
+
+        if task_options.get("long_polling_timeout", None) is not None:
+            logger.warning(
+                "deprecated long_polling_timeout, please use long_polling_timeout_in_ms"
+            )
+            task_options["long_polling_timeout_in_ms"] = options["long_polling_timeout"]
+            del task_options["long_polling_timeout"]
+
+        if task_options.get("lock_duration", None) is not None:
+            logger.warning("deprecated lock_duration, please use lock_duration_in_ms")
+            task_options["lock_duration_in_ms"] = options["lock_duration"]
+            del task_options["lock_duration"]
+
+        if task_options.get("additional_lock_duration", None) is not None:
+            logger.warning(
+                "additional_lock_duration is ignored, but lock_duration_in_ms is used"
+            )
+
+        if task_options.get("extend_lock_timeout", None) is not None:
+            logger.warning(
+                "extend_lock_timeout is ignored, but 90 percent of lock_duration is used"
+            )
+            del task_options["extend_lock_timeout"]
+
+        if topic in self._topic_for_handler:
+            logger.warning(f"The topic '{topic}' skipped, is already registered.'")
+        else:
+            self.__start_subscription(topic, handler, task_options)
+
+    def __start_subscription(self, topic, handler, task_options):
+        async def bg_job_handle_external_tasks():
+            try:
+                await self.handle_external_tasks(topic, handler, task_options)
+            except Exception as e:
+                if type(e) is errno.EPIPE:
+                    # Raised while long polling finished, that the reason for only log as info.
+                    logger.info(f"Expected long polling error: {e}")
+                else:
+                    import traceback
+                    import sys
+
+                    traceback.print_exc(file=sys.stdout)
+                    logger.warn(f"Exception on handle_external_task: {e}")
+
+        async_bg_task = self.__loop_helper.register_background_task(
+            bg_job_handle_external_tasks
+        )
+        self._topic_for_handler[topic] = async_bg_task
+
+    def subscribe_to_external_tasks_for_topics(self, topics_for_handlers):
+        for topic in topics_for_handlers.keys():
+            handler = topics_for_handlers[
+                topic
+            ]  # TODO: Options sollten auch hier zu setzen sein
+
+            self.subscribe_to_external_task_for_topic(topic, handler)
+
+    def start(self, run_forever=True):
+        logger.info(
+            f"Starting external task for topics '{', '.join(self._topic_for_handler.keys())}'."
+        )
+        logger.info(f"Connecting to process engine at url '{self._url}'.")
+        self.__loop_helper.start(run_forever=run_forever)
+
+    async def handle_external_tasks(self, topic, handler, task_options):
+        external_tasks = await self.__fetch_and_lock(topic, handler, task_options)
+
+        len_external_tasks = len(external_tasks)
+        if len_external_tasks >= 1:
+            logger.info(f"Receive {len_external_tasks} tasks for topic '{topic}'.")
+
+            external_task_tasks = []
+
+            external_task_options = {
+                "long_polling_timeout_in_ms": task_options.get(
+                    "long_polling_timeout_in_ms"
+                ),
+                "lock_duration_in_ms": task_options.get("lock_duration_in_ms"),
+            }
+
+            for external_task in external_tasks:
+                external_task_worker = ExternalTaskWorker(
+                    self._url,
+                    self._session,
+                    self._identity,
+                    self.__loop_helper,
+                    topic,
+                    handler,
+                    external_task,
+                    external_task_options,
+                )
+                task = asyncio.create_task(external_task_worker.start())
+                external_task_tasks.append(task)
+
+            try:
+                done_tasks, pending = await asyncio.wait(
+                    external_task_tasks, return_when=futures.ALL_COMPLETED
+                )
+                logger.debug(
+                    f"Wait result while handle external task (done: {done_tasks}, pending {pending})."
+                )
+            except Exception as e:
+                logger.error(f"asyncio.wait({e} - {type(e)})")
+
+    async def __on_shutdown(self):
+        await self.close()
+
+    def stop(self):
+        logger.info(
+            f"Stopping external task for topics {self._topic_for_handler.keys()}"
+        )
+        self.__loop_helper.stop()
+
+    async def __fetch_and_lock(self, topic, handler, task_options={}):
+        logger.debug(
+            f"fetch and lock external task for topic {topic} and options {task_options}"
+        )
+
+        max_tasks = task_options.get("max_tasks", 10)
+        long_polling_timeout = task_options.get(
+            "long_polling_timeout_in_ms", (10 * 1000)
+        )
+        lock_duration = task_options.get("lock_duration_in_ms", (100 * 1000))
+        payload_filter = task_options.get("payload_filter", None)
+
+        request = {
+            "workerId": self.__worker_id,
+            "topicName": topic,
+            "maxTasks": max_tasks,
+            "longPollingTimeout": long_polling_timeout,
+            "lockDuration": lock_duration,
+        }
+
+        if payload_filter is not None:
+            request["payloadFilter"] = payload_filter
+
+        try:
+            external_tasks = await self.do_post(
+                "/atlas_engine/api/v1/external_tasks/fetch_and_lock", request
+            )
+        except Exception as e:
+            logger.error(f"fetch_and_lock({e} - {type(e)})")
+            external_tasks = []
+
+        return external_tasks

processcube_etw_library/processcube_client/external_task/external_task_worker.py

@@ -0,0 +1,205 @@
+import asyncio
+import inspect
+import logging
+import traceback
+import concurrent.futures
+
+from ..core import BaseClient, ensure_has_loop
+from .functional_error import FunctionalError
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExternalTaskWorker(BaseClient):
+
+    LOCK_DURATION_IN_MS = (60 * 1000)
+    # Class-level executor to be reused across all instances
+    _executor = None
+
+    def __init__(self, url, session, identity, loop_helper, topic, handler, external_task, options={}):
+        super(ExternalTaskWorker, self).__init__(url, session, identity)
+        self._loop_helper = loop_helper
+        self._topic = topic
+        self._handler = handler
+        self._external_task = external_task
+        self._payload = self._external_task.get('payload', {})
+        self._options = options
+
+    @classmethod
+    def _get_executor(cls):
+        """Get or create the class-level ThreadPoolExecutor"""
+        if cls._executor is None:
+            cls._executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+        return cls._executor
+
+    def __get_lock_duration_in_ms(self):
+        lock_duration_in_ms = self._options.get("lock_duration_in_ms", ExternalTaskWorker.LOCK_DURATION_IN_MS)
+
+        if lock_duration_in_ms is None:
+            logger.info(f":ock_duration_in_ms is not given, set to default {ExternalTaskWorker.LOCK_DURATION_IN_MS}")
+            lock_duration_in_ms = ExternalTaskWorker.LOCK_DURATION_IN_MS
+
+        return lock_duration_in_ms
+
+    def __lock_timeout_in_ms(self):
+        lock_duration_in_ms = self.__get_lock_duration_in_ms()
+        lock_timeout_in_ms = lock_duration_in_ms * 0.9
+
+        return lock_timeout_in_ms
+
+    def __delay_in_seconds(self):
+        delay_in_seconds = self.__lock_timeout_in_ms() / 1000
+
+        return delay_in_seconds
+
+    def __with_external_task_param(self):
+
+        def is_handler_a_func(func):
+            spec = inspect.getfullargspec(func)
+            is_func = inspect.isroutine(func)
+
+            result = (len(spec.args) == 2 and is_func)
+
+            return result
+
+        def is_handler_callable(caller):
+            spec = inspect.getfullargspec(caller)
+            is_func = inspect.isroutine(caller)
+
+            result = (len(spec.args) == 3 and not is_func)
+
+            return result
+
+        return is_handler_a_func(self._handler) or is_handler_callable(self._handler)
+
+    async def start(self):
+
+        def is_async_handler(handler):
+            if asyncio.iscoroutinefunction(handler):
+                return True
+            elif hasattr(handler, '__call__') and inspect.iscoroutinefunction(handler.__call__):
+                return True
+            else:
+                return False
+
+        async def extend_lock_task_wrapper():
+            worker_id = self._external_task['workerId']
+            external_task_id = self._external_task['id']
+
+            lock_duration_in_ms = self.__get_lock_duration_in_ms()
+
+            await self.extend_lock(worker_id, external_task_id, lock_duration_in_ms)
+
+        delay_in_seconds = self.__delay_in_seconds()
+
+        options = {'delay_in_seconds': delay_in_seconds}
+        extend_lock = self._loop_helper.register_background_task(extend_lock_task_wrapper, **options)
+        
+        external_task_id = self._external_task['id']
+        logger.info(f"Starting external task '{external_task_id}' for topic '{self._topic}'")
+
+        try:
+            result = None
+            
+            if is_async_handler(self._handler):
+                def handler_wrapper():
+                    async def async_handler():
+                        if self.__with_external_task_param():
+                            return await self._handler(self._payload, self._external_task)
+                        else:
+                            return await self._handler(self._payload)
+
+                    #new_loop = asyncio.new_event_loop()
+                    # see https://stackoverflow.com/questions/46727787/runtimeerror-there-is-no-current-event-loop-in-thread-in-async-apscheduler
+                    #asyncio.set_event_loop(new_loop)
+
+                    new_loop = ensure_has_loop()
+
+                    result = new_loop.run_until_complete(async_handler())
+
+                    return result
+
+                # Use class-level executor to avoid race condition
+                # The executor must not be closed before the async operation completes
+                executor = self._get_executor()
+                result = await self._loop_helper._loop.run_in_executor(executor, handler_wrapper)
+
+            else:
+                fkt = None
+                if self.__with_external_task_param():
+                    def with_all_args():
+                        ensure_has_loop()
+
+                        result = self._handler(self._payload, self._external_task)
+                        return result
+                    fkt = with_all_args
+                else:
+                    def with_some_args():
+                        ensure_has_loop()
+
+                        result = self._handler(self._payload)
+                        return result
+                    fkt = with_some_args
+
+                # Use class-level executor to avoid race condition
+                # The executor must not be closed before the async operation completes
+                executor = self._get_executor()
+                result = await self._loop_helper._loop.run_in_executor(executor, fkt)
+
+            await self.__finish_task_successfully(result)
+            
+        except FunctionalError as fe:
+            logger.warning(f"Finish external task with functional error (code: {fe.get_code()}, message: {fe.get_message()})")
+            await self.__finish_task_with_errors(fe.get_code(), fe.get_message(), fe.get_details())
+
+        except Exception as e:
+            formatted_lines = traceback.format_exc().splitlines()
+            logger.error(f"Finish external task with technical error ({str(e)} -> {formatted_lines})")
+            await self.__finish_task_with_errors(str(e), str(formatted_lines))
+        finally:
+            self._loop_helper.unregister_background_task(extend_lock, "extend_lock background task")
+
+    async def extend_lock(self, worker_id, external_task_id, additional_duration):
+        path = f"/atlas_engine/api/v1/external_tasks/{external_task_id}/extend_lock"
+        
+        logger.info(f"Extend lock for worker '{worker_id}' with external_task_id '{external_task_id}' for topic '{self._topic}' for another {additional_duration}ms")
+
+        request = {
+            "workerId": worker_id,
+            "additionalDuration": additional_duration
+        }
+        try:
+            await self.do_put(path, request)
+        except Exception as e:
+            logger.error(f"Error on extend lock for worker {worker_id} for {additional_duration}ms with error {e}")
+
+    async def __finish_task_successfully(self, result):
+        external_task_id = self._external_task['id']
+        worker_id = self._external_task['workerId']
+
+        logger.info(f"Finish external task '{external_task_id}' for worker '{worker_id}' and topic '{self._topic}' with result '{result}'")
+        path = f"/atlas_engine/api/v1/external_tasks/{external_task_id}/finish"
+
+        payload = {
+            "workerId": worker_id,
+            "result": result
+        }
+
+        result = await self.do_put(path, payload)
+        logger.info(f"Finished external task '{external_task_id}' successfully.")
+
+    async def __finish_task_with_errors(self, error_code, error_message, error_details=""):
+        logger.warning(f"Finished external task_with errors '{self._external_task}', '{error_code}', '{error_message}'.")
+        path = f"/atlas_engine/api/v1/external_tasks/{self._external_task['id']}/error"
+
+        payload = {
+            "workerId": self._external_task['workerId'],
+            "error": {
+                "errorCode": error_code,
+                "errorMessage": error_message,
+                "errorDetails": error_details
+            }
+        }
+
+        await self.do_put(path, payload)

processcube_etw_library/processcube_client/external_task/functional_error.py

@@ -0,0 +1,17 @@
+
+class FunctionalError(Exception):
+    
+    def __init__(self, code, message, details=""):
+        super(FunctionalError, self).__init__(message)
+        self._code = code
+        self._message = message
+        self._details = details
+
+    def get_code(self):
+        return self._code
+
+    def get_message(self):
+        return self._message
+
+    def get_details(self):
+        return self._details

processcube_etw_library/processcube_client/flow_node_instance/__init__.py

@@ -0,0 +1 @@
+from .flow_node_instance_client import FlowNodeInstanceClient

processcube_etw_library/processcube_client/flow_node_instance/flow_node_instance_client.py

@@ -0,0 +1,43 @@
+import logging
+
+from ..core import base_client
+
+logger = logging.getLogger(__name__)
+
+
+class FlowNodeInstanceClient(base_client.BaseClient):
+    def __init__(self, url, session=None, identity=None):
+        super(FlowNodeInstanceClient, self).__init__(url, session, identity)
+
+    async def __trigger_message_event(self, event_name, process_instance_id=None):
+        url = f"/atlas_engine/api/v1/messages/{event_name}/trigger"
+
+        if process_instance_id is not None:
+            url = f"{url}?processInstanceId={process_instance_id}"
+
+        result = await self.do_post(url, {})
+
+        return result
+
+    def trigger_message_event(self, event_name, process_instance_id=None):
+        logger.info(f"Connection to process engine at url '{self._url}'.")
+        logger.info(f"Trigger message '{event_name}'.")
+
+        return base_client.run_async_in_sync_context(
+            self.__trigger_message_event(event_name, process_instance_id)
+        )
+
+    async def __trigger_signal_event(self, event_name):
+        url = f"/atlas_engine/api/v1/signals/{event_name}/trigger"
+
+        result = await self.do_post(url, {})
+
+        return result
+
+    def trigger_signal_event(self, event_name):
+        logger.info(f"Connection to process engine at url '{self._url}'.")
+        logger.info(f"Trigger signal '{event_name}'.")
+
+        return base_client.run_async_in_sync_context(
+            self.__trigger_signal_event(event_name)
+        )

processcube_etw_library/processcube_client/notification/__init__.py

@@ -0,0 +1 @@
+from .notification_client import NotificationClient

processcube_etw_library/processcube_client/notification/notification_client.py

@@ -0,0 +1,103 @@
+import asyncio
+import logging
+
+from ..core import BaseClient, LoopHelper
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationClient(BaseClient):
+    def __init__(self, url, session=None, identity=None):
+        super(NotificationClient, self).__init__(url, session, identity)
+
+        self.__loop_helper = LoopHelper(on_shutdown=self.__on_shutdown)
+        self.__notification_callbacks = {}
+
+    async def __on_shutdown(self):
+        for task in self.__notification_callbacks.values():
+            self.__loop_helper.unregister_background_task(task)
+
+        await self.close()
+
+    def start(self):
+        logger.info(f"Connecting to process engine at url '{self._url}'.")
+        self.__loop_helper.start()
+
+    def __on_register_event(self, event_name, callback):
+        async def bg_on_event():
+            url = f"/atlas_engine/api/v1/notifications/long_polling/{event_name}"
+
+            result = await self.do_get(url)
+
+            logger.debug(f"handling event '{event_name}' with {result}")
+
+            if asyncio.iscoroutine(callback):
+                await callback(result)
+            else:
+                callback(result)
+
+        async_bg_task = self.__loop_helper.register_background_task(bg_on_event)
+        self.__notification_callbacks[event_name] = async_bg_task
+
+    def on_activity_reached(self, callback):
+        self.__on_register_event("activity_reached", callback)
+
+    def on_activity_finished(self, callback):
+        self.__on_register_event("activity_finished", callback)
+
+    def on_boundary_event_triggered(self, callback):
+        self.__on_register_event("boundary_event_triggered", callback)
+
+    def on_empty_activity_waiting(self, callback):
+        self.__on_register_event("empty_activity_waiting", callback)
+
+    def on_empty_activity_finished(self, callback):
+        self.__on_register_event("empty_activity_finished", callback)
+
+    def on_manual_task_waiting(self, callback):
+        self.__on_register_event("manual_task_waiting", callback)
+
+    def on_manual_task_finished(self, callback):
+        self.__on_register_event("manual_task_finished", callback)
+
+    def on_process_started(self, callback):
+        self.__on_register_event("process_started", callback)
+
+    def on_process_ended(self, callback):
+        self.__on_register_event("process_ended", callback)
+
+    def on_process_error(self, callback):
+        self.__on_register_event("process_error", callback)
+
+    def on_user_task_waiting(self, callback):
+        self.__on_register_event("user_task_waiting", callback)
+
+    def on_user_task_finished(self, callback):
+        self.__on_register_event("user_task_finished", callback)
+
+    def on_user_task_reserved(self, callback):
+        self.__on_register_event("user_task_reserved", callback)
+
+    def on_user_task_reservation_canceled(self, callback):
+        self.__on_register_event("user_task_reservation_canceled", callback)
+
+    def on_empty_activity_finished(self, callback):
+        self.__on_register_event("empty_activity_finished", callback)
+
+    def on_empty_activity_waiting(self, callback):
+        self.__on_register_event("empty_activity_waiting", callback)
+
+    def on_manual_task_finished(self, callback):
+        self.__on_register_event("manual_task_finished", callback)
+
+    def on_manual_task_waiting(self, callback):
+        self.__on_register_event("manual_task_waiting", callback)
+
+    def on_intermediate_throw_event_triggered(self, callback):
+        self.__on_register_event("intermediate_throw_event_triggered", callback)
+
+    def on_intermediate_catch_event_reached(self, callback):
+        self.__on_register_event("intermediate_catch_event_reached", callback)
+
+    def on_intermediate_catch_event_finished(self, callback):
+        self.__on_register_event("intermediate_catch_event_finished", callback)

processcube_etw_library/processcube_client/process_definition/__init__.py

@@ -0,0 +1,2 @@
+from .process_definition_client import ProcessDefinitionClient
+from .start_callback_type import StartCallbackType

processcube_etw_library/processcube_client/process_definition/process_definition_client.py

@@ -0,0 +1,94 @@
+import logging
+
+from ..core import base_client
+from .start_callback_type import StartCallbackType
+
+logger = logging.getLogger(__name__)
+
+
+class ProcessDefinitionClient(base_client.BaseClient):
+
+    def __init__(self, url, session=None, identity=None):
+        super(ProcessDefinitionClient, self).__init__(url, session, identity)
+
+    async def __start_process_instance(self, process_model_id, **options):
+        start_callback_type = options.get('start_callback', StartCallbackType.ON_PROCESSINSTANCE_CREATED)
+        path = f"/atlas_engine/api/v1/process_models/{process_model_id}/start"
+
+        initial_token = options.get('inital_token', {})
+
+        payload = {
+            "returnOn": int(start_callback_type),
+            "processModelId": process_model_id,
+            "initialToken": initial_token
+        }
+
+        logger.info(f"Start process with uri '{path}' and payload '{payload}'")
+
+        result = await self.do_post(path, payload)
+
+        return result
+
+    async def __start_process_instance_by_start_event(self, process_model_id, start_event_id, end_event_id, **options):
+        start_callback_type = options.get('start_callback', StartCallbackType.ON_PROCESSINSTANCE_CREATED)
+        path = f"/atlas_engine/api/v1/process_models/{process_model_id}/start"
+
+        initial_token = options.get('initial_token', {})
+
+        payload = {
+            "returnOn": int(start_callback_type),
+            "processModelId": process_model_id,
+            "startEventId": start_event_id,
+            "initialToken": initial_token
+        }
+
+        if end_event_id is not None:
+            payload["endEventId"] = end_event_id
+
+        logger.info(f"Start process with uri '{path}' and payload '{payload}'")
+
+        result = await self.do_post(path, payload)
+
+        return result
+
+    def __start_process_instance_wrapper(self, process_model_id, start_event_id=None, end_event_id=None, **options):
+
+        async def _start():
+            if start_event_id is not None:
+                result = await self.__start_process_instance_by_start_event(process_model_id, start_event_id, end_event_id, **options)
+            else:
+                result = await self.__start_process_instance(process_model_id, **options)
+
+            await self.close()
+
+            return result
+
+        logger.info(f"Connection to process engine at url '{self._url}'.")
+        logger.info(f"Starting process instance process_model_id '{process_model_id}' and start_event_id '{start_event_id}'.")
+
+        return base_client.run_async_in_sync_context(_start())
+
+    def start_process_instance(self, process_model_id, start_event_id=None, **options):
+        options['start_callback'] = StartCallbackType.ON_PROCESSINSTANCE_CREATED
+
+        return self.__start_process_instance_wrapper(process_model_id, start_event_id, **options)
+
+    def start_process_instance_and_await_end_event(self, process_model_id, start_event_id=None, **options):
+        options['start_callback'] = StartCallbackType.ON_PROCESSINSTANCE_FINISHED
+
+        return self.__start_process_instance_wrapper(process_model_id, start_event_id, **options)
+
+    def start_process_instance_and_await_specific_end_event(self, process_model_id, start_event_id=None, end_event_id=None, **options):
+        options['start_callback'] = StartCallbackType.ON_ENDEVENT_REACHED
+
+        return self.__start_process_instance_wrapper(process_model_id, start_event_id, end_event_id, **options)
+
+    def get_process_definition(self, process_model_id):
+
+        async def _get_definition():
+            url = f"/atlas_engine/api/v1/process_models/{process_model_id}/process_definition"
+            return await self.do_get(url)
+
+        logger.info(f"Get the definition of process_model '{process_model_id}' from atlas engine at url '{self._url}'.")
+
+        return base_client.run_async_in_sync_context(_get_definition())

processcube_etw_library/processcube_client/process_definition/start_callback_type.py

@@ -0,0 +1,6 @@
+from enum import IntEnum
+
+class StartCallbackType(IntEnum):
+    ON_PROCESSINSTANCE_CREATED = 1
+    ON_PROCESSINSTANCE_FINISHED = 2
+    ON_ENDEVENT_REACHED = 3

processcube_etw_library/processcube_client/process_instance/__init__.py

@@ -0,0 +1 @@
+from .process_instance_client import ProcessInstanceClient