Support specifying a custom_handler_url for a task despatch

So that you can override the handler_url in the configuration
for the task type at runtime. Useful when despatching tasks
where the url depends on something in the payload, e.g.
forwarding to a subdomain or a url-based route rather than
just a querystring.

Author: acoulton

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+* Allow clients to specify a custom_handler_url when creating a task, to override the default handler_url provided
+  by the configuration for the task type. Useful when the handler url is dependent on something that can only be 
+  determined at runtime (e.g. routing to a subdomain).
+
 * Support a `custom_token_audience` in the TaskType options, to allow specifying a non-default `audience` in the JWT
   that Cloud Tasks issues to authorise the request.
 

src/Client/CloudTaskCreator.php

@@ -40,7 +40,7 @@ public function create(string $task_type_name, ?CreateTaskOptions $options = NUL
         $task_type = $this->task_config->getConfig($task_type_name);
         $options   ??= new CreateTaskOptions([]);
 
-        $handler_url = $task_type->getHandlerUrl();
+        $handler_url = $options->getCustomHandlerUrl() ?? $task_type->getHandlerUrl();
         if ($options->hasQuery()) {
             $handler_url .= '?'.\http_build_query($options->getQuery());
         }

src/Client/CreateTaskOptions.php

@@ -7,6 +7,7 @@
 use Ingenerator\PHPUtils\DateTime\DateTimeImmutableFactory;
 use Ingenerator\PHPUtils\Object\ObjectPropertyPopulator;
 use Ingenerator\PHPUtils\StringEncoding\JSON;
+use function str_contains;
 
 class CreateTaskOptions
 {
@@ -41,6 +42,11 @@ class CreateTaskOptions
      */
     private array $headers = [];
 
+    /**
+     * Optionally specify a complete URL the task should be sent to, otherwise this will come from the TaskTypeConfig
+     */
+    private ?string $custom_handler_url = NULL;
+
     /**
      * Optionally add GET parameters to the handler URL.
      *
@@ -150,6 +156,12 @@ public function __construct(array $options)
             throw new \InvalidArgumentException('Cannot set both task_id and task_id_hash_options');
         }
 
+        if (str_contains($this->custom_handler_url ?? '', '?') and ! empty($this->query)) {
+            throw new \InvalidArgumentException(
+                'Cannot set a query if your custom_handler_url already includes a querystring'
+            );
+        }
+
         if (isset($options['throttle_delay_secs']) and ! $this->throttle_interval) {
             // Only matters if they set it explicitly so we check $options not the property which has a default
             throw new \InvalidArgumentException('Cannot use throttle_delay_secs without throttle_interval');
@@ -277,6 +289,11 @@ public function getHeaders(): array
         return $this->headers;
     }
 
+    public function getCustomHandlerUrl(): ?string
+    {
+        return $this->custom_handler_url;
+    }
+
     /**
      * @return array|null
      */

test/unit/Client/CloudTaskCreatorTest.php

@@ -93,11 +93,39 @@ public function test_it_configures_custom_audience_for_authenticated_task_if_con
         $this->assertSame($expect, $task->getHttpRequest()->getOidcToken()->getAudience());
     }
 
+    public function provider_task_url()
+    {
+        return [
+            'just from config, no query'                                                 => [
+                [],
+                "https://my.handler.foo/something",
+            ],
+            'from config, with CreateTaskOptions.query'                                  => [
+                ['query' => ['id' => 15, 'scope' => 'any']],
+                "https://my.handler.foo/something?id=15&scope=any",
+            ],
+            'with CreateTaskOptions.custom_handler_url and no query'                     => [
+                ['custom_handler_url' => 'https://my-handler.com/whatever'],
+                "https://my-handler.com/whatever",
+            ],
+            'with CreateTaskOptions.custom_handler_url including own query and no query' => [
+                ['custom_handler_url' => 'https://my-handler.com/whatever?foo=bar'],
+                "https://my-handler.com/whatever?foo=bar",
+            ],
+            'with CreateTaskOptions.custom_handler_url and CreateTaskOptions.query'      => [
+                [
+                    'custom_handler_url' => 'https://my-handler.com/whatever',
+                    'query'              => ['id' => 15, 'scope' => 'any'],
+                ],
+                "https://my-handler.com/whatever?id=15&scope=any",
+            ],
+        ];
+    }
+
     /**
-     * @testWith [[], "https://my.handler.foo/something"]
-     *           [{"query": {"id": 15, "scope": "any"}}, "https://my.handler.foo/something?id=15&scope=any"]
+     * @dataProvider provider_task_url
      */
-    public function test_it_sets_task_to_post_to_provided_url_optionally_adding_query_params($opts, $expect)
+    public function test_it_sets_task_to_post_to_custom_or_config_url_optionally_adding_query_params($opts, $expect)
     {
         $this->task_config = TaskTypeConfigStub::withTaskType(
             'do-something',

test/unit/Client/CreateTaskOptionsTest.php

@@ -6,6 +6,7 @@
 
 use Ingenerator\CloudTasksWrapper\Client\CreateTaskOptions;
 use Ingenerator\PHPUtils\Object\ObjectPropertyRipper;
+use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 
 class CreateTaskOptionsTest extends TestCase
@@ -89,6 +90,27 @@ public function test_it_can_have_query($opts, $expect)
         }
     }
 
+    /**
+     * @testWith [{"query": {"foo": "bar"}, "custom_handler_url": "http://some.service/wherever"}, true]
+     *           [{"custom_handler_url": "http://some.service/wherever?hardcoded=query"}, true]
+     *           [{"query": {"foo": "bar"}, "custom_handler_url": "http://some.service/wherever?hardcoded=query"}, false]
+     */
+    public function test_it_only_allows_query_with_custom_url_if_url_does_not_contain_a_query($opts, $is_valid)
+    {
+        $e = NULL;
+        try {
+            $subject = new CreateTaskOptions($opts);
+        } catch (\InvalidArgumentException $e) {
+        }
+
+        if ($is_valid) {
+            $this->assertNull($e, (string ) $e);
+        } else {
+            $this->assertInstanceOf(InvalidArgumentException::class, $e);
+            $this->assertStringContainsString('querystring', $e->getMessage());
+        }
+    }
+
     public function provider_body_encoding()
     {
         return [