K#3532 Contrat

README.md

@@ -78,13 +78,15 @@ am_driver:
 
 ```php
 use ApplicationManagerTools\AmDriver\Core\Contract\CreateInstanceHandlerInterface;
+use ApplicationManagerTools\AmDriver\Core\Dto\CreateInstanceHandlerResult;
 use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCommand;
 
 final class MyCreateInstanceHandler implements CreateInstanceHandlerInterface
 {
-    public function handle(OrchestrationCommand $command): void
+    public function handle(OrchestrationCommand $command): CreateInstanceHandlerResult
     {
         // provision tenant / DB / storage
+        return new CreateInstanceHandlerResult('https://tenant.example/login');
     }
 }
 ```

docs/openapi/am-client-v1.yaml

@@ -108,6 +108,7 @@ paths:
                 value:
                   idempotencyKey: am_ins_10000000-0000-4000-8000-000000000001:create_instance:v1
                   status: SUCCEEDED
+                  location: https://tenant.example/login
               failed:
                 value:
                   idempotencyKey: am_ins_10000000-0000-4000-8000-000000000001:create_instance:v1
@@ -178,3 +179,8 @@ components:
         message:
           type: string
           description: Détail d’échec (optionnel).
+        location:
+          type: string
+          format: uri
+          nullable: true
+          description: URL d'accès tenant (CREATE_INSTANCE SUCCEEDED).

src/Bridge/Console/Command/CallbackSendCommand.php

@@ -26,7 +26,8 @@ protected function configure(): void
             ->addOption('token', null, InputOption::VALUE_REQUIRED, 'X-Orchestration-Callback-Token')
             ->addOption('idempotency-key', null, InputOption::VALUE_REQUIRED, 'idempotencyKey')
             ->addOption('status', null, InputOption::VALUE_REQUIRED, 'SUCCEEDED|FAILED|RETRYABLE_FAILURE', 'SUCCEEDED')
-            ->addOption('message', null, InputOption::VALUE_OPTIONAL, 'Optional message');
+            ->addOption('message', null, InputOption::VALUE_OPTIONAL, 'Optional message')
+            ->addOption('location', null, InputOption::VALUE_OPTIONAL, 'Optional tenant access URL (CREATE_INSTANCE SUCCEEDED)');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
@@ -50,6 +51,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             (string) $input->getOption('idempotency-key'),
             CallbackStatus::fromString((string) $input->getOption('status')),
             $input->getOption('message') ? (string) $input->getOption('message') : null,
+            $input->getOption('location') ? (string) $input->getOption('location') : null,
         );
 
         $response = $client->reportOrchestrationCallback($request);

src/Core/Cli/InMemory/LoggingCreateInstanceHandler.php

@@ -5,6 +5,7 @@
 namespace ApplicationManagerTools\AmDriver\Core\Cli\InMemory;
 
 use ApplicationManagerTools\AmDriver\Core\Contract\CreateInstanceHandlerInterface;
+use ApplicationManagerTools\AmDriver\Core\Dto\CreateInstanceHandlerResult;
 use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCommand;
 
 final class LoggingCreateInstanceHandler implements CreateInstanceHandlerInterface
@@ -17,8 +18,10 @@ public function __construct(CommandCallLog $log)
         $this->log = $log;
     }
 
-    public function handle(OrchestrationCommand $command): void
+    public function handle(OrchestrationCommand $command): CreateInstanceHandlerResult
     {
         $this->log->add('CREATE_INSTANCE', $command);
+
+        return new CreateInstanceHandlerResult();
     }
 }

src/Core/Contract/CreateInstanceHandlerInterface.php

@@ -4,9 +4,10 @@
 
 namespace ApplicationManagerTools\AmDriver\Core\Contract;
 
+use ApplicationManagerTools\AmDriver\Core\Dto\CreateInstanceHandlerResult;
 use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCommand;
 
 interface CreateInstanceHandlerInterface
 {
-    public function handle(OrchestrationCommand $command): void;
+    public function handle(OrchestrationCommand $command): CreateInstanceHandlerResult;
 }

