Implement endpoint response hooks and asynchronous processing

Author: tobyzerner

docs/async.md

@@ -0,0 +1,119 @@
+# Asynchronous Processing
+
+This library supports the
+[JSON:API Asynchronous Processing](https://jsonapi.org/recommendations/#asynchronous-processing)
+recommendation, which provides a standardized way to handle long-running
+resource creation operations.
+
+## Overview
+
+The async processing pattern works as follows:
+
+1. **Async Creation** (202 Accepted): Client creates a resource that takes time
+   to process. Server returns a `202 Accepted` status with a `Content-Location`
+   or `Location` header pointing to a job resource.
+2. **Job Polling** (200 OK): Client polls the job resource to check status.
+   Server returns `200 OK` with optional `Retry-After` header.
+3. **Completion** (303 See Other): When processing completes, job resource
+   returns `303 See Other` with a `Location` header pointing to the created
+   resource.
+
+## Async Creation
+
+To enable async processing for resource creation, use the `async` method on the
+`Create` endpoint:
+
+```php
+use Tobyz\JsonApiServer\Endpoint\Create;
+
+class PhotosResource extends Resource
+{
+    public function endpoints(): array
+    {
+        return [
+            Create::make()->async('jobs', function ($model, Context $context) {
+                if ($this->requiresAsyncProcessing($model)) {
+                    return Job::create([
+                        'status' => 'pending',
+                        'resource_type' => 'photos',
+                        'resource_data' => $model,
+                    ]);
+                }
+            }),
+        ];
+    }
+}
+```
+
+The `async` method takes two parameters:
+
+- **Collection name**: The name of the collection in which the job resource will
+  be found (e.g. `jobs`)
+- **Callback**: A function that receives the model and context, and returns:
+    - A **job model object**: Will return a `202 Accepted` response containing
+      the job resource, and a `Content-Location` header pointing to the job
+      resource
+    - A **string path**: Will return a `202 Accepted` response with the string
+      as the `Location`
+    - **null**: Falls back to synchronous processing with a normal `201 Created`
+      response
+
+The callback is invoked after the data pipeline has validated and filled the
+model, but before it's persisted to storage.
+
+## Job Polling
+
+Use custom headers on your job resource's `Show` endpoint to provide polling
+guidance:
+
+```php
+use Tobyz\JsonApiServer\Endpoint\Show;
+use Tobyz\JsonApiServer\Schema\Header;
+use Tobyz\JsonApiServer\Schema\Type\Integer;
+
+class JobsResource extends Resource
+{
+    public function endpoints(): array
+    {
+        return [
+            Show::make()->headers([
+                Header::make('Retry-After')
+                    ->type(Integer::make())
+                    ->nullable()
+                    ->get(
+                        fn($model) => $model->status === 'pending' ? 60 : null,
+                    ),
+            ]),
+        ];
+    }
+}
+```
+
+## Completion with See Other
+
+When a job completes, use the `seeOther` convenience method to redirect clients
+to the created resource:
+
+```php
+use Tobyz\JsonApiServer\Endpoint\Show;
+
+class JobsResource extends Resource
+{
+    public function endpoints(): array
+    {
+        return [
+            Show::make()->seeOther(function ($model, Context $context) {
+                if ($model->status === 'completed') {
+                    return "photos/$model->result_id";
+                }
+            }),
+        ];
+    }
+}
+```
+
+The `seeOther` method automatically:
+
+- Returns a `303 See Other` response when the callback returns a value, with the
+  returned string as the `Location` header
+- Adds OpenAPI schema for the 303 response

docs/resources.md

@@ -208,3 +208,37 @@ The `POST` method is used by default, but you can customize this using the
 ```php
 Endpoint\CollectionAction::make(...)->method('PUT');
 ```
+
+### Custom Headers
+
+Use the `headers()` method to define custom headers for endpoint responses.
+Headers can be static or dynamic based on the model data:
+
+```php
+use Tobyz\JsonApiServer\Schema\Header;
+use Tobyz\JsonApiServer\Schema\Type;
+
+Endpoint\Show::make()->headers([
+    Header::make('X-Rate-Limit')
+        ->type(Type\Integer::make())
+        ->get(fn($model) => $model->rate_limit),
+
+    Header::make('Cache-Control')->get(fn() => 'max-age=3600'),
+]);
+```
+
+### Response Callbacks
+
+Use the `response()` method to register callbacks that can modify or replace the
+response. Callbacks receive the response object and, when available, the model
+and context:
+
+```php
+Endpoint\Show::make()->response(function ($response, $model, Context $context) {
+    if ($model->is_archived) {
+        return $response->withStatus(410); // Gone
+    }
+
+    return $response->withHeader('X-Version', $model->version);
+});
+```

src/Endpoint/CollectionAction.php

@@ -3,9 +3,11 @@
 namespace Tobyz\JsonApiServer\Endpoint;
 
 use Closure;
-use Nyholm\Psr7\Response;
 use Psr\Http\Message\ResponseInterface;
 use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Endpoint\Concerns\BuildsDocument;
+use Tobyz\JsonApiServer\Endpoint\Concerns\HasResponse;
+use Tobyz\JsonApiServer\Endpoint\Concerns\HasSchema;
 use Tobyz\JsonApiServer\Exception\ForbiddenException;
 use Tobyz\JsonApiServer\Exception\MethodNotAllowedException;
 use Tobyz\JsonApiServer\JsonApi;
@@ -14,10 +16,15 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
+use function Tobyz\JsonApiServer\json_api_response;
+
 class CollectionAction implements Endpoint, OpenApiPathsProvider
 {
     use HasVisibility;
     use HasDescription;
+    use HasResponse;
+    use HasSchema;
+    use BuildsDocument;
 
     public string $method = 'POST';
 
@@ -55,21 +62,31 @@ public function handle(Context $context): ?ResponseInterface
 
         ($this->handler)($context);
 
-        return new Response(204);
+        $response = json_api_response($this->buildDocument($context), status: 204);
+
+        return $this->applyResponseHooks($response, $context);
     }
 
     public function getOpenApiPaths(Collection $collection, JsonApi $api): array
     {
-        return [
+        $response = [];
+
+        if ($headers = $this->getHeadersSchema($api)) {
+            $response['headers'] = $headers;
+        }
+
+        $paths = [
             "/{$collection->name()}/$this->name" => [
                 strtolower($this->method) => [
                     'description' => $this->getDescription(),
                     'tags' => [$collection->name()],
                     'responses' => [
-                        '204' => [],
+                        '204' => $response,
                     ],
                 ],
             ],
         ];
+
+        return $this->mergeSchema($paths);
     }
 }

src/Endpoint/Concerns/HasResponse.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Endpoint\Concerns;
+
+use Psr\Http\Message\ResponseInterface;
+use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\JsonApi;
+use Tobyz\JsonApiServer\Schema\Header;
+
+trait HasResponse
+{
+    /** @var Header[] */
+    private array $headers = [];
+
+    /** @var callable[] */
+    private array $responseCallbacks = [];
+
+    /**
+     * Set custom headers for the response.
+     *
+     * @param Header[] $headers
+     */
+    public function headers(array $headers): static
+    {
+        $this->headers = array_merge($this->headers, $headers);
+
+        return $this;
+    }
+
+    /**
+     * Register a callback to customize the response.
+     *
+     * The callback receives the response and can return a modified or new response.
+     */
+    public function response(callable $callback): static
+    {
+        $this->responseCallbacks[] = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Apply custom headers to the response.
+     */
+    private function applyHeaders(ResponseInterface $response, Context $context): ResponseInterface
+    {
+        foreach ($this->headers as $header) {
+            $headerContext = $context->withField($header);
+            $value = $header->getValue($headerContext);
+
+            if ($value !== null) {
+                $value = $header->serializeValue($value, $headerContext);
+                $response = $response->withHeader($header->name, (string) $value);
+            }
+        }
+
+        return $response;
+    }
+
+    /**
+     * Apply response callbacks in sequence.
+     */
+    private function applyResponseCallbacks(
+        ResponseInterface $response,
+        Context $context,
+    ): ResponseInterface {
+        foreach ($this->responseCallbacks as $callback) {
+            $result = isset($context->model)
+                ? $callback($response, $context->model, $context)
+                : $callback($response, $context);
+
+            if ($result instanceof ResponseInterface) {
+                $response = $result;
+            }
+        }
+
+        return $response;
+    }
+
+    /**
+     * Apply response hooks (headers and callbacks).
+     */
+    private function applyResponseHooks(
+        ResponseInterface $response,
+        Context $context,
+    ): ResponseInterface {
+        $response = $this->applyHeaders($response, $context);
+        $response = $this->applyResponseCallbacks($response, $context);
+
+        return $response;
+    }
+
+    /**
+     * Get OpenAPI headers schema for custom headers.
+     */
+    private function getHeadersSchema(JsonApi $api): array
+    {
+        $headers = [];
+
+        foreach ($this->headers as $header) {
+            $headers[$header->name] = [
+                'description' => $header->description,
+                'schema' => $header->getSchema($api),
+            ];
+        }
+
+        return $headers;
+    }
+}

src/Endpoint/Concerns/HasSchema.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Endpoint\Concerns;
+
+trait HasSchema
+{
+    private array $schema = [];
+
+    /**
+     * Set custom OpenAPI schema to merge with the base schema.
+     */
+    public function schema(array $schema): static
+    {
+        $this->schema = array_merge_recursive($this->schema, $schema);
+
+        return $this;
+    }
+
+    /**
+     * Merge custom schema with the base OpenAPI schema.
+     */
+    private function mergeSchema(array $baseSchema): array
+    {
+        return array_merge_recursive($baseSchema, $this->schema);
+    }
+}