@obsidiane/meridiane 2.0.7 → 2.0.11

package/templates/angular-bridge/src/lib/bridge/sse/mercure-url.builder.ts

@@ -0,0 +1,39 @@
+export class MercureUrlBuilder {
+  /**
+   * Builds the Mercure hub URL with one `topic=` parameter per topic.
+   * The adapter is responsible for canonicalising topics beforehand.
+   */
+  build(hubUrl: string, topics: ReadonlySet<string>, lastEventId?: string): string {
+    const url = new URL(hubUrl);
+    if (lastEventId) {
+      url.searchParams.set('lastEventID', lastEventId);
+    }
+    url.searchParams.delete('topic');
+    for (const topic of topics) {
+      url.searchParams.append('topic', topic);
+    }
+    return url.toString();
+  }
+
+  partitionTopics(hubUrl: string, topics: Iterable<string>, maxUrlLength: number, allowSplit: boolean): string[][] {
+    const sortedTopics = [...new Set(topics)].sort();
+    if (sortedTopics.length === 0) return [];
+    if (!allowSplit) return [sortedTopics];
+
+    const partitions: string[][] = [];
+    let current: string[] = [];
+
+    for (const topic of sortedTopics) {
+      const candidate = [...current, topic];
+      if (current.length > 0 && this.build(hubUrl, new Set(candidate)).length > maxUrlLength) {
+        partitions.push(current);
+        current = [topic];
+      } else {
+        current = candidate;
+      }
+    }
+
+    if (current.length > 0) partitions.push(current);
+    return partitions;
+  }
+}

package/templates/angular-bridge/src/lib/bridge/sse/mercure.adapter.ts