src/Core/Dto/CreateInstanceHandlerResult.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ApplicationManagerTools\AmDriver\Core\Dto;
+
+final class CreateInstanceHandlerResult
+{
+    /** @var string|null */
+    private $instanceLocation;
+
+    public function __construct(?string $instanceLocation = null)
+    {
+        $this->instanceLocation = $instanceLocation;
+    }
+
+    public function instanceLocation(): ?string
+    {
+        return $this->instanceLocation;
+    }
+}

src/Core/Dto/OrchestrationCallbackRequest.php

@@ -6,6 +6,7 @@
 
 use ApplicationManagerTools\AmDriver\Core\Orchestration\CallbackStatus;
 use ApplicationManagerTools\AmDriver\Core\Validation\JsonPayloadValidator;
+use InvalidArgumentException;
 
 final class OrchestrationCallbackRequest
 {
@@ -18,11 +19,19 @@ final class OrchestrationCallbackRequest
     /** @var string|null */
     private $message;
 
-    public function __construct(string $idempotencyKey, CallbackStatus $status, ?string $message = null)
-    {
+    /** @var string|null */
+    private $location;
+
+    public function __construct(
+        string $idempotencyKey,
+        CallbackStatus $status,
+        ?string $message = null,
+        ?string $location = null
+    ) {
         $this->idempotencyKey = $idempotencyKey;
         $this->status = $status;
         $this->message = $message;
+        $this->location = $location;
     }
 
     /**
@@ -35,11 +44,24 @@ public static function fromArray(array $data): self
         JsonPayloadValidator::requireNonEmptyString($data, 'status');
 
         $message = isset($data['message']) && \is_string($data['message']) ? $data['message'] : null;
+        $location = null;
+        if (\array_key_exists('location', $data)) {
+            if (null !== $data['location'] && !\is_string($data['location'])) {
+                throw new InvalidArgumentException('location must be a string URI or null.');
+            }
+            if (\is_string($data['location']) && '' !== $data['location']) {
+                if (false === filter_var($data['location'], FILTER_VALIDATE_URL)) {
+                    throw new InvalidArgumentException('location must be a valid URI.');
+                }
+                $location = $data['location'];
+            }
+        }
 
         return new self(
             (string) $data['idempotencyKey'],
             CallbackStatus::fromString((string) $data['status']),
             $message,
+            $location,
         );
     }
 
@@ -58,6 +80,11 @@ public function message(): ?string
         return $this->message;
     }
 
+    public function location(): ?string
+    {
+        return $this->location;
+    }
+
     /**
      * @return array<string, mixed>
      */
@@ -70,6 +97,9 @@ public function toArray(): array
         if (null !== $this->message) {
             $payload['message'] = $this->message;
         }
+        if (null !== $this->location) {
+            $payload['location'] = $this->location;
+        }
 
         return $payload;
     }

src/Core/Orchestration/OrchestrationCommandProcessor.php

@@ -7,6 +7,7 @@
 use ApplicationManagerTools\AmDriver\Core\Contract\CreateInstanceHandlerInterface;
 use ApplicationManagerTools\AmDriver\Core\Contract\StartInstanceHandlerInterface;
 use ApplicationManagerTools\AmDriver\Core\Contract\StopInstanceHandlerInterface;
+use ApplicationManagerTools\AmDriver\Core\Dto\CreateInstanceHandlerResult;
 use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCallbackRequest;
 use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCommand;
 use ApplicationManagerTools\AmDriver\Core\Exception\HandlerFailedException;
@@ -55,9 +56,10 @@ public function process(OrchestrationCommand $command): array
             return ['httpStatus' => 200, 'alreadyProcessed' => true];
         }
 
+        $createResult = null;
         try {
             if ($command->operation()->isCreate()) {
-                $this->createHandler->handle($command);
+                $createResult = $this->createHandler->handle($command);
             } elseif ($command->operation()->isStop()) {
                 $this->stopHandler->handle($command);
             } elseif ($command->operation()->isStart()) {
@@ -86,15 +88,24 @@ public function process(OrchestrationCommand $command): array
         }
 
         $this->idempotencyStore->remember($command->idempotencyKey());
-        $this->reportCallback($command, CallbackStatus::succeeded(), null);
+        $this->reportCallback(
+            $command,
+            CallbackStatus::succeeded(),
+            null,
+            $createResult instanceof CreateInstanceHandlerResult ? $createResult->instanceLocation() : null,
+        );
 
         return ['httpStatus' => 200, 'alreadyProcessed' => false];
     }
 
