quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/executors/jobs/job_executor.py

@@ -0,0 +1,190 @@
+"""
+Job Executor - Execute q:job statements
+
+Handles job queue operations.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import JobNode
+
+
+class JobExecutor(BaseExecutor):
+    """
+    Executor for q:job statements.
+
+    Supports:
+    - Job definition
+    - Job dispatch (enqueue)
+    - Batch job dispatch
+    - Priority and delay
+    - Retry with backoff
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [JobNode]
+
+    def execute(self, node: JobNode, exec_context) -> Any:
+        """
+        Execute job management.
+
+        Args:
+            node: JobNode with job configuration
+            exec_context: Execution context
+
+        Returns:
+            Job operation result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Execute based on action
+            if node.action == 'define':
+                result = self._execute_define(node, context, exec_context)
+            elif node.action == 'dispatch':
+                result = self._execute_dispatch(node, context, exec_context)
+            elif node.action == 'batch':
+                result = self._execute_batch(node, context, exec_context)
+            else:
+                raise ExecutorError(f"Unknown job action: {node.action}")
+
+            # Store result with both naming conventions for compatibility
+            exec_context.set_variable(f"dispatched_job_{node.name}", result, scope="component")
+            exec_context.set_variable(f"job_{node.name}", result, scope="component")
+
+            # Also store in runtime context if available
+            if hasattr(self._runtime, 'context'):
+                self._runtime.context[f"dispatched_job_{node.name}"] = result
+                self._runtime.context[f"job_{node.name}"] = result
+
+            return result
+
+        except Exception as e:
+            raise ExecutorError(f"Job execution error: {e}")
+
+    def _execute_define(self, node: JobNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Define a job (register handler)."""
+        name = node.name
+        queue = node.queue
+
+        # Get job_executor from runtime (same as legacy code)
+        job_executor = self._runtime.job_executor
+
+        # Create job handler that executes the job body
+        def job_handler(params: Dict[str, Any]):
+            from quantum.runtime.execution_context import ExecutionContext as EC
+            child_context = EC()
+            for param_name, param_value in params.items():
+                child_context.set_variable(param_name, param_value, scope="component")
+
+            # Execute job body statements
+            for statement in node.body:
+                self._runtime._execute_statement(statement, child_context)
+
+        # Register handler with job queue
+        job_executor.job_queue.register_handler(name, job_handler)
+
+        # Start worker for the queue if not already running
+        job_executor.job_queue.start_worker(queue)
+
+        result = {
+            'name': name,
+            'action': 'define',
+            'queue': queue,
+            'success': True
+        }
+
+        return result
+
+    def _execute_dispatch(self, node: JobNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Dispatch a job to the queue."""
+        name = node.name
+
+        # Get job_executor from runtime (same as legacy code)
+        job_executor = self._runtime.job_executor
+
+        # Build params from job params
+        params = {}
+        for param in node.params:
+            param_value = getattr(param, 'default', None)
+            if param.name in context:
+                param_value = context[param.name]
+            # If param has value attribute, resolve it
+            if hasattr(param, 'value') and param.value:
+                param_value = self.apply_databinding(param.value, context)
+            params[param.name] = param_value
+
+        # Dispatch job to queue
+        job_id = job_executor.job_queue.dispatch(
+            name=name,
+            queue=node.queue,
+            params=params,
+            delay=node.delay,
+            priority=node.priority,
+            attempts=node.attempts,
+            backoff=node.backoff
+        )
+
+        result = {
+            'job_id': job_id,
+            'name': name,
+            'action': 'dispatch',
+            'queue': node.queue,
+            'status': 'queued',
+            'success': True
+        }
+
+        return result
+
+    def _execute_batch(self, node: JobNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Dispatch multiple jobs as a batch."""
+        name = node.name
+
+        # Get job_executor from runtime (same as legacy code)
+        job_executor = self._runtime.job_executor
+
+        # Get tasks from node
+        tasks = node.tasks if node.tasks else []
+
+        # Resolve tasks
+        resolved_tasks = []
+        for task in tasks:
+            resolved_task = {}
+            for key, value in task.items():
+                if isinstance(value, str):
+                    resolved_task[key] = self.apply_databinding(value, context)
+                else:
+                    resolved_task[key] = value
+            resolved_tasks.append(resolved_task)
+
+        # Dispatch batch
+        job_ids = []
+        for task in resolved_tasks:
+            job_id = job_executor.job_queue.dispatch(
+                name=name,
+                queue=node.queue,
+                params=task,
+                priority=node.priority
+            )
+            job_ids.append(job_id)
+
+        result = {
+            'job_ids': job_ids,
+            'name': name,
+            'action': 'batch',
+            'queue': node.queue,
+            'count': len(job_ids),
+            'success': True
+        }
+
+        return result
+
+    def _param_to_dict(self, param) -> Dict:
+        """Convert param node to dict."""
+        return {
+            'name': param.name,
+            'type': getattr(param, 'type', 'string'),
+            'required': getattr(param, 'required', False),
+            'default': getattr(param, 'default', None)
+        }

quantum/runtime/executors/jobs/schedule_executor.py

@@ -0,0 +1,132 @@
+"""
+Schedule Executor - Execute q:schedule statements
+
+Handles scheduled task execution (cron-like).
+"""
+
+import logging
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import ScheduleNode
+
+logger = logging.getLogger(__name__)
+
+
+def schedule_info_to_dict(info) -> Dict[str, Any]:
+    """Convert a ScheduleInfo dataclass to a template-friendly dict."""
+    def _iso(value):
+        return value.isoformat() if hasattr(value, 'isoformat') else value
+
+    return {
+        'name': info.name,
+        'triggerType': info.trigger_type,
+        'triggerInfo': info.trigger_info,
+        'nextRun': _iso(info.next_run),
+        'enabled': info.enabled,
+        'runCount': info.run_count,
+        'lastRun': _iso(info.last_run),
+        'lastError': info.last_error,
+    }
+
+
+class ScheduleExecutor(BaseExecutor):
+    """
+    Executor for q:schedule statements.
+
+    Supports:
+    - Interval-based scheduling (30s, 5m, 1h, 1d)
+    - Cron expression scheduling
+    - One-time scheduled execution
+    - Timezone support
+    - Retry configuration
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [ScheduleNode]
+
+    def execute(self, node: ScheduleNode, exec_context) -> Any:
+        """
+        Execute schedule management.
+
+        Args:
+            node: ScheduleNode with schedule configuration
+            exec_context: Execution context
+
+        Returns:
+            Schedule operation result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Execute based on action
+            if node.action == 'run':
+                result = self._execute_run(node, context, exec_context)
+            elif node.action == 'pause':
+                result = self._execute_pause(node.name)
+            elif node.action == 'resume':
+                result = self._execute_resume(node.name)
+            elif node.action == 'delete':
+                result = self._execute_delete(node.name)
+            else:
+                raise ExecutorError(f"Unknown schedule action: {node.action}")
+
+            # Store result
+            exec_context.set_variable(f"{node.name}_schedule", result, scope="component")
+
+            return result
+
+        except ExecutorError:
+            raise
+        except Exception as e:
+            raise ExecutorError(f"Schedule execution error: {e}")
+
+    @property
+    def _schedule_service(self):
+        """The real scheduling service.
+
+        There is no services.scheduler — schedules live on the JobExecutor
+        facade as services.job_executor.schedule (a ScheduleService).
+        """
+        return self.services.job_executor.schedule
+
+    def _execute_run(self, node: ScheduleNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Create/update a scheduled task."""
+        interval = self.apply_databinding(node.interval, context) if node.interval else None
+        cron = self.apply_databinding(node.cron, context) if node.cron else None
+        at = self.apply_databinding(node.at, context) if node.at else None
+
+        body = node.body
+
+        def run_scheduled_body():
+            """Runs on the scheduler thread — must not raise into APScheduler."""
+            try:
+                return self.run_body_in_child_context(body)
+            except Exception as exc:  # noqa: BLE001 - reported via ScheduleInfo.last_error
+                logger.error(f"Scheduled task '{node.name}' failed: {exc}")
+                raise
+
+        info = self._schedule_service.add_schedule(
+            name=node.name,
+            callback=run_scheduled_body,
+            interval=interval,
+            cron=cron,
+            at=at,
+            timezone=node.timezone or 'UTC',
+            enabled=node.enabled,
+            overlap=node.overlap,
+        )
+
+        return schedule_info_to_dict(info)
+
+    def _execute_pause(self, name: str) -> Dict:
+        """Pause a scheduled task."""
+        return {'name': name, 'action': 'pause', 'success': self._schedule_service.pause_schedule(name)}
+
+    def _execute_resume(self, name: str) -> Dict:
+        """Resume a paused scheduled task."""
+        return {'name': name, 'action': 'resume', 'success': self._schedule_service.resume_schedule(name)}
+
+    def _execute_delete(self, name: str) -> Dict:
+        """Delete a scheduled task."""
+        return {'name': name, 'action': 'delete', 'success': self._schedule_service.remove_schedule(name)}

quantum/runtime/executors/jobs/thread_executor.py

@@ -0,0 +1,127 @@
+"""
+Thread Executor - Execute q:thread statements
+
+Handles async thread execution.
+"""
+
+import logging
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import ThreadNode
+
+logger = logging.getLogger(__name__)
+
+
+def thread_info_to_dict(info) -> Dict[str, Any]:
+    """Convert a ThreadInfo dataclass to a template-friendly dict."""
+    def _iso(value):
+        return value.isoformat() if hasattr(value, 'isoformat') else value
+
+    return {
+        'name': info.name,
+        'priority': info.priority,
+        'startedAt': _iso(info.started_at),
+        'status': info.status,
+        'timeout': info.timeout,
+        'result': info.result,
+        'error': info.error,
+    }
+
+
+class ThreadExecutor(BaseExecutor):
+    """
+    Executor for q:thread statements.
+
+    Supports:
+    - Async thread execution
+    - Thread join (wait for completion)
+    - Thread termination
+    - Priority levels
+    - Timeout and callbacks
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [ThreadNode]
+
+    def execute(self, node: ThreadNode, exec_context) -> Any:
+        """
+        Execute thread management.
+
+        Args:
+            node: ThreadNode with thread configuration
+            exec_context: Execution context
+
+        Returns:
+            Thread operation result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Execute based on action
+            if node.action == 'run':
+                result = self._execute_run(node, context, exec_context)
+            elif node.action == 'join':
+                result = self._execute_join(node.name)
+            elif node.action == 'terminate':
+                result = self._execute_terminate(node.name)
+            else:
+                raise ExecutorError(f"Unknown thread action: {node.action}")
+
+            # Store result
+            exec_context.set_variable(f"{node.name}_thread", result, scope="component")
+
+            return result
+
+        except ExecutorError:
+            raise
+        except Exception as e:
+            raise ExecutorError(f"Thread execution error: {e}")
+
+    @property
+    def _thread_service(self):
+        """The real threading service.
+
+        There is no services.threading — threads live on the JobExecutor
+        facade as services.job_executor.thread (a ThreadService).
+        """
+        return self.services.job_executor.thread
+
+    def _execute_run(self, node: ThreadNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Start a new thread."""
+        body = node.body
+        # Snapshot the caller's variables: the thread runs after this
+        # component's own execution has moved on.
+        snapshot = dict(context)
+
+        def run_thread_body():
+            try:
+                return self.run_body_in_child_context(body, snapshot)
+            except Exception as exc:  # noqa: BLE001 - surfaced via ThreadInfo.error
+                logger.error(f"Thread '{node.name}' failed: {exc}")
+                raise
+
+        info = self._thread_service.run_thread(
+            name=node.name,
+            callback=run_thread_body,
+            priority=node.priority or 'normal',
+            timeout=node.timeout,
+        )
+
+        return thread_info_to_dict(info)
+
+    def _execute_join(self, name: str) -> Dict:
+        """Wait for thread to complete."""
+        result = self._thread_service.join_thread(name)
+        info = self._thread_service.get_thread(name)
+        joined = thread_info_to_dict(info) if info else {'name': name}
+        joined['result'] = result
+        return joined
+
+    def _execute_terminate(self, name: str) -> Dict:
+        """Terminate a running thread."""
+        return {
+            'name': name,
+            'action': 'terminate',
+            'success': self._thread_service.terminate_thread(name),
+        }

quantum/runtime/executors/messaging/__init__.py

@@ -0,0 +1,17 @@
+"""
+Messaging Executors
+
+Executors for messaging operations: websocket, message, queue, subscribe.
+"""
+
+from .websocket_executor import WebSocketExecutor, WebSocketSendExecutor, WebSocketCloseExecutor
+from .message_executor import MessageExecutor, SubscribeExecutor
+from .queue_executor import QueueExecutor
+
+__all__ = [
+    'WebSocketExecutor', 'WebSocketSendExecutor', 'WebSocketCloseExecutor',
+    'MessageExecutor', 'SubscribeExecutor', 'QueueExecutor'
+]
+from quantum.runtime.executors.messaging.message_ack_executor import (
+    MessageAckExecutor, MessageNackExecutor,
+)

quantum/runtime/executors/messaging/message_ack_executor.py

@@ -0,0 +1,51 @@
+"""
+Executors for q:messageAck and q:messageNack.
+
+These nodes parsed and produced an AST node with NO executor registered, so
+inside a `<q:subscribe ack="manual">` handler they did nothing. With manual
+acknowledgement the broker waits for an ack that could never arrive, so the
+message was redelivered forever — the audit's most-reported critical, and the
+worst kind of silent failure: an infinite loop of side effects.
+
+MessageQueueService already had ack() and nack(); nothing called them.
+"""
+
+from typing import Any, List, Type
+
+from quantum.core.ast_nodes import MessageAckNode, MessageNackNode
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+
+
+class MessageAckExecutor(BaseExecutor):
+    """Executor for q:messageAck — acknowledge the message being handled."""
+
+    @property
+    def handles(self) -> List[Type]:
+        return [MessageAckNode]
+
+    def execute(self, node: MessageAckNode, exec_context) -> Any:
+        try:
+            self.services.message_queue.ack()
+            return {'acknowledged': True}
+        except Exception as e:
+            raise ExecutorError(f"q:messageAck failed: {e}")
+
+
+class MessageNackExecutor(BaseExecutor):
+    """Executor for q:messageNack — reject the message being handled."""
+
+    @property
+    def handles(self) -> List[Type]:
+        return [MessageNackNode]
+
+    def execute(self, node: MessageNackNode, exec_context) -> Any:
+        # requeue defaults to True: rejecting without requeueing silently
+        # drops the message, which should be the explicit choice.
+        requeue = getattr(node, 'requeue', True)
+        if isinstance(requeue, str):
+            requeue = requeue.strip().lower() not in ('false', '0', 'no', 'off')
+        try:
+            self.services.message_queue.nack(requeue=bool(requeue))
+            return {'acknowledged': False, 'requeued': bool(requeue)}
+        except Exception as e:
+            raise ExecutorError(f"q:messageNack failed: {e}")

quantum/runtime/executors/messaging/message_executor.py

@@ -0,0 +1,174 @@
+"""
+Message Executor - Execute q:message statements
+
+Handles message queue publish/send/request operations.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import MessageNode, SubscribeNode
+
+
+class MessageExecutor(BaseExecutor):
+    """
+    Executor for q:message statements.
+
+    Supports:
+    - Pub/Sub (publish to topic)
+    - Direct queue send
+    - Request/reply pattern
+    - Message headers
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [MessageNode]
+
+    def execute(self, node: MessageNode, exec_context) -> Any:
+        """
+        Execute message publish/send.
+
+        Args:
+            node: MessageNode with message configuration
+            exec_context: Execution context
+
+        Returns:
+            Message operation result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve body
+            body = None
+            if node.body:
+                body = self.apply_databinding(node.body, context)
+
+            # Resolve headers
+            headers = {}
+            for header in node.headers:
+                header_name = header.name
+                header_value = self.apply_databinding(header.value, context)
+                headers[header_name] = header_value
+
+            # Resolve target
+            topic = None
+            queue = None
+            if node.topic:
+                topic = self.apply_databinding(node.topic, context)
+            if node.queue:
+                queue = self.apply_databinding(node.queue, context)
+
+            # Execute based on message type
+            if node.type == 'publish':
+                result = self.services.message_queue.publish(
+                    topic=topic,
+                    body=body,
+                    headers=headers
+                )
+            elif node.type == 'send':
+                result = self.services.message_queue.send(
+                    queue=queue,
+                    body=body,
+                    headers=headers
+                )
+            elif node.type == 'request':
+                timeout = int(node.timeout) if node.timeout else 30000
+                result = self.services.message_queue.request(
+                    queue=queue,
+                    body=body,
+                    headers=headers,
+                    timeout=timeout
+                )
+            else:
+                raise ExecutorError(f"Unknown message type: {node.type}")
+
+            # Store result
+            if node.name:
+                exec_context.set_variable(node.name, result, scope="component")
+
+            return result
+
+        except Exception as e:
+            if node.name:
+                exec_context.set_variable(node.name, {
+                    'success': False,
+                    'error': str(e)
+                }, scope="component")
+            raise ExecutorError(f"Message operation error: {e}")
+
+
+class SubscribeExecutor(BaseExecutor):
+    """
+    Executor for q:subscribe statements.
+
+    Subscribes to topics or queues and handles incoming messages.
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [SubscribeNode]
+
+    def execute(self, node: SubscribeNode, exec_context) -> Any:
+        """
+        Execute subscription setup.
+
+        Args:
+            node: SubscribeNode with subscription configuration
+            exec_context: Execution context
+
+        Returns:
+            Subscription info dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve topics/queue
+            topics = []
+            if node.topic:
+                topics = [self.apply_databinding(node.topic, context)]
+            elif node.topics:
+                topics_str = self.apply_databinding(node.topics, context)
+                topics = [t.strip() for t in topics_str.split(',')]
+
+            queue = None
+            if node.queue:
+                queue = self.apply_databinding(node.queue, context)
+
+            # MessageQueueService.subscribe() takes a single `handler`
+            # callable, not a handlers config dict, and `topics` as a
+            # comma-separated string.
+            on_message_body = node.on_message
+            on_error_body = node.on_error
+
+            def handle_message(message):
+                payload = message if isinstance(message, dict) else {'message': message}
+                try:
+                    return self.run_body_in_child_context(on_message_body, payload)
+                except Exception as exc:  # noqa: BLE001 - routed to on_error body
+                    if on_error_body:
+                        return self.run_body_in_child_context(
+                            on_error_body, {**payload, 'error': str(exc)}
+                        )
+                    raise
+
+            # Create subscription
+            result = self.services.message_queue.subscribe(
+                name=node.name,
+                topics=','.join(topics) if topics else None,
+                queue=queue,
+                handler=handle_message,
+                ack=node.ack,
+                prefetch=node.prefetch,
+            )
+
+            # Store subscription reference
+            exec_context.set_variable(node.name, result, scope="component")
+
+            return result
+
+        except Exception as e:
+            exec_context.set_variable(node.name, {
+                'active': False,
+                'error': str(e)
+            }, scope="component")
+            raise ExecutorError(f"Subscription error: {e}")