@cocoar/signalarrr 4.0.0-beta.15

package/dist/index.js

@@ -0,0 +1,333 @@
+// src/harrr-connection.ts
+import * as signalR from "@microsoft/signalr";
+
+// src/models/cancellation-token-reference.ts
+function isCancellationTokenReference(v) {
+  return typeof v === "object" && v !== null && typeof v["Id"] === "string";
+}
+
+// src/models/stream-reference.ts
+function isStreamReference(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  return typeof obj["Uri"] === "string" && Object.keys(obj).length === 1;
+}
+async function resolveStreamReference(ref) {
+  const response = await fetchStreamReference(ref);
+  return response.arrayBuffer();
+}
+async function resolveStreamReferenceAsStream(ref) {
+  const response = await fetchStreamReference(ref);
+  if (!response.body) {
+    throw new Error("StreamReference: response has no body stream");
+  }
+  return response.body;
+}
+async function fetchStreamReference(ref) {
+  const url = ref.Uri;
+  const scheme = url.split(":")[0]?.toLowerCase();
+  if (scheme !== "http" && scheme !== "https") {
+    throw new Error(`StreamReference: unsupported URI scheme '${scheme}'`);
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`StreamReference: download failed (${response.status} ${response.statusText})`);
+  }
+  return response;
+}
+
+// src/models/harrr-error.ts
+function parseHARRRError(error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  const marker = "HARRRException: ";
+  const markerIndex = msg.indexOf(marker);
+  const jsonCandidate = markerIndex >= 0 ? msg.substring(markerIndex + marker.length) : msg;
+  try {
+    const parsed = JSON.parse(jsonCandidate);
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.Type === "string" && typeof parsed.Message === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  const matches = /\[([\w.]+)\]\s*(.*)/m.exec(msg);
+  if (matches) {
+    return {
+      Type: matches[1] ?? "Error",
+      Message: matches[2] ?? msg
+    };
+  }
+  return {
+    Type: "Error",
+    Message: msg
+  };
+}
+
+// src/cancellation-manager.ts
+var CancellationManager = class {
+  _controllers = /* @__PURE__ */ new Map();
+  create(id) {
+    const controller = new AbortController();
+    this._controllers.set(id, controller);
+    return controller.signal;
+  }
+  cancel(id) {
+    const controller = this._controllers.get(id);
+    if (controller) {
+      controller.abort();
+      this._controllers.delete(id);
+    }
+  }
+  remove(id) {
+    this._controllers.delete(id);
+  }
+};
+
+// src/harrr-connection.ts
+var HARRRConnection = class _HARRRConnection {
+  _hubConnection;
+  _accessTokenFactory = () => "";
+  _serverRequestHandlers = /* @__PURE__ */ new Map();
+  _serverStreamHandlers = /* @__PURE__ */ new Map();
+  _cancellationManager = new CancellationManager();
+  get baseUrl() {
+    return this._hubConnection.baseUrl;
+  }
+  set baseUrl(value) {
+    this._hubConnection.baseUrl = value;
+  }
+  get connectionId() {
+    return this._hubConnection.connectionId;
+  }
+  get state() {
+    return this._hubConnection.state;
+  }
+  get serverTimeoutInMilliseconds() {
+    return this._hubConnection.serverTimeoutInMilliseconds;
+  }
+  set serverTimeoutInMilliseconds(value) {
+    this._hubConnection.serverTimeoutInMilliseconds = value;
+  }
+  get keepAliveIntervalInMilliseconds() {
+    return this._hubConnection.keepAliveIntervalInMilliseconds;
+  }
+  set keepAliveIntervalInMilliseconds(value) {
+    this._hubConnection.keepAliveIntervalInMilliseconds = value;
+  }
+  constructor(hubConnection, _options) {
+    this._hubConnection = hubConnection;
+    const conn = hubConnection["connection"];
+    const factory = conn?.["_options"]?.["accessTokenFactory"] ?? conn?.["_accessTokenFactory"];
+    if (typeof factory === "function") {
+      this._accessTokenFactory = factory;
+    }
+    this._hubConnection.on("ChallengeAuthentication", (req) => {
+      return this._accessTokenFactory();
+    });
+    this._hubConnection.on("InvokeServerRequest", async (req) => {
+      if (req.StreamId) {
+        await this._streamBackToServer(req, req.StreamId);
+        return void 0;
+      }
+      const result = await this._dispatchServerMethod(req);
+      if (result instanceof Blob || result instanceof ArrayBuffer || isNodeBuffer(result)) {
+        return await this._uploadAndReturnReference(result);
+      }
+      return result;
+    });
+    this._hubConnection.on("InvokeServerMessage", async (req) => {
+      try {
+        if (req.StreamId) {
+          await this._streamBackToServer(req, req.StreamId);
+        } else {
+          await this._dispatchServerMethod(req);
+        }
+      } catch {
+      }
+    });
+    this._hubConnection.on("CancelTokenFromServer", (req) => {
+      if (req.CancellationGuid) {
+        this._cancellationManager.cancel(req.CancellationGuid);
+      }
+    });
+  }
+  async _dispatchServerMethod(req) {
+    const handler = this._serverRequestHandlers.get(req.Method);
+    if (!handler) return void 0;
+    const args = await this._prepareArgs(req);
+    return await handler(...args);
+  }
+  async _prepareArgs(req) {
+    const args = [];
+    for (const arg of req.Arguments ?? []) {
+      if (isCancellationTokenReference(arg) && req.CancellationGuid) {
+        args.push(this._cancellationManager.create(req.CancellationGuid));
+      } else if (isStreamReference(arg)) {
+        args.push(await resolveStreamReference(arg));
+      } else {
+        args.push(arg);
+      }
+    }
+    return args;
+  }
+  async _streamBackToServer(req, streamId) {
+    const args = await this._prepareArgs(req);
+    try {
+      const streamHandler = this._serverStreamHandlers.get(req.Method);
+      if (streamHandler) {
+        const stream = streamHandler(...args);
+        for await (const item of stream) {
+          await this._hubConnection.send("StreamItemToServer", streamId, item);
+        }
+        await this._hubConnection.send("StreamCompleteToServer", streamId, null);
+        return;
+      }
+      const handler = this._serverRequestHandlers.get(req.Method);
+      if (handler) {
+        const result = await handler(...args);
+        if (result != null) {
+          if (typeof result === "object" && Symbol.asyncIterator in result) {
+            for await (const item of result) {
+              await this._hubConnection.send("StreamItemToServer", streamId, item);
+            }
+          } else {
+            await this._hubConnection.send("StreamItemToServer", streamId, result);
+          }
+        }
+        await this._hubConnection.send("StreamCompleteToServer", streamId, null);
+      } else {
+        await this._hubConnection.send("StreamCompleteToServer", streamId, null);
+      }
+    } catch (err) {
+      await this._hubConnection.send("StreamCompleteToServer", streamId, String(err));
+    }
+  }
+  async _uploadAndReturnReference(data) {
+    const uploadUrl = await this._hubConnection.invoke("RequestUploadSlot");
+    let body;
+    if (data instanceof Blob) {
+      body = data;
+    } else if (data instanceof ArrayBuffer || data instanceof Uint8Array) {
+      body = data;
+    } else {
+      body = String(data);
+    }
+    await fetch(uploadUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body
+    });
+    return { Uri: uploadUrl };
+  }
+  /** Prepare outgoing arguments — upload binary data and replace with StreamReferences. */
+  async _prepareOutgoingArgs(args) {
+    let hasStream = false;
+    for (const arg of args) {
+      if (arg instanceof Blob || arg instanceof ArrayBuffer || isNodeBuffer(arg)) {
+        hasStream = true;
+        break;
+      }
+    }
+    if (!hasStream) return args;
+    const result = [];
+    for (const arg of args) {
+      if (arg instanceof Blob || arg instanceof ArrayBuffer || isNodeBuffer(arg)) {
+        result.push(await this._uploadAndReturnReference(arg));
+      } else {
+        result.push(arg);
+      }
+    }
+    return result;
+  }
+  start() {
+    return this._hubConnection.start();
+  }
+  stop() {
+    return this._hubConnection.stop();
+  }
+  onClose(callback) {
+    this._hubConnection.onclose(callback);
+  }
+  onReconnecting(callback) {
+    this._hubConnection.onreconnecting(callback);
+  }
+  onReconnected(callback) {
+    this._hubConnection.onreconnected(callback);
+  }
+  async invoke(methodName, ...args) {
+    const preparedArgs = await this._prepareOutgoingArgs(args);
+    const msg = {
+      Method: methodName,
+      Arguments: preparedArgs,
+      Authorization: this._accessTokenFactory()
+    };
+    return this._hubConnection.invoke("InvokeMessageResult", msg).catch((err) => Promise.reject(this._extractException(err)));
+  }
+  async send(methodName, ...args) {
+    const preparedArgs = await this._prepareOutgoingArgs(args);
+    const msg = {
+      Method: methodName,
+      Arguments: preparedArgs,
+      Authorization: this._accessTokenFactory()
+    };
+    return this._hubConnection.send("SendMessage", msg);
+  }
+  stream(methodName, ...args) {
+    const msg = {
+      Method: methodName,
+      Arguments: args,
+      Authorization: this._accessTokenFactory()
+    };
+    return this._hubConnection.stream("StreamMessage", msg);
+  }
+  on(methodName, newMethod) {
+    this._hubConnection.on(methodName, newMethod);
+  }
+  /** Register a handler for server-to-client method calls (single return value). */
+  onServerMethod(methodName, func) {
+    this._serverRequestHandlers.set(methodName, func);
+    return this;
+  }
+  /** Register a handler for server-to-client streaming calls (returns AsyncIterable). */
+  onServerStreamMethod(methodName, func) {
+    this._serverStreamHandlers.set(methodName, func);
+    return this;
+  }
+  off(methodName, method) {
+    if (!method) {
+      this._hubConnection.off(methodName);
+    } else {
+      this._hubConnection.off(methodName, method);
+    }
+  }
+  asSignalRHubConnection() {
+    return this._hubConnection;
+  }
+  static create(hubConnection, options) {
+    if (hubConnection instanceof Function) {
+      const builder = new signalR.HubConnectionBuilder();
+      hubConnection(builder);
+      return new _HARRRConnection(builder.build(), options);
+    }
+    return new _HARRRConnection(hubConnection, options);
+  }
+  _extractException(error) {
+    const parsed = parseHARRRError(error);
+    return { type: parsed.Type, message: parsed.Message };
+  }
+};
+function isNodeBuffer(value) {
+  return typeof globalThis !== "undefined" && typeof globalThis["Buffer"] === "function" && typeof globalThis["Buffer"]["isBuffer"] === "function" && globalThis["Buffer"].isBuffer(value);
+}
+
+// src/harrr-connection-options.ts
+var HARRRConnectionOptions = class {
+};
+export {
+  HARRRConnection,
+  HARRRConnectionOptions,
+  isStreamReference,
+  parseHARRRError,
+  resolveStreamReference,
+  resolveStreamReferenceAsStream
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/harrr-connection.ts","../src/models/cancellation-token-reference.ts","../src/models/stream-reference.ts","../src/models/harrr-error.ts","../src/cancellation-manager.ts","../src/harrr-connection-options.ts"],"sourcesContent":["import * as signalR from '@microsoft/signalr';\nimport { ClientRequestMessage } from './models/client-request-message.js';\nimport { ServerRequestMessage } from './models/server-request-message.js';\nimport { isCancellationTokenReference } from './models/cancellation-token-reference.js';\nimport { isStreamReference, resolveStreamReference } from './models/stream-reference.js';\nimport { parseHARRRError } from './models/harrr-error.js';\nimport { HARRRConnectionOptions } from './harrr-connection-options.js';\nimport { CancellationManager } from './cancellation-manager.js';\n\nexport class HARRRConnection {\n  private _hubConnection: signalR.HubConnection;\n  private _accessTokenFactory: () => string = () => '';\n  private _serverRequestHandlers = new Map<string, (...args: unknown[]) => unknown>();\n  private _serverStreamHandlers = new Map<string, (...args: unknown[]) => AsyncIterable<unknown>>();\n  private _cancellationManager = new CancellationManager();\n\n  public get baseUrl(): string {\n    return this._hubConnection.baseUrl;\n  }\n\n  public set baseUrl(value: string) {\n    this._hubConnection.baseUrl = value;\n  }\n\n  public get connectionId(): string | null {\n    return this._hubConnection.connectionId;\n  }\n\n  public get state(): signalR.HubConnectionState {\n    return this._hubConnection.state;\n  }\n\n  public get serverTimeoutInMilliseconds(): number {\n    return this._hubConnection.serverTimeoutInMilliseconds;\n  }\n\n  public set serverTimeoutInMilliseconds(value: number) {\n    this._hubConnection.serverTimeoutInMilliseconds = value;\n  }\n\n  public get keepAliveIntervalInMilliseconds(): number {\n    return this._hubConnection.keepAliveIntervalInMilliseconds;\n  }\n\n  public set keepAliveIntervalInMilliseconds(value: number) {\n    this._hubConnection.keepAliveIntervalInMilliseconds = value;\n  }\n\n  constructor(hubConnection: signalR.HubConnection, _options?: HARRRConnectionOptions) {\n    this._hubConnection = hubConnection;\n\n    const conn = (hubConnection as unknown as Record<string, unknown>)['connection'] as Record<string, unknown> | undefined;\n    const factory =\n      (conn?.['_options'] as Record<string, unknown> | undefined)?.['accessTokenFactory'] ??\n      conn?.['_accessTokenFactory'];\n    if (typeof factory === 'function') {\n      this._accessTokenFactory = factory as () => string;\n    }\n\n    // Native client results — return values are sent back to the server automatically by SignalR\n    this._hubConnection.on('ChallengeAuthentication', (req: ServerRequestMessage) => {\n      return this._accessTokenFactory();\n    });\n\n    this._hubConnection.on('InvokeServerRequest', async (req: ServerRequestMessage) => {\n      // If StreamId is present, stream results back instead of returning a single value\n      if (req.StreamId) {\n        await this._streamBackToServer(req, req.StreamId);\n        return undefined;\n      }\n      const result = await this._dispatchServerMethod(req);\n\n      // If the result is binary data (Blob, ArrayBuffer, Buffer), upload via HTTP\n      // and return a StreamReference instead\n      if (result instanceof Blob || result instanceof ArrayBuffer ||\n          isNodeBuffer(result)) {\n        return await this._uploadAndReturnReference(result);\n      }\n\n      return result;\n    });\n\n    this._hubConnection.on('InvokeServerMessage', async (req: ServerRequestMessage) => {\n      try {\n        if (req.StreamId) {\n          await this._streamBackToServer(req, req.StreamId);\n        } else {\n          await this._dispatchServerMethod(req);\n        }\n      } catch {\n        // ignored — fire-and-forget\n      }\n    });\n\n    this._hubConnection.on('CancelTokenFromServer', (req: ServerRequestMessage) => {\n      if (req.CancellationGuid) {\n        this._cancellationManager.cancel(req.CancellationGuid);\n      }\n    });\n  }\n\n  private async _dispatchServerMethod(req: ServerRequestMessage): Promise<unknown> {\n    const handler = this._serverRequestHandlers.get(req.Method);\n    if (!handler) return undefined;\n\n    const args = await this._prepareArgs(req);\n    return await handler(...args);\n  }\n\n  private async _prepareArgs(req: ServerRequestMessage): Promise<unknown[]> {\n    const args: unknown[] = [];\n    for (const arg of req.Arguments ?? []) {\n      if (isCancellationTokenReference(arg) && req.CancellationGuid) {\n        args.push(this._cancellationManager.create(req.CancellationGuid));\n      } else if (isStreamReference(arg)) {\n        // Download the stream data via HTTP and pass as ArrayBuffer\n        args.push(await resolveStreamReference(arg));\n      } else {\n        args.push(arg);\n      }\n    }\n    return args;\n  }\n\n  private async _streamBackToServer(req: ServerRequestMessage, streamId: string): Promise<void> {\n    const args = await this._prepareArgs(req);\n\n    try {\n      // Try stream handler first\n      const streamHandler = this._serverStreamHandlers.get(req.Method);\n      if (streamHandler) {\n        const stream = streamHandler(...args);\n        for await (const item of stream) {\n          await this._hubConnection.send('StreamItemToServer', streamId, item);\n        }\n        await this._hubConnection.send('StreamCompleteToServer', streamId, null);\n        return;\n      }\n\n      // Fall back to regular handler — send single result as one item\n      const handler = this._serverRequestHandlers.get(req.Method);\n      if (handler) {\n        const result = await handler(...args);\n        if (result != null) {\n          // Check if result is async iterable\n          if (typeof result === 'object' && Symbol.asyncIterator in (result as object)) {\n            for await (const item of result as AsyncIterable<unknown>) {\n              await this._hubConnection.send('StreamItemToServer', streamId, item);\n            }\n          } else {\n            await this._hubConnection.send('StreamItemToServer', streamId, result);\n          }\n        }\n        await this._hubConnection.send('StreamCompleteToServer', streamId, null);\n      } else {\n        await this._hubConnection.send('StreamCompleteToServer', streamId, null);\n      }\n    } catch (err) {\n      await this._hubConnection.send('StreamCompleteToServer', streamId, String(err));\n    }\n  }\n\n  private async _uploadAndReturnReference(data: Blob | ArrayBuffer | Uint8Array | unknown): Promise<{ Uri: string }> {\n    // Request an upload URL from the server\n    const uploadUrl = await this._hubConnection.invoke<string>('RequestUploadSlot');\n\n    // Upload the data via HTTP POST\n    let body: BodyInit;\n    if (data instanceof Blob) {\n      body = data;\n    } else if (data instanceof ArrayBuffer || data instanceof Uint8Array) {\n      body = data as BodyInit;\n    } else {\n      body = String(data);\n    }\n    await fetch(uploadUrl, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/octet-stream' },\n      body,\n    });\n\n    return { Uri: uploadUrl };\n  }\n\n  /** Prepare outgoing arguments — upload binary data and replace with StreamReferences. */\n  private async _prepareOutgoingArgs(args: unknown[]): Promise<unknown[]> {\n    let hasStream = false;\n    for (const arg of args) {\n      if (arg instanceof Blob || arg instanceof ArrayBuffer ||\n          isNodeBuffer(arg)) {\n        hasStream = true;\n        break;\n      }\n    }\n    if (!hasStream) return args;\n\n    const result: unknown[] = [];\n    for (const arg of args) {\n      if (arg instanceof Blob || arg instanceof ArrayBuffer ||\n          isNodeBuffer(arg)) {\n        result.push(await this._uploadAndReturnReference(arg));\n      } else {\n        result.push(arg);\n      }\n    }\n    return result;\n  }\n\n  public start(): Promise<void> {\n    return this._hubConnection.start();\n  }\n\n  public stop(): Promise<void> {\n    return this._hubConnection.stop();\n  }\n\n  public onClose(callback: (error?: Error) => void): void {\n    this._hubConnection.onclose(callback);\n  }\n\n  public onReconnecting(callback: (error?: Error) => void): void {\n    this._hubConnection.onreconnecting(callback);\n  }\n\n  public onReconnected(callback: (connectionId?: string) => void): void {\n    this._hubConnection.onreconnected(callback);\n  }\n\n  public async invoke<T>(methodName: string, ...args: unknown[]): Promise<T> {\n    const preparedArgs = await this._prepareOutgoingArgs(args);\n    const msg: ClientRequestMessage = {\n      Method: methodName,\n      Arguments: preparedArgs,\n      Authorization: this._accessTokenFactory(),\n    };\n    return this._hubConnection\n      .invoke<T>('InvokeMessageResult', msg)\n      .catch(err => Promise.reject(this._extractException(err)));\n  }\n\n  public async send(methodName: string, ...args: unknown[]): Promise<void> {\n    const preparedArgs = await this._prepareOutgoingArgs(args);\n    const msg: ClientRequestMessage = {\n      Method: methodName,\n      Arguments: preparedArgs,\n      Authorization: this._accessTokenFactory(),\n    };\n    return this._hubConnection.send('SendMessage', msg);\n  }\n\n  public stream<T>(methodName: string, ...args: unknown[]): signalR.IStreamResult<T> {\n    const msg: ClientRequestMessage = {\n      Method: methodName,\n      Arguments: args,\n      Authorization: this._accessTokenFactory(),\n    };\n    return this._hubConnection.stream<T>('StreamMessage', msg);\n  }\n\n  public on(methodName: string, newMethod: (...args: any[]) => void): void {\n    this._hubConnection.on(methodName, newMethod);\n  }\n\n  /** Register a handler for server-to-client method calls (single return value). */\n  public onServerMethod(methodName: string, func: (...args: unknown[]) => unknown): this {\n    this._serverRequestHandlers.set(methodName, func);\n    return this;\n  }\n\n  /** Register a handler for server-to-client streaming calls (returns AsyncIterable). */\n  public onServerStreamMethod(methodName: string, func: (...args: unknown[]) => AsyncIterable<unknown>): this {\n    this._serverStreamHandlers.set(methodName, func);\n    return this;\n  }\n\n  public off(methodName: string): void;\n  public off(methodName: string, method: (...args: any[]) => void): void;\n  public off(methodName: string, method?: (...args: any[]) => void): void {\n    if (!method) {\n      this._hubConnection.off(methodName);\n    } else {\n      this._hubConnection.off(methodName, method);\n    }\n  }\n\n  public asSignalRHubConnection(): signalR.HubConnection {\n    return this._hubConnection;\n  }\n\n  public static create(\n    hubConnection: signalR.HubConnection | ((builder: signalR.HubConnectionBuilder) => void),\n    options?: HARRRConnectionOptions,\n  ): HARRRConnection {\n    if (hubConnection instanceof Function) {\n      const builder = new signalR.HubConnectionBuilder();\n      hubConnection(builder);\n      return new HARRRConnection(builder.build(), options);\n    }\n    return new HARRRConnection(hubConnection, options);\n  }\n\n  private _extractException(error: unknown): { type: string; message: string } {\n    const parsed = parseHARRRError(error);\n    return { type: parsed.Type, message: parsed.Message };\n  }\n}\n\n/** Runtime check for Node.js Buffer without importing @types/node */\nfunction isNodeBuffer(value: unknown): boolean {\n  return typeof globalThis !== 'undefined' &&\n    typeof (globalThis as Record<string, unknown>)['Buffer'] === 'function' &&\n    typeof ((globalThis as Record<string, unknown>)['Buffer'] as Record<string, unknown>)['isBuffer'] === 'function' &&\n    ((globalThis as Record<string, unknown>)['Buffer'] as { isBuffer: (v: unknown) => boolean }).isBuffer(value);\n}\n","export interface CancellationTokenReference {\n  Id: string;\n}\n\nexport function isCancellationTokenReference(v: unknown): v is CancellationTokenReference {\n  return typeof v === 'object' && v !== null && typeof (v as Record<string, unknown>)['Id'] === 'string';\n}\n","export interface StreamReference {\n  Uri: string;\n}\n\nexport function isStreamReference(v: unknown): v is StreamReference {\n  if (typeof v !== 'object' || v === null) return false;\n  const obj = v as Record<string, unknown>;\n  return typeof obj['Uri'] === 'string' && Object.keys(obj).length === 1;\n}\n\n/** Resolve a StreamReference by downloading the data — returns the full content buffered in memory. */\nexport async function resolveStreamReference(ref: StreamReference): Promise<ArrayBuffer> {\n  const response = await fetchStreamReference(ref);\n  return response.arrayBuffer();\n}\n\n/** Resolve a StreamReference as a ReadableStream — for large files, avoids buffering in memory. */\nexport async function resolveStreamReferenceAsStream(ref: StreamReference): Promise<ReadableStream<Uint8Array>> {\n  const response = await fetchStreamReference(ref);\n  if (!response.body) {\n    throw new Error('StreamReference: response has no body stream');\n  }\n  return response.body;\n}\n\nasync function fetchStreamReference(ref: StreamReference): Promise<Response> {\n  const url = ref.Uri;\n  const scheme = url.split(':')[0]?.toLowerCase();\n  if (scheme !== 'http' && scheme !== 'https') {\n    throw new Error(`StreamReference: unsupported URI scheme '${scheme}'`);\n  }\n  const response = await fetch(url);\n  if (!response.ok) {\n    throw new Error(`StreamReference: download failed (${response.status} ${response.statusText})`);\n  }\n  return response;\n}\n","/**\n * Structured error envelope from SignalARRR server exceptions.\n * The server serializes exceptions as JSON in the HubException message string.\n */\nexport interface HARRRError {\n  Type: string;\n  Message: string;\n  StackTrace?: string;\n}\n\n/**\n * Parse a HubException message into a structured HARRRError.\n * Supports both the new JSON format and the legacy `[Type] Message` format.\n *\n * SignalR wraps HubException messages with prefix text like:\n * \"An unexpected error occurred invoking '...' on the server. HARRRException: {json}\"\n */\nexport function parseHARRRError(error: unknown): HARRRError {\n  const msg = error instanceof Error ? error.message : String(error);\n\n  // Extract JSON after \"HARRRException: \" marker (SignalR wrapping)\n  const marker = 'HARRRException: ';\n  const markerIndex = msg.indexOf(marker);\n  const jsonCandidate = markerIndex >= 0 ? msg.substring(markerIndex + marker.length) : msg;\n\n  // Try JSON format\n  try {\n    const parsed = JSON.parse(jsonCandidate);\n    if (typeof parsed === 'object' && parsed !== null && typeof parsed.Type === 'string' && typeof parsed.Message === 'string') {\n      return parsed as HARRRError;\n    }\n  } catch {\n    // Not JSON — try legacy format\n  }\n\n  // Legacy format: [Type] Message\n  const matches = /\\[([\\w.]+)\\]\\s*(.*)/m.exec(msg);\n  if (matches) {\n    return {\n      Type: matches[1] ?? 'Error',\n      Message: matches[2] ?? msg,\n    };\n  }\n\n  // Fallback\n  return {\n    Type: 'Error',\n    Message: msg,\n  };\n}\n","export class CancellationManager {\n  private _controllers = new Map<string, AbortController>();\n\n  create(id: string): AbortSignal {\n    const controller = new AbortController();\n    this._controllers.set(id, controller);\n    return controller.signal;\n  }\n\n  cancel(id: string): void {\n    const controller = this._controllers.get(id);\n    if (controller) {\n      controller.abort();\n      this._controllers.delete(id);\n    }\n  }\n\n  remove(id: string): void {\n    this._controllers.delete(id);\n  }\n}\n","export class HARRRConnectionOptions {}\n"],"mappings":"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","names":[]}

package/docs/authorization.md

@@ -0,0 +1,182 @@
+# Authorization
+
+SignalARRR integrates with ASP.NET Core's authorization system. Use standard
+`[Authorize]` and `[AllowAnonymous]` attributes on hub methods and classes.
+
+---
+
+## Setup
+
+### Server configuration
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddAuthentication("Bearer")
+    .AddJwtBearer(options => {
+        options.Authority = "https://auth.example.com";
+        options.Audience = "my-api";
+    });
+
+builder.Services.AddAuthorization(options => {
+    options.AddPolicy("AdminOnly", policy =>
+        policy.RequireRole("admin"));
+    options.AddPolicy("Premium", policy =>
+        policy.RequireClaim("subscription", "premium"));
+});
+
+builder.Services.AddSignalR();
+builder.Services.AddSignalARRR(options => options
+    .AddServerMethodsFrom(typeof(Program).Assembly));
+
+var app = builder.Build();
+
+app.UseRouting();
+app.UseAuthentication();   // Must come before UseAuthorization
+app.UseAuthorization();
+app.MapHARRRController<ChatHub>("/chathub");
+```
+
+### Client token configuration
+
+```csharp
+var connection = HARRRConnection.Create(builder => {
+    builder.WithUrl("https://localhost:5001/chathub", options => {
+        options.AccessTokenProvider = () => Task.FromResult(GetJwtToken());
+    });
+});
+```
+
+---
+
+## Method-Level Authorization
+
+Apply `[Authorize]` to individual methods in ServerMethods classes:
+
+```csharp
+public class AdminMethods : ServerMethods<ChatHub> {
+
+    [Authorize("AdminOnly")]
+    public Task DeleteUser(int userId) {
+        // Only accessible to users with "admin" role
+        return _userService.Delete(userId);
+    }
+
+    [Authorize("Premium")]
+    public Task<List<string>> GetPremiumContent() {
+        return _contentService.GetPremium();
+    }
+
+    [AllowAnonymous]
+    public Task<string> GetPublicInfo() {
+        // Accessible to everyone, even without authentication
+        return Task.FromResult("Public info");
+    }
+}
+```
+
+---
+
+## Class-Level Authorization
+
+Apply `[Authorize]` to the ServerMethods class — all methods inherit it:
+
+```csharp
+[Authorize]
+public class SecureMethods : ServerMethods<ChatHub> {
+
+    // All methods require authentication
+    public Task<string> GetSecret() => Task.FromResult("secret");
+
+    [AllowAnonymous]
+    public Task<string> GetPublic() => Task.FromResult("public");
+}
+```
+
+---
+
+## Hub-Level Authorization Inheritance
+
+If the Hub class has `[Authorize]`, all ServerMethods classes for that hub
+inherit the authorization requirement automatically:
+
+```csharp
+[Authorize]  // All methods on all ServerMethods<SecureHub> require auth
+public class SecureHub : HARRR {
+    public SecureHub(IServiceProvider sp) : base(sp) { }
+}
+
+// This class inherits [Authorize] from SecureHub
+public class SecureHubMethods : ServerMethods<SecureHub> {
+
+    // Requires authentication (inherited from hub)
+    public Task<string> GetData() => Task.FromResult("data");
+
+    // Override: allow anonymous access despite hub-level auth
+    [AllowAnonymous]
+    public Task<string> GetPublicData() => Task.FromResult("public");
+}
+```
+
+### Inheritance priority
+
+Authorization attributes are resolved in this order:
+
+1. **Method-level** — `[Authorize]` or `[AllowAnonymous]` on the method itself
+2. **Class-level** — `[Authorize]` on the `ServerMethods<T>` class
+3. **Hub-level** — `[Authorize]` on the `HARRR` hub class (via `ServerMethods<T>` generic argument)
+
+If no authorization attributes are found at any level, the method is accessible
+anonymously.
+
+---
+
+## Authorization flow
+
+When a client calls an authorized method:
+
+1. SignalARRR checks for `[AllowAnonymous]` — if present, allows access
+2. Checks for `[Authorize]` on method → class → hub
+3. If authorization data exists:
+   a. Validates the token (from `AccessTokenProvider`) against configured schemes
+   b. Caches the authentication result until `ClientContext.UserValidUntil`
+   c. Evaluates the authorization policy
+4. If authentication has expired, sends a challenge to the client
+5. Client responds with a fresh token via the challenge protocol
+6. Server re-evaluates with the new token
+
+### Token caching
+
+SignalARRR caches successful authentication results. It only re-authenticates
+when `ClientContext.UserValidUntil` expires. This avoids re-validating the token
+on every RPC call.
+
+---
+
+## Accessing the authenticated user
+
+```csharp
+public class UserMethods : ServerMethods<ChatHub> {
+    public Task<string> WhoAmI() {
+        // From ClientContext (enhanced)
+        var user = ClientContext.User;
+        var name = user.Identity?.Name ?? "Anonymous";
+
+        // Or from standard SignalR context
+        var signalRUser = Context.User;
+
+        return Task.FromResult(name);
+    }
+}
+```
+
+---
+
+## SignalR negotiate-level auth
+
+Note that `[Authorize]` on the Hub class also blocks the SignalR negotiate
+endpoint (HTTP level). Unauthenticated clients will get a 401 response when
+trying to connect — they won't even establish a SignalR connection.
+
+This is different from method-level auth, where the connection succeeds but
+individual method calls are rejected.