Improve Mercure Discovery spec and enhance component features

- Add full Mercure Discovery specification support with rel="self" and optional link attributes (last-event-id, content-type, key-set)
- Add SubscriptionUrlBuilder utility for building subscription URLs with topics
- Enhance MercureComponent::discover() with discoverWithTopics config option and optional parameters

Author: josbeir

README.md

@@ -642,6 +642,49 @@ fetch('/api/resource')
     });
 ```
 
+### Discovery with Topics and Attributes
+
+The `discover()` method supports optional parameters that align with the Mercure specification:
+
+```php
+// Add discovery header with optional link attributes
+$this->Mercure->discover(
+    lastEventId: '123',
+    contentType: 'application/json',
+    keySet: 'https://example.com/.well-known/jwks.json'
+);
+```
+
+**Include subscription topics in discovery:**
+
+When you want the `rel="self"` Link header to include the topics the user is authorized for, enable `discoverWithTopics`:
+
+```php
+// Option 1: Enable per-call
+$this->Mercure
+    ->authorize(['/books/123', '/notifications/*'])
+    ->discover(includeTopics: true);
+
+// Option 2: Enable in component config
+$this->loadComponent('Mercure.Mercure', [
+    'discoverWithTopics' => true
+]);
+
+// Then in your action:
+$this->Mercure
+    ->authorize(['/books/123'])
+    ->discover(); // Automatically includes topics in rel="self"
+```
+
+This generates both headers:
+
+```
+Link: <https://hub.example.com/.well-known/mercure?topic=%2Fbooks%2F123>; rel="self"
+Link: <https://hub.example.com/.well-known/mercure>; rel="mercure"
+```
+
+The `rel="self"` header provides a ready-to-use subscription URL that clients can connect to directly.
+
 ### Using Middleware
 
 This is an alternative approach to add the discovery header automatically to all responses by using middleware:
@@ -863,8 +906,9 @@ public function initialize(): void
 {
     parent::initialize();
     $this->loadComponent('Mercure.Mercure', [
-        'autoDiscover' => true,  // Optional: auto-add discovery headers
-        'defaultTopics' => [     // Optional: topics available in all views
+        'autoDiscover' => true,      // Optional: auto-add discovery headers
+        'discoverWithTopics' => false, // Optional: include topics in rel="self"
+        'defaultTopics' => [         // Optional: topics available in all views
             '/notifications',
             '/global/alerts'
         ]
@@ -888,7 +932,7 @@ public function initialize(): void
 | `resetAdditionalClaims()` | `$this` | Reset accumulated JWT claims |
 | `authorize(array $subscribe = [], array $additionalClaims = [])` | `$this` | Set authorization cookie (merges with accumulated state, then resets) |
 | `clearAuthorization()` | `$this` | Clear authorization cookie |
-| `discover()` | `$this` | Add Mercure discovery Link header |
+| `discover(?bool $includeTopics, ?string $lastEventId, ?string $contentType, ?string $keySet)` | `$this` | Add Mercure discovery Link headers with optional attributes and topics |
 | `publish(Update $update)` | `bool` | Publish an update to the Mercure hub |
 | `publishJson(string\|array $topics, mixed $data, ...)` | `bool` | Publish JSON data (auto-encodes) |
 | `publishSimple(string\|array $topics, string $data, ...)` | `bool` | Publish simple string data (no encoding) |

src/Authorization.php

@@ -130,20 +130,64 @@ public static function getCookieName(): string
     }
 
     /**
-     * Add the Mercure discovery header to the response
+     * Add the Mercure discovery headers to the response
      *
-     * Adds a Link header with rel="mercure" to advertise the Mercure hub URL.
-     * This allows clients to discover the hub endpoint automatically.
+     * Adds Link headers for Mercure discovery according to the Mercure specification:
+     * - rel="mercure": The hub URL for subscriptions (required)
+     * - rel="self": The canonical topic URL for this resource (optional)
+     *
+     * The rel="mercure" link may include optional attributes:
+     * - last-event-id: The last event ID for reconciliation
+     * - content-type: Content type hint for updates (e.g., for partial updates)
+     * - key-set: URL to JWK key set for encrypted updates
      *
      * Skips CORS preflight requests to prevent conflicts with CORS middleware.
      *
+     * Example usage:
+     * ```
+     * // Basic discovery
+     * $response = Authorization::addDiscoveryHeader($response);
+     *
+     * // With canonical topic URL
+     * $response = Authorization::addDiscoveryHeader(
+     *     response: $response,
+     *     selfUrl: '/books/123'
+     * );
+     *
+     * // With all parameters
+     * $response = Authorization::addDiscoveryHeader(
+     *     response: $response,
+     *     selfUrl: '/books/123.jsonld',
+     *     lastEventId: 'urn:uuid:abc-123',
+     *     contentType: 'application/ld+json',
+     *     keySet: 'https://example.com/.well-known/jwks.json'
+     * );
+     * ```
+     *
      * @param \Cake\Http\Response $response The response object to modify
      * @param \Cake\Http\ServerRequest|null $request Optional request to check for preflight
-     * @return \Cake\Http\Response Modified response with discovery header
+     * @param string|null $selfUrl Canonical topic URL for rel="self" link
+     * @param string|null $lastEventId Last event ID for state reconciliation
+     * @param string|null $contentType Content type of updates
+     * @param string|null $keySet URL to JWK key set for encryption
+     * @return \Cake\Http\Response Modified response with discovery headers
      * @throws \Mercure\Exception\MercureException
      */
-    public static function addDiscoveryHeader(Response $response, ?ServerRequest $request = null): Response
-    {
-        return self::create()->addDiscoveryHeader($response, $request);
+    public static function addDiscoveryHeader(
+        Response $response,
+        ?ServerRequest $request = null,
+        ?string $selfUrl = null,
+        ?string $lastEventId = null,
+        ?string $contentType = null,
+        ?string $keySet = null,
+    ): Response {
+        return self::create()->addDiscoveryHeader(
+            $response,
+            $request,
+            $selfUrl,
+            $lastEventId,
+            $contentType,
+            $keySet,
+        );
     }
 }

src/Controller/Component/MercureComponent.php

@@ -6,6 +6,8 @@
 use Cake\Controller\Component;
 use Cake\Event\EventInterface;
 use Mercure\Authorization;
+use Mercure\Internal\ConfigurationHelper;
+use Mercure\Internal\SubscriptionUrlBuilder;
 use Mercure\Publisher;
 use Mercure\Service\AuthorizationInterface;
 use Mercure\Service\PublisherInterface;
@@ -88,8 +90,9 @@
  * Configuration:
  * ```
  * $this->loadComponent('Mercure.Mercure', [
- *     'autoDiscover' => true,     // Automatically add discovery headers
- *     'defaultTopics' => [        // Topics automatically available in all views
+ *     'autoDiscover' => true,        // Automatically add discovery headers
+ *     'discoverWithTopics' => true,  // Include subscribe topics in discovery rel="self" link
+ *     'defaultTopics' => [           // Topics automatically available in all views
  *         '/notifications',
  *         '/global/alerts'
  *     ]
@@ -111,6 +114,13 @@ class MercureComponent extends Component
      */
     protected array $subscribe = [];
 
+    /**
+     * Last authorized subscribe topics (preserved for discovery)
+     *
+     * @var array<string>
+     */
+    protected array $lastAuthorizedTopics = [];
+
     /**
      * Additional JWT claims accumulated via addSubscribe()
      *
@@ -125,6 +135,7 @@ class MercureComponent extends Component
      */
     protected array $_defaultConfig = [
         'autoDiscover' => false,
+        'discoverWithTopics' => false,
         'defaultTopics' => [],
     ];
 
@@ -335,6 +346,9 @@ public function authorize(array $subscribe = [], array $additionalClaims = []):
         $response = $this->authorizationService->setCookie($response, $allSubscribe, $allClaims);
         $this->getController()->setResponse($response);
 
+        // Store topics for potential use in discovery
+        $this->lastAuthorizedTopics = $allSubscribe;
+
         // Reset accumulated state after authorization
         $this->resetSubscribe();
         $this->resetAdditionalClaims();
@@ -366,27 +380,75 @@ public function clearAuthorization(): static
     }
 
     /**
-     * Add the Mercure discovery header to the response
+     * Add Mercure discovery headers to the response
      *
-     * Adds a Link header with rel="mercure" to advertise the Mercure hub URL.
-     * This allows clients to automatically discover the hub endpoint.
+     * Adds Link headers for Mercure hub discovery. Optionally includes
+     * a rel="self" link with subscription topics from the subscribe array.
      *
-     * Example:
+     * Priority for includeTopics parameter:
+     * 1. Explicit method parameter (true/false)
+     * 2. Component config 'discoverWithTopics'
+     * 3. Default: false
+     *
+     * Examples:
      * ```
+     * // Basic discovery
      * $this->Mercure->discover();
      *
-     * // Or chained with authorize
-     * $this->Mercure->authorize(['/feeds/123'])->discover();
+     * // With topics from subscribe array
+     * $this->Mercure
+     *     ->addSubscribe('/books/123')
+     *     ->authorize()
+     *     ->discover(includeTopics: true);
+     *
+     * // With all discovery parameters
+     * $this->Mercure->discover(
+     *     includeTopics: true,
+     *     lastEventId: 'urn:uuid:abc-123',
+     *     contentType: 'application/ld+json',
+     *     keySet: 'https://example.com/.well-known/jwks.json'
+     * );
+     *
+     * // Use config value (discoverWithTopics)
+     * $this->Mercure->discover(); // Uses config setting
      * ```
      *
+     * @param bool|null $includeTopics Include subscribe topics in rel="self" link (null uses config)
+     * @param string|null $lastEventId Last event ID for state reconciliation
+     * @param string|null $contentType Content type hint for updates
+     * @param string|null $keySet URL to JWK key set for encryption
      * @return $this For method chaining
      * @throws \Mercure\Exception\MercureException
      */
-    public function discover(): static
-    {
+    public function discover(
+        ?bool $includeTopics = null,
+        ?string $lastEventId = null,
+        ?string $contentType = null,
+        ?string $keySet = null,
+    ): static {
         $request = $this->getController()->getRequest();
         $response = $this->getController()->getResponse();
-        $response = $this->authorizationService->addDiscoveryHeader($response, $request);
+
+        // Determine if we should include topics
+        // Priority: method param > config > default (false)
+        $shouldIncludeTopics = $includeTopics ?? $this->getConfig('discoverWithTopics', false);
+
+        // Build selfUrl if topics should be included and we have authorized topics
+        $selfUrl = null;
+        if ($shouldIncludeTopics && $this->lastAuthorizedTopics !== []) {
+            $hubUrl = ConfigurationHelper::getPublicUrl();
+            $selfUrl = SubscriptionUrlBuilder::build($hubUrl, $this->lastAuthorizedTopics);
+        }
+
+        $response = $this->authorizationService->addDiscoveryHeader(
+            $response,
+            $request,
+            $selfUrl,
+            $lastEventId,
+            $contentType,
+            $keySet,
+        );
+
         $this->getController()->setResponse($response);
 
         return $this;

src/Internal/QueryBuilder.php src/Internal/PublishQueryBuilder.phpsrc/Internal/QueryBuilder.php renamed to src/Internal/PublishQueryBuilder.php

@@ -4,13 +4,13 @@
 namespace Mercure\Internal;
 
 /**
- * Query Builder
+ * Publish Query Builder
  *
- * Builds URL-encoded query strings for Mercure hub requests.
+ * Builds URL-encoded query strings for Mercure hub publish requests.
  *
  * @internal
  */
-class QueryBuilder
+class PublishQueryBuilder
 {
     /**
      * Build a URL-encoded query string from data

src/Internal/SubscriptionUrlBuilder.php

@@ -0,0 +1,69 @@
+<?php
+declare(strict_types=1);
+
+namespace Mercure\Internal;
+
+/**
+ * Subscription URL Builder
+ *
+ * Builds Mercure subscription URLs with topic query parameters.
+ * This utility is used by both MercureHelper and MercureComponent
+ * to generate consistent subscription URLs.
+ *
+ * @internal
+ */
+class SubscriptionUrlBuilder
+{
+    /**
+     * Build a subscription URL with topics and optional query parameters
+     *
+     * Generates a complete Mercure hub subscription URL with topic query parameters.
+     * Topics can be specified multiple times in the query string as per Mercure spec.
+     *
+     * Example:
+     * ```
+     * $url = SubscriptionUrlBuilder::build(
+     *     'https://hub.example.com/.well-known/mercure',
+     *     ['/books/123', '/notifications/*']
+     * );
+     * // Result: https://hub.example.com/.well-known/mercure?topic=%2Fbooks%2F123&topic=%2Fnotifications%2F*
+     * ```
+     *
+     * @param string $hubUrl Base hub URL
+     * @param array<string> $topics Topics to subscribe to
+     * @param array<string, mixed> $options Additional query parameters
+     * @return string Complete subscription URL
+     */
+    public static function build(string $hubUrl, array $topics, array $options = []): string
+    {
+        if ($topics === [] && $options === []) {
+            return $hubUrl;
+        }
+
+        $params = [];
+
+        // Add topic parameters (can be specified multiple times)
+        foreach ($topics as $topic) {
+            $params[] = 'topic=' . urlencode($topic);
+        }
+
+        // Add additional options
+        foreach ($options as $key => $value) {
+            if (is_array($value)) {
+                foreach ($value as $item) {
+                    $params[] = urlencode($key) . '=' . urlencode((string)$item);
+                }
+            } else {
+                $params[] = urlencode($key) . '=' . urlencode((string)$value);
+            }
+        }
+
+        if ($params === []) {
+            return $hubUrl;
+        }
+
+        $separator = str_contains($hubUrl, '?') ? '&' : '?';
+
+        return $hubUrl . $separator . implode('&', $params);
+    }
+}