Am Driver Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require application-manager-tools/am-driver
   

2. Configure Symfony Bundle (if using Symfony):

   • Add to config/bundles.php:

     ApplicationManagerTools\AmDriver\Bridge\Symfony\AmDriverBundle::class => ['all' => true],
     

   • Set environment variables in .env.local (e.g., AM_DRIVER_AM_BASE_URL, AM_DRIVER_SOURCE=captain-learning).
   • Configure in config/packages/am_driver.yaml:

     am_driver:
         route_prefix: am
         consumption_webhook_token: '%env(AM_DRIVER_CONSUMPTION_WEBHOOK_TOKEN)%'
         orchestration_command_token: '%env(AM_DRIVER_ORCHESTRATION_COMMAND_TOKEN)%'
     

3. Import Routes Add to config/routes/am_driver.yaml:

   am_driver:
       resource: '@AmDriverBundle/Resources/config/routes.yaml'
   

4. Implement a Handler Create a CreateInstanceHandler for orchestration commands:

   use ApplicationManagerTools\AmDriver\Core\Contract\CreateInstanceHandlerInterface;
   use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCommand;
   
   final class MyCreateInstanceHandler implements CreateInstanceHandlerInterface {
       public function handle(OrchestrationCommand $command): void {
           // Logic to create tenant/instance (e.g., provision DB, storage)
       }
   }
   

   Tag it in services.yaml:

   services:
       App\Handler\MyCreateInstanceHandler:
           tags: ['am_driver.create_instance_handler']
   

5. Test Locally Start the receptacle server:

   vendor/bin/am-driver serve --port=8099 --token-command=dev-command-token
   

   Simulate an orchestration command:

   vendor/bin/am-driver orchestration:simulate create --token=dev-command-token
   

First Use Case: Handling CREATE_INSTANCE

1. Trigger: AM sends a CREATE_INSTANCE command to your /am/orchestration/commands endpoint.
2. Process: The CreateInstanceHandler receives the OrchestrationCommand DTO with:
   • tenantId: Unique identifier for the tenant.
   • integrationInstanceId: (New in v0.0.16) Unique identifier for the integration instance (useful for multi-tenancy or multi-instance setups).
   • parameters: Custom payload (e.g., {"storage_gb": 10, "region": "eu-west-1"}).
3. Action: Implement tenant provisioning logic (e.g., create a database, allocate storage).
4. Callback: AM expects a callback to /am/orchestration/commands/callbacks with the result (success/failure).
   • New in v0.0.16: Include integrationInstanceId in the callback response for better traceability.

Where to Look First

• Documentation:
  • OpenAPI Spec for API contracts (check for updates in integrationInstanceId fields).
  • Integration Guide for technical setup.
  • Manual for Integrators for human-readable workflows.
• Code:
  • src/Core/Contract/ for handler interfaces (e.g., CreateInstanceHandlerInterface).
  • src/Core/Dto/ for data transfer objects (e.g., OrchestrationCommand now includes integrationInstanceId).
  • src/Bridge/Symfony/ for Symfony-specific wiring.
• CLI:
  • Use vendor/bin/am-driver serve for local testing.
  • Simulate commands with orchestration:simulate (ensure integrationInstanceId is included in test payloads).

Implementation Patterns

Workflows

1. Orchestration Command Handling

• Pattern: Use the Handler Pattern for each orchestration command type.
  • Implement CreateInstanceHandlerInterface, StopInstanceHandlerInterface, etc.
  • Tag services with am_driver.{command}_handler (e.g., am_driver.create_instance_handler).
• Example:

  // Handle START_INSTANCE with custom logic, now using integrationInstanceId
  final class MyStartInstanceHandler implements StartInstanceHandlerInterface {
      public function handle(OrchestrationCommand $command): void {
          $this->tenantService->startTenant(
              tenantId: $command->tenantId,
              integrationInstanceId: $command->integrationInstanceId // New field
          );
          $this->logger->info(
              "Started tenant {$command->tenantId} (instance: {$command->integrationInstanceId})"
          );
      }
  }
  

• Validation: The bundle automatically validates incoming commands against the OpenAPI spec (now includes integrationInstanceId).

2. Consumption Webhook Processing

• Pattern: Use the ConsumptionWebhookReceiver to process inbound consumption events.
  • AM sends webhooks to /am/consumption/webhook with a consumption_webhook_token.
  • Parse the payload (e.g., tenantId, resourceKey, value, integrationInstanceId).
• Example:

  use ApplicationManagerTools\AmDriver\Core\Contract\ConsumptionWebhookReceiverInterface;
  
  final class MyConsumptionWebhookReceiver implements ConsumptionWebhookReceiverInterface {
      public function receive(
          string $tenantId,
          string $resourceKey,
          float $value,
          ?string $integrationInstanceId = null // New optional field
      ): void {
          $this->consumptionStore->record(
              tenantId: $tenantId,
              integrationInstanceId: $integrationInstanceId,
              resourceKey: $resourceKey,
              value: $value
          );
      }
  }
  

3. Operational State Push

• Pattern: Use the OperationalStatePublisher to push state updates to AM.
  • Call $publisher->pushOperationalState($tenantId, $state, $integrationInstanceId).
  • Example states: RUNNING, STOPPED, FAILED.
• Example:

  $publisher = $container->get('am_driver.operational_state_publisher');
  $publisher->pushOperationalState(
      tenantId: $tenantId,
      state: 'STOPPED',
      integrationInstanceId: $integrationInstanceId // New optional field
  );
  

4. Resource Consumption Publishing

• Pattern: Use the ConsumptionPublisher to push resource usage to AM.
  • Call $publisher->pushResourceConsumption($tenantId, 'storage_gb', 5.2, $integrationInstanceId).
  • AM uses this data for billing and quotas.
• Example:

  $publisher = $container->get('am_driver.consumption_publisher');
  $publisher->pushResourceConsumption(
      tenantId: $tenantId,
      resourceKey: 'proof_storage_mo',
      value: 12.5,
      integrationInstanceId: $integrationInstanceId // New optional field
  );
  

Integration Tips

Symfony-Specific

• Dependency Injection: The bundle auto-configures services like:
  • am_driver.orchestration_command_processor
  • am_driver.operational_state_publisher
  • am_driver.consumption_publisher
• Routing: All AM routes are prefixed (e.g., /am/orchestration/commands). Customize with route_prefix in config.
• Security: Exclude AM routes from global auth in security.yaml:

  access_control:
      - { path: ^/am/, roles: PUBLIC_ACCESS }
  

Framework-Agnostic Core

• Manual Wiring: For non-Symfony apps, instantiate core components:

  $client = new AmApiClient($amBaseUrl, $orchestrationCommandToken);
  $processor = new OrchestrationCommandProcessor(
      $client,
      new CreateInstanceHandler(),
      new StopInstanceHandler()
  );
  $processor->process($command);
  

• HTTP Server: Use AmDriverReceptacle to expose endpoints:

  $receptacle = new AmDriverReceptacle(
      new CreateInstanceHandler(),
      new ConsumptionWebhookReceiver()
  );
  $server = new SwooleHttpServer($receptacle);
  $server->start();
  

Testing

• CLI Simulation: Test orchestration commands locally with integrationInstanceId:

  vendor/bin/am-driver orchestration:simulate create \
      --token=dev-command-token \
      --integration-instance-id=test-instance-123
  

• Swagger UI: Inspect the OpenAPI spec at http://localhost:18098 (default port) for updated fields.
• **Mock AM