-    private function reportCallback(OrchestrationCommand $command, CallbackStatus $status, ?string $message): void
-    {
+    private function reportCallback(
+        OrchestrationCommand $command,
+        CallbackStatus $status,
+        ?string $message,
+        ?string $location = null
+    ): void {
         $this->amApiClient->reportOrchestrationCallback(
-            new OrchestrationCallbackRequest($command->idempotencyKey(), $status, $message),
+            new OrchestrationCallbackRequest($command->idempotencyKey(), $status, $message, $location),
         );
     }
 }

tests/Unit/Dto/OrchestrationCallbackRequestTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ApplicationManagerTools\AmDriver\Tests\Unit\Dto;
+
+use ApplicationManagerTools\AmDriver\Core\Dto\OrchestrationCallbackRequest;
+use ApplicationManagerTools\AmDriver\Core\Orchestration\CallbackStatus;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+final class OrchestrationCallbackRequestTest extends TestCase
+{
+    public function testToArrayOmitsLocationWhenNull(): void
+    {
+        // Arrange
+        $request = new OrchestrationCallbackRequest('idem-1', CallbackStatus::succeeded());
+
+        // Act
+        $array = $request->toArray();
+
+        // Assert
+        self::assertArrayNotHasKey('location', $array);
+    }
+
+    public function testToArrayIncludesLocationWhenSet(): void
+    {
+        // Arrange
+        $request = new OrchestrationCallbackRequest(
+            'idem-1',
+            CallbackStatus::succeeded(),
+            null,
+            'https://tenant.example/login',
+        );
+
+        // Act
+        $array = $request->toArray();
+
+        // Assert
+        self::assertSame('https://tenant.example/login', $array['location']);
+    }
+
+    public function testFromArrayAcceptsOptionalLocation(): void
+    {
+        // Arrange
+        $data = [
+            'idempotencyKey' => 'idem-1',
+            'status' => 'SUCCEEDED',
+            'location' => 'https://tenant.example/login',
+        ];
+
+        // Act
+        $request = OrchestrationCallbackRequest::fromArray($data);
+
+        // Assert
+        self::assertSame('https://tenant.example/login', $request->location());
+    }
+
+    public function testFromArrayRejectsInvalidLocationUri(): void
+    {
+        // Arrange
+        $this->expectException(InvalidArgumentException::class);
+
+        // Act
+        OrchestrationCallbackRequest::fromArray([
+            'idempotencyKey' => 'idem-1',
+            'status' => 'SUCCEEDED',
+            'location' => 'not-a-uri',
+        ]);
+    }
+}

tests/Unit/Http/AmApiClientTest.php

@@ -54,6 +54,28 @@ public function testReportCallbackUsesCallbackToken(): void
         self::assertSame('secret-cb', $this->headerValue($recording->options, 'X-Orchestration-Callback-Token'));
     }
 
+    public function testReportCallbackSerializesLocationInJsonBody(): void
+    {
+        // Arrange
+        $recording = new RecordingHttpClient();
+        $api = new AmApiClient($recording, new AmApiClientConfig('https://am.example', 'secret-cons', 'secret-cb'));
+
+        // Act
+        $api->reportOrchestrationCallback(new OrchestrationCallbackRequest(
+            'idem-key',
+            CallbackStatus::succeeded(),
+            null,
+            'https://tenant.example/login',
+        ));
+
+        // Assert
+        $body = $recording->options['body'] ?? null;
+        self::assertIsString($body);
+        /** @var array<string, mixed> $json */
+        $json = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
+        self::assertSame('https://tenant.example/login', $json['location'] ?? null);
+    }
+
     /**
      * @param array<string, mixed> $options
      */