@bluefly/openstandardagents 0.3.1 → 0.3.3

package/spec/v0.3.2/adapters/symfony.md

@@ -0,0 +1,659 @@
+# Symfony Messenger OSSA Runtime Adapter
+
+## Overview
+
+The Symfony Messenger OSSA Runtime Adapter enables execution of OSSA Task, Workflow, and Agent manifests using Symfony Messenger's asynchronous message queue system. This provides enterprise-grade async processing with support for multiple transports.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Symfony Application                          │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
+│  │  OSSA Manifest  │    │        OSSA Message Handler         │ │
+│  │  (Task/Workflow)│───▶│  • OSSATaskMessageHandler           │ │
+│  └─────────────────┘    │  • OSSAWorkflowMessageHandler       │ │
+│                         │  • OSSAAgentMessageHandler          │ │
+│                         └──────────────┬──────────────────────┘ │
+│                                        │                        │
+│                         ┌──────────────▼──────────────────────┐ │
+│                         │      Symfony Messenger Bus          │ │
+│                         └──────────────┬──────────────────────┘ │
+│                                        │                        │
+│  ┌──────────────┬──────────────┬───────┴─────┬──────────────┐  │
+│  │    AMQP      │    Redis     │  Doctrine   │     SQS      │  │
+│  │  Transport   │  Transport   │  Transport  │  Transport   │  │
+│  └──────┬───────┴──────┬───────┴──────┬──────┴──────┬───────┘  │
+├─────────┼──────────────┼──────────────┼─────────────┼──────────┤
+│  ┌──────▼───────┐ ┌────▼────┐ ┌───────▼──────┐ ┌────▼────┐     │
+│  │  RabbitMQ    │ │  Redis  │ │   Database   │ │   SQS   │     │
+│  └──────────────┘ └─────────┘ └──────────────┘ └─────────┘     │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────▼─────────┐
+                    │   Messenger Worker │
+                    │   messenger:consume│
+                    └─────────┬─────────┘
+                              │
+                    ┌─────────▼─────────┐
+                    │   Task Execution  │
+                    └───────────────────┘
+```
+
+## Installation
+
+```bash
+composer require ossa/symfony-adapter
+```
+
+## Configuration
+
+### Bundle Configuration (`config/packages/ossa.yaml`)
+
+```yaml
+ossa:
+  # Manifest discovery
+  manifest_paths:
+    - '%kernel.project_dir%/config/ossa'
+    - '%kernel.project_dir%/src/*/Resources/ossa'
+
+  # Default runtime settings
+  defaults:
+    timeout_seconds: 300
+    retry_attempts: 3
+    retry_delay_ms: 1000
+
+  # Observability
+  observability:
+    enabled: true
+    exporter: otel
+    endpoint: '%env(OTEL_EXPORTER_ENDPOINT)%'
+```
+
+### Messenger Configuration (`config/packages/messenger.yaml`)
+
+```yaml
+framework:
+  messenger:
+    transports:
+      # OSSA Task transport
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          queue_name: ossa_tasks
+        retry_strategy:
+          max_retries: 3
+          delay: 1000
+          multiplier: 2
+
+      # OSSA Workflow transport
+      ossa_workflows:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          queue_name: ossa_workflows
+        retry_strategy:
+          max_retries: 5
+          delay: 2000
+
+      # OSSA Agent transport (higher priority)
+      ossa_agents:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          queue_name: ossa_agents
+
+    routing:
+      'OSSA\Messenger\Message\OSSATaskMessage': ossa_tasks
+      'OSSA\Messenger\Message\OSSAWorkflowMessage': ossa_workflows
+      'OSSA\Messenger\Message\OSSAAgentMessage': ossa_agents
+```
+
+## Message Types
+
+### OSSATaskMessage
+
+Wraps a `kind: Task` manifest for async execution:
+
+```php
+<?php
+
+namespace OSSA\Messenger\Message;
+
+final class OSSATaskMessage
+{
+    public function __construct(
+        private readonly string $manifestPath,
+        private readonly array $input,
+        private readonly ?string $correlationId = null,
+        private readonly array $metadata = [],
+    ) {}
+
+    public function getManifestPath(): string
+    {
+        return $this->manifestPath;
+    }
+
+    public function getInput(): array
+    {
+        return $this->input;
+    }
+
+    public function getCorrelationId(): ?string
+    {
+        return $this->correlationId;
+    }
+
+    public function getMetadata(): array
+    {
+        return $this->metadata;
+    }
+}
+```
+
+### OSSAWorkflowMessage
+
+Wraps a `kind: Workflow` manifest with step orchestration:
+
+```php
+<?php
+
+namespace OSSA\Messenger\Message;
+
+final class OSSAWorkflowMessage
+{
+    public function __construct(
+        private readonly string $manifestPath,
+        private readonly array $input,
+        private readonly ?string $workflowInstanceId = null,
+        private readonly ?string $parentStepId = null,
+        private readonly array $context = [],
+    ) {}
+
+    // ... getters
+}
+```
+
+## Message Handlers
+
+### OSSATaskMessageHandler
+
+```php
+<?php
+
+namespace OSSA\Messenger\Handler;
+
+use OSSA\Messenger\Message\OSSATaskMessage;
+use OSSA\Runtime\TaskExecutor;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+#[AsMessageHandler]
+final class OSSATaskMessageHandler
+{
+    public function __construct(
+        private readonly TaskExecutor $executor,
+        private readonly ManifestLoader $manifestLoader,
+    ) {}
+
+    public function __invoke(OSSATaskMessage $message): void
+    {
+        $manifest = $this->manifestLoader->load($message->getManifestPath());
+
+        $result = $this->executor->execute($manifest, $message->getInput());
+
+        // Result is stored/emitted based on manifest observability settings
+    }
+}
+```
+
+### OSSAWorkflowMessageHandler
+
+```php
+<?php
+
+namespace OSSA\Messenger\Handler;
+
+use OSSA\Messenger\Message\OSSAWorkflowMessage;
+use OSSA\Messenger\Message\OSSATaskMessage;
+use OSSA\Runtime\WorkflowOrchestrator;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+use Symfony\Component\Messenger\MessageBusInterface;
+
+#[AsMessageHandler]
+final class OSSAWorkflowMessageHandler
+{
+    public function __construct(
+        private readonly WorkflowOrchestrator $orchestrator,
+        private readonly MessageBusInterface $bus,
+    ) {}
+
+    public function __invoke(OSSAWorkflowMessage $message): void
+    {
+        $workflow = $this->orchestrator->loadWorkflow($message->getManifestPath());
+
+        foreach ($workflow->getReadySteps($message->getContext()) as $step) {
+            if ($step->getKind() === 'Task') {
+                // Dispatch Task step as separate message
+                $this->bus->dispatch(new OSSATaskMessage(
+                    $step->getRef(),
+                    $step->getResolvedInput($message->getContext()),
+                    correlationId: $message->getWorkflowInstanceId(),
+                ));
+            }
+        }
+    }
+}
+```
+
+## Transport Support
+
+### AMQP (RabbitMQ)
+
+```yaml
+# .env
+MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
+
+# config/packages/messenger.yaml
+framework:
+  messenger:
+    transports:
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          exchange:
+            name: ossa
+            type: topic
+          queues:
+            ossa_tasks:
+              binding_keys:
+                - 'task.*'
+```
+
+### Redis
+
+```yaml
+# .env
+MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages
+
+# config/packages/messenger.yaml
+framework:
+  messenger:
+    transports:
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          stream: ossa_tasks
+          group: ossa_workers
+          consumer: worker_%hostname%
+```
+
+### Doctrine
+
+```yaml
+# .env
+MESSENGER_TRANSPORT_DSN=doctrine://default
+
+# config/packages/messenger.yaml
+framework:
+  messenger:
+    transports:
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          table_name: ossa_messenger_messages
+          queue_name: ossa_tasks
+```
+
+### Amazon SQS
+
+```yaml
+# .env
+MESSENGER_TRANSPORT_DSN=sqs://default?region=us-east-1
+
+# config/packages/messenger.yaml
+framework:
+  messenger:
+    transports:
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          queue_name: ossa-tasks
+          wait_time: 20
+          poll_timeout: 0.1
+```
+
+## Runtime Bindings
+
+Map OSSA capabilities to Symfony services:
+
+```yaml
+# config/packages/ossa.yaml
+ossa:
+  bindings:
+    send_email:
+      service: 'Symfony\Component\Mailer\MailerInterface'
+      method: send
+
+    http_request:
+      service: 'Symfony\Contracts\HttpClient\HttpClientInterface'
+      method: request
+
+    cache_get:
+      service: 'Symfony\Contracts\Cache\CacheInterface'
+      method: get
+
+    dispatch_event:
+      service: 'Symfony\Contracts\EventDispatcher\EventDispatcherInterface'
+      method: dispatch
+```
+
+## Example Task Manifest
+
+```yaml
+# config/ossa/tasks/send-email.yaml
+apiVersion: ossa/v0.3.3
+kind: Task
+metadata:
+  name: send-email-symfony
+  version: 1.0.0
+  labels:
+    runtime: symfony
+    transport: messenger
+
+spec:
+  execution:
+    type: deterministic
+    runtime: symfony
+    entrypoint: 'App\TaskHandler\SendEmailHandler::execute'
+    timeout_seconds: 30
+
+  capabilities:
+    - send_email
+    - render_template
+
+  input:
+    type: object
+    properties:
+      to:
+        type: string
+        format: email
+      subject:
+        type: string
+      template:
+        type: string
+      variables:
+        type: object
+    required:
+      - to
+      - subject
+      - template
+
+  output:
+    type: object
+    properties:
+      message_id:
+        type: string
+      sent_at:
+        type: string
+        format: date-time
+
+  error_handling:
+    on_error: retry
+    retry:
+      max_attempts: 3
+      backoff_strategy: exponential
+
+runtime:
+  type: symfony
+  bindings:
+    send_email:
+      service: '@Symfony\Component\Mailer\MailerInterface'
+    render_template:
+      service: '@Twig\Environment'
+
+  messenger:
+    transport: ossa_tasks
+    routing_key: email.send
+```
+
+## Example Workflow Manifest
+
+```yaml
+# config/ossa/workflows/user-onboarding.yaml
+apiVersion: ossa/v0.3.3
+kind: Workflow
+metadata:
+  name: user-onboarding-symfony
+  version: 1.0.0
+
+spec:
+  triggers:
+    - type: event
+      source: symfony.event_dispatcher
+      event: user.registered
+
+  inputs:
+    type: object
+    properties:
+      user_id:
+        type: string
+      email:
+        type: string
+    required:
+      - user_id
+      - email
+
+  steps:
+    - id: validate_email
+      kind: Task
+      ref: ./tasks/validate-email.yaml
+      input:
+        email: '${{ workflow.input.email }}'
+
+    - id: create_profile
+      kind: Task
+      ref: ./tasks/create-profile.yaml
+      input:
+        user_id: '${{ workflow.input.user_id }}'
+      depends_on:
+        - validate_email
+
+    - id: send_welcome_email
+      kind: Task
+      ref: ./tasks/send-email.yaml
+      input:
+        to: '${{ workflow.input.email }}'
+        template: welcome
+      depends_on:
+        - create_profile
+
+runtime:
+  type: symfony
+  messenger:
+    transport: ossa_workflows
+    step_dispatch:
+      transport: ossa_tasks
+      parallel_execution: true
+```
+
+## Worker Deployment
+
+### Docker
+
+```dockerfile
+FROM php:8.2-cli
+
+# Install dependencies
+RUN docker-php-ext-install pdo_mysql pcntl
+
+# Copy application
+COPY . /app
+WORKDIR /app
+
+# Run worker
+CMD ["php", "bin/console", "messenger:consume", "ossa_tasks", "ossa_workflows", "-vv"]
+```
+
+### Kubernetes
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ossa-worker
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: ossa-worker
+  template:
+    spec:
+      containers:
+        - name: worker
+          image: myapp:latest
+          command: ["php", "bin/console", "messenger:consume"]
+          args:
+            - "ossa_tasks"
+            - "ossa_workflows"
+            - "--limit=100"
+            - "--time-limit=3600"
+          resources:
+            requests:
+              memory: "256Mi"
+              cpu: "250m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+```
+
+## Observability
+
+### OpenTelemetry Integration
+
+```php
+<?php
+// Automatic span creation for message handling
+
+use OpenTelemetry\API\Trace\TracerInterface;
+
+#[AsMessageHandler]
+final class OSSATaskMessageHandler
+{
+    public function __construct(
+        private readonly TracerInterface $tracer,
+    ) {}
+
+    public function __invoke(OSSATaskMessage $message): void
+    {
+        $span = $this->tracer->spanBuilder('ossa.task.execute')
+            ->setAttribute('ossa.task.name', $message->getManifestPath())
+            ->setAttribute('ossa.correlation_id', $message->getCorrelationId())
+            ->startSpan();
+
+        try {
+            // Execute task
+        } finally {
+            $span->end();
+        }
+    }
+}
+```
+
+### Prometheus Metrics
+
+```yaml
+# Exposed at /metrics
+ossa_task_messages_total{task="send-email", status="success"} 1234
+ossa_task_duration_seconds{task="send-email"} 0.45
+ossa_workflow_steps_completed{workflow="user-onboarding"} 567
+ossa_messenger_queue_size{queue="ossa_tasks"} 12
+```
+
+## Error Handling
+
+### Dead Letter Queue
+
+```yaml
+framework:
+  messenger:
+    transports:
+      ossa_tasks:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        failure_transport: ossa_failed
+
+      ossa_failed:
+        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+        options:
+          queue_name: ossa_failed
+```
+
+### Custom Error Handler
+
+```php
+<?php
+
+namespace App\EventSubscriber;
+
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\Messenger\Event\WorkerMessageFailedEvent;
+
+class OSSAFailureSubscriber implements EventSubscriberInterface
+{
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            WorkerMessageFailedEvent::class => 'onMessageFailed',
+        ];
+    }
+
+    public function onMessageFailed(WorkerMessageFailedEvent $event): void
+    {
+        $message = $event->getEnvelope()->getMessage();
+
+        if ($message instanceof OSSATaskMessage) {
+            // Log, alert, or handle failure
+        }
+    }
+}
+```
+
+## CLI Commands
+
+```bash
+# Validate OSSA manifest
+php bin/console ossa:validate config/ossa/tasks/my-task.yaml
+
+# Dispatch a task
+php bin/console ossa:dispatch task my-task --input='{"key": "value"}'
+
+# Start a workflow
+php bin/console ossa:dispatch workflow user-onboarding --input='{"user_id": "123"}'
+
+# List pending messages
+php bin/console messenger:stats
+
+# Consume messages
+php bin/console messenger:consume ossa_tasks ossa_workflows -vv
+
+# Retry failed messages
+php bin/console messenger:failed:retry --all
+```
+
+## OSSA Compliance
+
+This adapter implements OSSA v0.3.3 specification:
+
+- ✅ Task execution with deterministic semantics
+- ✅ Workflow orchestration with step dependencies
+- ✅ Async execution via Symfony Messenger
+- ✅ Multiple transport support (AMQP, Redis, Doctrine, SQS)
+- ✅ Capability abstraction and runtime bindings
+- ✅ OpenTelemetry observability
+- ✅ Error handling with retry strategies
+- ✅ Dead letter queue support
+
+## Related
+
+- [OSSA Specification v0.3.3](../README.md)
+- [Drupal Adapter](./drupal.md)
+- [Node.js Adapter](./nodejs.md)
+- [Capability Registry](../capability-schema.md)