Merge tag 'v1.0.1' into develop

Fix asynchronous process bug.

Author: lindyhopchris

CHANGELOG.md

@@ -2,6 +2,12 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## [1.0.1] - 2019-03-12
+
+### Fixed
+- A `303 See Other` will now not be returned if a client job has failed. This is necessary because
+otherwise there is no way for an API client to determine that the job completed but failed.
+
 ## [1.0.0] - 2019-02-28
 
 ### Added

docs/features/async.md

@@ -217,6 +217,40 @@ class ProcessPodcast implements ShouldQueue
 }
 ```
 
+## Routing
+
+The final step of setup is to enable asynchronous process routes on a resource. These
+routes allow a client to check the current status of a process.
+
+For example, if our `podcasts` resource used asynchronous processes when a podcast is
+created, we would need to add the following to our [route definitions](../basics/routing.md):
+
+```php
+JsonApi::register('default')->withNamespace('Api')->routes(function ($api) {
+    $api->resource('podcasts')->async();
+});
+```
+
+This enables the following routes:
+
+- `GET /podcasts/queue-jobs`: this lists all `queue-jobs` resources for the `podcasts`
+resource type.
+- `GET /podcasts/queue-jobs/<UUID>`: this retrieves a specific `queue-jobs` resource 
+for the `podcasts` resource type.
+
+The resource type `queue-jobs` is the name used in the JSON API's recommendation for
+asynchronous processing. If you want to use a resource type, then you can change this 
+by editing the `jobs.resource` config setting in your API's configuration file.
+
+Note that we assume the resource id of a process is a valid UUID. If you use something
+different, then you can pass a constraint into the `async()` method, as follows:
+
+```php
+JsonApi::register('default')->withNamespace('Api')->routes(function ($api) {
+    $api->resource('podcasts')->async('^\d+$');
+});
+```
+
 ## HTTP Requests and Responses
 
 Once you have followed the above instructions, you can now make HTTP requests and receive

src/Queue/ClientJob.php

@@ -119,6 +119,10 @@ public function getResourceType(): string
      */
     public function getLocation(): ?string
     {
+        if ($this->failed) {
+            return null;
+        }
+
         $type = $this->resource_type;
         $id = $this->resource_id;
 

tests/dummy/database/factories/ClientJobFactory.php

@@ -22,7 +22,7 @@
 
 /** @var Factory $factory */
 
-$factory->define(ClientJob::class, function (Faker $faker) {
+$factory->define(ClientJob::class, function () {
     return [
         'api' => 'v1',
         'failed' => false,
@@ -36,6 +36,20 @@
         'completed_at' => $faker->dateTimeBetween('-10 minutes', 'now'),
         'failed' => false,
         'attempts' => $faker->numberBetween(1, 3),
+    ];
+});
+
+$factory->state(ClientJob::class, 'failed', function (Faker $faker) {
+    return [
+        'completed_at' => $faker->dateTimeBetween('-10 minutes', 'now'),
+        'failed' => true,
+        'attempts' => $faker->numberBetween(1, 3),
+    ];
+});
+
+$factory->state(ClientJob::class, 'with_download', function () {
+    return [
+        'resource_type' => 'downloads',
         'resource_id' => factory(Download::class)->create()->getRouteKey(),
     ];
 });

tests/lib/Integration/Queue/QueueJobsTest.php

@@ -54,7 +54,7 @@ public function testReadPending()
      */
     public function testReadNotPending()
     {
-       $job = factory(ClientJob::class)->states('success')->create();
+       $job = factory(ClientJob::class)->states('success', 'with_download')->create();
 
        $response = $this
            ->getJsonApi($this->jobUrl($job))
@@ -71,7 +71,22 @@ public function testReadNotPending()
      */
     public function testReadNotPendingCannotSeeOther()
     {
-        $job = factory(ClientJob::class)->states('success')->create(['resource_id' => null]);
+        $job = factory(ClientJob::class)->states('success')->create();
+        $expected = $this->serialize($job);
+
+        $this->getJsonApi($this->jobUrl($job))
+            ->assertFetchedOneExact($expected)
+            ->assertHeaderMissing('Location');
+    }
+
+    /**
+     * If the async process fails, we do not expect it to return a See Other even if
+     * it has a resource id. This is because otherwise there is no way for the client
+     * to know that it failed.
+     */
+    public function testReadFailed()
+    {
+        $job = factory(ClientJob::class)->states('failed', 'with_download')->create();
         $expected = $this->serialize($job);
 
         $this->getJsonApi($this->jobUrl($job))