@@ -0,0 +1,358 @@
+import {inject, Injectable, OnDestroy, PLATFORM_ID} from '@angular/core';
+import {defer, EMPTY, fromEvent, Observable, Subject} from 'rxjs';
+import {auditTime, filter, finalize, map, takeUntil} from 'rxjs/operators';
+import {
+  API_BASE_URL,
+  BRIDGE_LOGGER,
+  BRIDGE_MERCURE_WITH_CREDENTIALS,
+  MERCURE_CONNECTION_MODE,
+  MERCURE_HUB_URL,
+  MERCURE_MAX_URL_LENGTH,
+  MERCURE_TOPIC_MODE,
+} from '../../tokens';
+import {
+  RealtimeDiagnostics,
+  WatchConnectionOptions,
+} from '../../bridge.types';
+import {RealtimeDiagnosticsPort, RealtimeEvent, RealtimeStatus, SubscribeFilter} from '../../ports/realtime.port';
+import {Iri, Item} from '../../ports/resource-repository.port';
+import {isPlatformBrowser} from '@angular/common';
+import {RefCountTopicRegistry} from './ref-count-topic.registry';
+import {MercureTopicMapper} from './mercure-topic.mapper';
+import {SubscriptionClaims, topicsKey} from './subscription-claims';
+import {createPayloadTopicMatcher, parseMercurePayload} from './mercure-payload';
+import {toIriList} from '../../utils/iri';
+import {IncomingMessage, MercureConnectionManager} from './mercure-connections';
+
+type SharedSubscriptionClaim = {
+  id: string;
+  topics: string[];
+  topicsKey: string;
+  stop$: Subject<void>;
+};
+
+type DedicatedSubscriptionClaim = {
+  id: string;
+  groupId: string;
+  topics: string[];
+  topicsKey: string;
+  incoming: Subject<IncomingMessage>;
+  stop$: Subject<void>;
+};
+
+type PreparedSubscription = {
+  iris: string[];
+  source$: Observable<IncomingMessage>;
+};
+
+@Injectable({providedIn: 'root'})
+export class MercureRealtimeAdapter implements RealtimeDiagnosticsPort, OnDestroy {
+  private readonly apiBase = inject(API_BASE_URL);
+  private readonly withCredentials = inject(BRIDGE_MERCURE_WITH_CREDENTIALS);
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly hubUrl = inject(MERCURE_HUB_URL, {optional: true}) ?? undefined;
+  private readonly topicMode = inject(MERCURE_TOPIC_MODE, {optional: true}) ?? 'url';
+  private readonly connectionMode = inject(MERCURE_CONNECTION_MODE, {optional: true}) ?? 'auto';
+  private readonly maxUrlLength = normalizeMaxUrlLength(
+    inject(MERCURE_MAX_URL_LENGTH, {optional: true}),
+    1900
+  );
+  private readonly logger = inject(BRIDGE_LOGGER, {optional: true}) ?? undefined;
+
+  private readonly destroy$ = new Subject<void>();
+  private readonly sharedRebuild$ = new Subject<void>();
+  private readonly incoming$ = new Subject<IncomingMessage>();
+  private shuttingDown = false;
+  private sequence = 0;
+
+  private readonly topicsRegistry = new RefCountTopicRegistry();
+  private readonly topicMapper = new MercureTopicMapper(this.apiBase, this.topicMode);
+  private readonly connectionManager = new MercureConnectionManager({
+    hubUrl: this.hubUrl,
+    withCredentials: this.withCredentials,
+    mode: this.connectionMode,
+    maxUrlLength: this.maxUrlLength,
+    logger: this.logger,
+    destroy$: this.destroy$,
+    nextId: (prefix) => `${prefix}-${++this.sequence}`,
+  });
+  private readonly sharedClaims = new SubscriptionClaims<SharedSubscriptionClaim>();
+  private readonly dedicatedClaims = new SubscriptionClaims<DedicatedSubscriptionClaim>();
+
+  constructor() {
+    this.sharedRebuild$.pipe(auditTime(10)).subscribe(() => this.rebuildSharedConnections());
+
+    if (isPlatformBrowser(this.platformId)) {
+      fromEvent<PageTransitionEvent>(window, 'pagehide')
+        .pipe(takeUntil(this.destroy$))
+        .subscribe(() => this.shutdownBeforeExit());
+
+      fromEvent<BeforeUnloadEvent>(window, 'beforeunload')
+        .pipe(takeUntil(this.destroy$))
+        .subscribe(() => this.shutdownBeforeExit());
+    }
+  }
+
+  status$(): Observable<RealtimeStatus> {
+    return this.connectionManager.status$;
+  }
+
+  diagnostics$(): Observable<RealtimeDiagnostics> {
+    return this.connectionManager.diagnostics$;
+  }
+
+  subscribe$<T>(
+    iris: Iri[],
+    subscribeFilter?: SubscribeFilter,
+    options?: WatchConnectionOptions
+  ): Observable<RealtimeEvent<T>> {
+    return defer(() => {
+      const subscription = this.prepareSubscription(iris, options);
+      if (!subscription) return EMPTY;
+
+      const matchTopic = createPayloadTopicMatcher(
+        subscription.iris,
+        subscribeFilter,
+        this.topicMapper
+      );
+
+      return this.payloads$(subscription.source$).pipe(
+        map((payload) => {
+          const topic = matchTopic(payload);
+          if (!topic) return undefined;
+
+          const rawId = payload?.['@id'];
+          const iri = typeof rawId === 'string' ? rawId : topic;
+          return {topic, iri, data: payload as T} as RealtimeEvent<T>;
+        }),
+        filter((event): event is RealtimeEvent<T> => event !== undefined)
+      );
+    });
+  }
+
+  subscribeAll$<T>(iris: Iri[], options?: WatchConnectionOptions): Observable<RealtimeEvent<T>> {
+    return defer(() => {
+      const subscription = this.prepareSubscription(iris, options);
+      if (!subscription) return EMPTY;
+
+      return this.payloads$(subscription.source$).pipe(
+        map((payload) => {
+          const rawId = payload['@id'];
+          const iri = typeof rawId === 'string' ? rawId : '';
+          return {iri, data: payload as T} as RealtimeEvent<T>;
+        })
+      );
+    });
+  }
+
+  unsubscribe(iris: Iri[]): void {
+    const inputIris = toIriList(iris);
+    if (inputIris.length === 0) return;
+
+    const topics = uniqueStrings(inputIris.map((iri) => this.topicMapper.toTopic(iri)));
+    if (this.releaseOneClaimByTopics(topics)) return;
+
+    // Claims are the source of truth. Never drop shared topics blindly when claims still exist:
+    // it could disconnect another active consumer.
+    if (this.sharedClaims.size === 0 && this.dedicatedClaims.size === 0) {
+      this.topicsRegistry.removeAll(topics);
+      this.scheduleSharedRebuild();
+      return;
+    }
+
+    this.logger?.warn?.('[Mercure] unsubscribe ignored: no matching active claim for topics', {topics});
+  }
+
+  shutdownBeforeExit(): void {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    this.teardownAllConnections();
+  }
+
+  ngOnDestroy(): void {
+    this.teardownAllConnections();
+    this.connectionManager.complete();
+    this.incoming$.complete();
+    this.destroy$.next();
+    this.destroy$.complete();
+    this.sharedRebuild$.complete();
+  }
+
+  private prepareSubscription(
+    iris: Iri[],
+    options?: WatchConnectionOptions
+  ): PreparedSubscription | undefined {
+    const inputIris = toIriList(iris);
+    if (inputIris.length === 0) return undefined;
+
+    if (!this.hubUrl) {
+      this.logger?.debug?.('[Mercure] hubUrl not configured → realtime disabled');
+      return undefined;
+    }
+
+    const topics = uniqueStrings(inputIris.map((iri) => this.topicMapper.toTopic(iri)));
+    return {
+      iris: inputIris,
+      source$: this.buildIncomingStream$(topics, options),
+    };
+  }
+
+  private payloads$(source$: Observable<IncomingMessage>): Observable<Item> {
+    return source$.pipe(
+      map((event) => parseMercurePayload(event.data, this.logger)),
+      filter((payload): payload is Item => payload !== undefined)
+    );
+  }
+
+  private buildIncomingStream$(topics: string[], options?: WatchConnectionOptions): Observable<IncomingMessage> {
+    const useDedicatedConnection = this.connectionMode === 'single' || options?.newConnection === true;
+    return useDedicatedConnection
+      ? this.subscribeViaDedicatedConnections$(topics)
+      : this.subscribeViaSharedConnections$(topics);
+  }
+
+  private subscribeViaSharedConnections$(topics: string[]): Observable<IncomingMessage> {
+    return defer(() => {
+      const uniqueTopics = uniqueStrings(topics);
+      if (uniqueTopics.length === 0) return EMPTY;
+      const claim = this.createSharedClaim(uniqueTopics);
+
+      return this.incoming$.pipe(
+        takeUntil(claim.stop$),
+        finalize(() => {
+          this.releaseSharedClaim(claim.id);
+        })
+      );
+    });
+  }
+
+  private subscribeViaDedicatedConnections$(topics: string[]): Observable<IncomingMessage> {
+    return defer(() => {
+      if (!this.hubUrl) return EMPTY;
+
+      const uniqueTopics = uniqueStrings(topics);
+      if (uniqueTopics.length === 0) return EMPTY;
+
+      const groupId = `dedicated-${++this.sequence}`;
+      const incoming = new Subject<IncomingMessage>();
+      const claim = this.createDedicatedClaim({groupId, topics: uniqueTopics, incoming});
+
+      try {
+        this.connectionManager.openDedicated(groupId, uniqueTopics, incoming);
+      } catch (error) {
+        this.logger?.error?.('[Mercure] dedicated connection setup failed:', error);
+        this.releaseDedicatedClaim(claim.id);
+        return EMPTY;
+      }
+
+      return incoming.asObservable().pipe(
+        takeUntil(claim.stop$),
+        finalize(() => {
+          this.releaseDedicatedClaim(claim.id);
+        })
+      );
+    });
+  }
+
+  private scheduleSharedRebuild(): void {
+    if (this.shuttingDown) return;
+    this.sharedRebuild$.next();
+  }
+
+  private rebuildSharedConnections(): void {
+    if (this.shuttingDown) return;
+
+    try {
+      if (!this.hubUrl || !this.topicsRegistry.hasAny()) {
+        this.connectionManager.closeShared();
+        return;
+      }
+
+      this.connectionManager.reconcileShared(this.topicsRegistry.snapshot(), this.incoming$);
+    } catch (error) {
+      this.logger?.error?.('[Mercure] shared rebuild failed:', error);
+    }
+  }
+
+  private createSharedClaim(topics: string[]): SharedSubscriptionClaim {
+    const normalizedTopics = uniqueStrings(topics);
+    const claim: SharedSubscriptionClaim = {
+      id: `shared-claim-${++this.sequence}`,
+      topics: normalizedTopics,
+      topicsKey: topicsKey(normalizedTopics),
+      stop$: new Subject<void>(),
+    };
+
+    this.sharedClaims.add(claim);
+    this.topicsRegistry.addAll(claim.topics);
+    this.scheduleSharedRebuild();
+
+    return claim;
+  }
+
+  private createDedicatedClaim(params: {
+    groupId: string;
+    topics: string[];
+    incoming: Subject<IncomingMessage>;
+  }): DedicatedSubscriptionClaim {
+    const normalizedTopics = uniqueStrings(params.topics);
+    const claim: DedicatedSubscriptionClaim = {
+      id: `dedicated-claim-${++this.sequence}`,
+      groupId: params.groupId,
+      topics: normalizedTopics,
+      topicsKey: topicsKey(normalizedTopics),
+      incoming: params.incoming,
+      stop$: new Subject<void>(),
+    };
+
+    this.dedicatedClaims.add(claim);
+    return claim;
+  }
+
+  private releaseOneClaimByTopics(topics: string[]): boolean {
+    const key = topicsKey(topics);
+    if (!key) return false;
+
+    if (this.connectionMode === 'single') {
+      return this.dedicatedClaims.stopNext(key) || this.sharedClaims.stopNext(key);
+    }
+
+    return this.sharedClaims.stopNext(key) || this.dedicatedClaims.stopNext(key);
+  }
+
+  private releaseSharedClaim(claimId: string): void {
+    const claim = this.sharedClaims.release(claimId);
+    if (!claim) return;
+
+    this.topicsRegistry.removeAll(claim.topics);
+    this.scheduleSharedRebuild();
+  }
+
+  private releaseDedicatedClaim(claimId: string): void {
+    const claim = this.dedicatedClaims.release(claimId);
+    if (!claim) return;
+
+    this.connectionManager.closeDedicated(claim.groupId);
+    claim.incoming.complete();
+  }
+
+  private teardownAllConnections(): void {
+    this.shuttingDown = true;
+    this.sharedClaims.stopAll();
+    this.dedicatedClaims.stopAll();
+
+    this.sharedClaims.clear();
+    this.dedicatedClaims.clear();
+    this.connectionManager.closeAll();
+  }
+}
+
+function normalizeMaxUrlLength(value: number | null | undefined, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  const rounded = Math.floor(value);
+  return rounded >= 256 ? rounded : fallback;
+}
+
+function uniqueStrings(values: Iterable<string>): string[] {
+  return [...new Set(values)];
+}

package/templates/{_lib_template → angular-bridge}/src/lib/bridge/sse/ref-count-topic.registry.ts

@@ -1,5 +1,4 @@
 export class RefCountTopicRegistry {
-  private readonly topics = new Set<string>();
   private readonly refCounts = new Map<string, number>();
 
   /**
@@ -8,9 +7,7 @@ export class RefCountTopicRegistry {
    */
   addAll(topics: Iterable<string>): void {
     for (const topic of topics) {
-      const next = (this.refCounts.get(topic) ?? 0) + 1;
-      this.refCounts.set(topic, next);
-      this.topics.add(topic);
+      this.refCounts.set(topic, (this.refCounts.get(topic) ?? 0) + 1);
     }
   }
 
@@ -23,7 +20,6 @@ export class RefCountTopicRegistry {
       const next = (this.refCounts.get(topic) ?? 0) - 1;
       if (next <= 0) {
         this.refCounts.delete(topic);
-        this.topics.delete(topic);
       } else {
         this.refCounts.set(topic, next);
       }
@@ -31,15 +27,10 @@ export class RefCountTopicRegistry {
   }
 
   hasAny(): boolean {
-    return this.topics.size > 0;
+    return this.refCounts.size > 0;
   }
 
   snapshot(): ReadonlySet<string> {
-    return new Set(this.topics);
-  }
-
-  computeKey(hubUrl: string, credentialsOn: boolean): string {
-    const topicsSorted = Array.from(this.topics).sort().join('|');
-    return `${hubUrl}::${credentialsOn ? '1' : '0'}::${topicsSorted}`;
+    return new Set(this.refCounts.keys());
   }
 }

package/templates/angular-bridge/src/lib/bridge/sse/subscription-claims.ts

@@ -0,0 +1,76 @@
+import {Subject} from 'rxjs';
+
+export interface SubscriptionClaim {
+  id: string;
+  topicsKey: string;
+  stop$: Subject<void>;
+}
+
+/** Tracks active subscriptions and preserves FIFO `unsubscribe(topics)` semantics. */
+export class SubscriptionClaims<T extends SubscriptionClaim> {
+  private readonly claims = new Map<string, T>();
+  private readonly queueByTopics = new Map<string, string[]>();
+
+  get size(): number {
+    return this.claims.size;
+  }
+
+  add(claim: T): void {
+    this.claims.set(claim.id, claim);
+    const queue = this.queueByTopics.get(claim.topicsKey) ?? [];
+    queue.push(claim.id);
+    this.queueByTopics.set(claim.topicsKey, queue);
+  }
+
+  release(claimId: string): T | undefined {
+    const claim = this.claims.get(claimId);
+    if (!claim) return undefined;
+
+    this.claims.delete(claimId);
+    this.removeFromQueue(claim);
+    return claim;
+  }
+
+  stopNext(topicsKey: string): boolean {
+    const queue = this.queueByTopics.get(topicsKey);
+    while (queue?.length) {
+      const claimId = queue[0];
+      if (this.stop(claimId)) return true;
+      queue.shift();
+    }
+
+    this.queueByTopics.delete(topicsKey);
+    return false;
+  }
+
+  stopAll(): void {
+    for (const claimId of [...this.claims.keys()]) this.stop(claimId);
+  }
+
+  clear(): void {
+    this.claims.clear();
+    this.queueByTopics.clear();
+  }
+
+  private stop(claimId: string): boolean {
+    const claim = this.claims.get(claimId);
+    if (!claim) return false;
+
+    claim.stop$.next();
+    claim.stop$.complete();
+    return true;
+  }
+
+  private removeFromQueue(claim: T): void {
+    const queue = this.queueByTopics.get(claim.topicsKey);
+    if (!queue) return;
+
+    const remaining = queue.filter((claimId) => claimId !== claim.id);
+    if (remaining.length > 0) this.queueByTopics.set(claim.topicsKey, remaining);
+    else this.queueByTopics.delete(claim.topicsKey);
+  }
+}
+
+export function topicsKey(topics: Iterable<string>): string {
+  return [...new Set(topics)].sort().join('|');
+}

package/templates/angular-bridge/src/lib/bridge-options.ts

@@ -0,0 +1,59 @@
+import {HttpInterceptorFn} from '@angular/common/http';
+import {BridgeDefaults, MercureConnectionMode, MercureTopicMode} from './bridge.types';
+
+export type BridgeAuth =
+  | string
+  | {type: 'bearer'; token: string}
+  | {type: 'bearer'; getToken: () => string | undefined | Promise<string | undefined>}
+  | HttpInterceptorFn;
+
+export interface BridgeMercureOptions {
+  hubUrl?: string;
+  init?: RequestInit;
+  topicMode?: MercureTopicMode;
+  /**
+   * Connection strategy for SSE subscriptions.
+   * - `single`: one SSE connection per watch subscription
+   * - `auto` (default): shared connections with automatic URL-length sharding
+   */
+  connectionMode?: MercureConnectionMode;
+  /**
+   * Maximum Mercure URL length before auto-sharding topics into multiple connections.
+   * Used only when `connectionMode: 'auto'`. Default: `1900`.
+   */
+  maxUrlLength?: number;
+}
+
+export interface BridgeHttpOptions {
+  /**
+   * Enables cookies / credentials on HTTP requests by default.
+   *
+   * When omitted, the bridge preserves the historical behavior and derives the
+   * HTTP value from `mercure.init.credentials`.
+   */
+  withCredentials?: boolean;
+}
+
+export interface BridgeOptions {
+  /** Base URL of the API (e.g. `http://localhost:8000`). */
+  baseUrl: string;
+  /** Auth strategy used to attach an Authorization header. */
+  auth?: BridgeAuth;
+  /** Default HTTP transport options. */
+  http?: BridgeHttpOptions;
+  /** Use `topicMode` to control the `topic=` values sent to the hub. */
+  mercure?: BridgeMercureOptions;
+  /** Default HTTP behaviour (headers, timeout, retries). */
+  defaults?: BridgeDefaults;
+  /**
+   * De-duplicates in-flight HTTP requests.
+   *
+   * - `true` (default): single-flight for safe methods (`GET/HEAD/OPTIONS`)
+   * - `false`: disabled (each call triggers a new request)
+   */
+  singleFlight?: boolean;
+  /** Enables debug logging via the debug interceptor and console logger. */
+  debug?: boolean;
+  /** Extra `HttpInterceptorFn` applied after bridge interceptors. */
+  extraInterceptors?: HttpInterceptorFn[];
+}