@cocoar/signalarrr 4.0.0-beta.15

package/docs/streaming.md

@@ -0,0 +1,215 @@
+# Streaming
+
+SignalARRR supports streaming in both directions using `IAsyncEnumerable<T>`,
+`IObservable<T>`, and `ChannelReader<T>`.
+
+---
+
+## Server-to-Client Streaming
+
+### Define the contract
+
+```csharp
+[SignalARRRContract]
+public interface IChatHub {
+    IAsyncEnumerable<string> StreamMessages(CancellationToken ct);
+    IObservable<int> ObserveCountdown(int from);
+    ChannelReader<LogEntry> StreamLogs(string filter);
+}
+```
+
+### Implement on the server
+
+```csharp
+public class ChatMethods : ServerMethods<ChatHub>, IChatHub {
+
+    // IAsyncEnumerable — preferred for most streaming scenarios
+    public async IAsyncEnumerable<string> StreamMessages(
+        [EnumeratorCancellation] CancellationToken ct) {
+        while (!ct.IsCancellationRequested) {
+            yield return $"Message at {DateTime.Now:HH:mm:ss}";
+            await Task.Delay(1000, ct);
+        }
+    }
+
+    // IObservable — for Rx-based pipelines
+    public IObservable<int> ObserveCountdown(int from) {
+        return Observable.Interval(TimeSpan.FromSeconds(1))
+            .Take(from)
+            .Select(i => from - (int)i);
+    }
+
+    // ChannelReader — for producer/consumer patterns
+    public ChannelReader<LogEntry> StreamLogs(string filter) {
+        var channel = Channel.CreateUnbounded<LogEntry>();
+        _ = WriteLogsAsync(channel.Writer, filter);
+        return channel.Reader;
+    }
+
+    private async Task WriteLogsAsync(ChannelWriter<LogEntry> writer, string filter) {
+        try {
+            await foreach (var log in _logService.Watch(filter)) {
+                await writer.WriteAsync(log);
+            }
+        } finally {
+            writer.Complete();
+        }
+    }
+}
+```
+
+### Consume on the client
+
+```csharp
+var chat = connection.GetTypedMethods<IChatHub>();
+
+// IAsyncEnumerable — natural async iteration
+var cts = new CancellationTokenSource();
+await foreach (var msg in chat.StreamMessages(cts.Token)) {
+    Console.WriteLine(msg);
+    if (shouldStop) cts.Cancel();
+}
+
+// IObservable — Rx subscription
+chat.ObserveCountdown(10).Subscribe(
+    count => Console.WriteLine($"Countdown: {count}"),
+    () => Console.WriteLine("Done!"));
+
+// ChannelReader — read from channel
+var reader = chat.StreamLogs("error");
+while (await reader.WaitToReadAsync()) {
+    while (reader.TryRead(out var log)) {
+        Console.WriteLine(log);
+    }
+}
+```
+
+---
+
+## Client-to-Server Streaming (Server-Initiated)
+
+The server can request a stream from the client. The client returns
+`IAsyncEnumerable<T>` and SignalARRR handles the wire protocol automatically.
+
+### Define the client contract
+
+```csharp
+[SignalARRRContract]
+public interface IDataClient {
+    IAsyncEnumerable<int> StreamNumbers(int count);
+    Task<string> GetStatus();
+}
+```
+
+### Implement on the client
+
+```csharp
+public class DataClientImpl : IDataClient {
+    public async IAsyncEnumerable<int> StreamNumbers(int count) {
+        for (int i = 0; i < count; i++) {
+            yield return i;
+            await Task.Delay(100);
+        }
+    }
+
+    public Task<string> GetStatus() => Task.FromResult("OK");
+}
+
+// Register the implementation
+connection.MessageHandler.RegisterInterface<IDataClient, DataClientImpl>();
+```
+
+### Request the stream from the server
+
+```csharp
+public class DataMethods : ServerMethods<MyHub> {
+    public async Task ProcessClientData() {
+        // Get typed proxy for the calling client
+        var client = ClientContext.GetTypedMethods<IDataClient>();
+
+        // Stream data from the client
+        await foreach (var number in client.StreamNumbers(100)) {
+            Logger.LogInformation("Received: {Number}", number);
+        }
+    }
+}
+```
+
+### How it works internally
+
+1. Server calls `StreamNumbers(100)` on the client proxy
+2. Proxy sends a `ServerRequestMessage` with a `StreamId` to the client
+3. Client invokes `DataClientImpl.StreamNumbers(100)`
+4. Client enumerates the `IAsyncEnumerable<int>` and sends each item back
+   to the server via `StreamItemToServer(streamId, item)`
+5. Client signals completion via `StreamCompleteToServer(streamId, null)`
+6. Server reads items from a `Channel<object>` managed by `ServerStreamManager`
+7. Server receives items as `IAsyncEnumerable<T>` through the proxy
+
+---
+
+## Cancellation
+
+### Server-to-client stream cancellation
+
+Pass a `CancellationToken` to the streaming method. When cancelled, the server
+stops the stream:
+
+```csharp
+var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
+await foreach (var msg in chat.StreamMessages(cts.Token)) {
+    Console.WriteLine(msg);
+}
+// Stream stops after 30 seconds
+```
+
+On the server side, use `[EnumeratorCancellation]` on the `CancellationToken`
+parameter:
+
+```csharp
+public async IAsyncEnumerable<string> StreamMessages(
+    [EnumeratorCancellation] CancellationToken ct) {
+    // ct is cancelled when the client disconnects or cancels
+}
+```
+
+### Server-to-client CancellationToken propagation
+
+When the server calls a client method, it can pass a `CancellationToken` that
+propagates to the client:
+
+```csharp
+// Server side
+var cts = new CancellationTokenSource();
+var client = ClientContext.GetTypedMethods<IWorkerClient>();
+_ = client.DoLongWork(cts.Token);  // Token propagated to client
+
+// Later...
+cts.Cancel();  // Client's CancellationToken is cancelled remotely
+```
+
+```csharp
+// Client side
+public class WorkerImpl : IWorkerClient {
+    public async Task DoLongWork(CancellationToken ct) {
+        while (!ct.IsCancellationRequested) {
+            await Task.Delay(1000, ct);
+            // Cancelled when server calls cts.Cancel()
+        }
+    }
+}
+```
+
+---
+
+## Return type mapping
+
+| Contract return type | Proxy dispatch | Wire protocol |
+|---|---|---|
+| `IAsyncEnumerable<T>` | `StreamAsync<T>()` | `StreamMessage` |
+| `ChannelReader<T>` | `StreamAsync<T>()` → `ToChannelReader()` | `StreamMessage` |
+| `IObservable<T>` | `StreamAsync<T>()` → `ToObservable()` | `StreamMessage` |
+| `Task<T>` | `InvokeAsync<T>()` | `InvokeMessageResult` |
+| `Task` | `SendAsync()` | `InvokeMessage` |
+| `void` | `Send()` | `SendMessage` |
+| `T` (sync) | `Invoke<T>()` | `InvokeMessageResult` |

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cocoar/signalarrr",
+  "version": "4.0.0-beta.15",
+  "description": "TypeScript client for SignalARRR — type-safe RPC over SignalR",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "node scripts/copy-assets.cjs",
+    "postinstall": "node scripts/postinstall.cjs"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "docs/",
+    "scripts/"
+  ],
+  "author": "Bernhard Windisch",
+  "license": "ISC",
+  "dependencies": {
+    "@microsoft/signalr": "^10.0.0",
+    "@microsoft/signalr-protocol-msgpack": "^10.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/copy-assets.cjs

@@ -0,0 +1,34 @@
+'use strict';
+/**
+ * Runs at `prepack` (before npm pack / npm publish).
+ * Copies the repo-root skills/ and docs/ into the package directory so they
+ * are included in the published tarball.
+ * Safe to run outside the repo — exits silently if sources are not found.
+ */
+const { existsSync, mkdirSync, cpSync, rmSync } = require('node:fs');
+const { join } = require('node:path');
+
+const pkgRoot   = join(__dirname, '..');
+const repoRoot  = join(__dirname, '../../..');
+
+const skillsSrc = join(repoRoot, 'skills', 'signalarrr');
+const docsSrc   = join(repoRoot, 'docs');
+const skillsDst = join(pkgRoot,  'skills', 'signalarrr');
+const docsDst   = join(pkgRoot,  'docs');
+
+if (!existsSync(skillsSrc) || !existsSync(docsSrc)) {
+  console.log('[signalarrr] prepack: source assets not found — skipping copy');
+  process.exit(0);
+}
+
+// Clean and copy
+if (existsSync(skillsDst)) rmSync(skillsDst, { recursive: true, force: true });
+if (existsSync(docsDst))   rmSync(docsDst,   { recursive: true, force: true });
+
+mkdirSync(skillsDst, { recursive: true });
+mkdirSync(docsDst,   { recursive: true });
+
+cpSync(skillsSrc, skillsDst, { recursive: true });
+cpSync(docsSrc,   docsDst,   { recursive: true });
+
+console.log('[signalarrr] prepack: assets copied');

package/scripts/postinstall.cjs

@@ -0,0 +1,42 @@
+'use strict';
+/**
+ * Runs automatically after `npm install` in a consuming project.
+ * Mirrors the MSBuild buildTransitive targets behaviour:
+ *   - Only copies if .claude / .github already exists (no folder pollution)
+ *   - Copies SKILL.md  → {agentDir}/skills/signalarrr/
+ *   - Copies docs/     → {agentDir}/skills/signalarrr/references/
+ */
+const { existsSync, mkdirSync, cpSync } = require('node:fs');
+const { join } = require('node:path');
+
+const pkgRoot = join(__dirname, '..');
+
+// INIT_CWD is set by npm to the directory where `npm install` was invoked.
+const projectRoot = process.env.INIT_CWD ?? process.env.npm_config_local_prefix;
+
+// Guard: not a consuming project install (e.g. `npm install` run inside this package itself)
+if (!projectRoot || projectRoot === pkgRoot) process.exit(0);
+
+const skillsSrc = join(pkgRoot, 'skills', 'signalarrr');
+const docsSrc   = join(pkgRoot, 'docs');
+
+// Guard: assets were not bundled (dev build without prepack)
+if (!existsSync(skillsSrc)) process.exit(0);
+
+function copySkills(agentDir) {
+  if (!existsSync(agentDir)) return;
+
+  const skillsDst = join(agentDir, 'skills', 'signalarrr');
+  const refsDst   = join(agentDir, 'skills', 'signalarrr', 'references');
+
+  mkdirSync(skillsDst, { recursive: true });
+  mkdirSync(refsDst,   { recursive: true });
+
+  cpSync(skillsSrc, skillsDst, { recursive: true, force: true });
+  cpSync(docsSrc,   refsDst,   { recursive: true, force: true });
+
+  console.log(`[signalarrr] Skills copied to ${skillsDst}`);
+}
+
+copySkills(join(projectRoot, '.claude'));
+copySkills(join(projectRoot, '.github'));

package/skills/signalarrr/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: signalarrr
+description: >
+  Typed bidirectional RPC over SignalR using Cocoar.SignalARRR.
+  Use when working with HARRR hubs, ServerMethods, HARRRConnection,
+  [SignalARRRContract] interfaces, streaming (IAsyncEnumerable, IObservable,
+  ChannelReader), server-to-client calls, SignalARRR authorization,
+  or the @cocoar/signalarrr TypeScript/JavaScript npm client.
+metadata:
+  author: Bernhard Windisch
+  version: "4.0"
+---
+
+# Cocoar.SignalARRR
+
+SignalARRR extends ASP.NET Core SignalR with typed bidirectional RPC.
+Both server and client can call each other's methods through shared interfaces,
+with compile-time proxy generation, streaming, cancellation propagation, and
+ASP.NET Core authorization.
+
+## When to use this skill
+
+Use this skill when:
+- Setting up a HARRR hub or ServerMethods class
+- Creating or configuring a HARRRConnection (C# or TypeScript client)
+- Defining `[SignalARRRContract]` interfaces for typed RPC
+- Implementing streaming with IAsyncEnumerable, IObservable, or ChannelReader
+- Server needs to call client methods and await responses
+- Configuring authorization on hub methods
+- Using the `@cocoar/signalarrr` npm package in a JavaScript/TypeScript project
+- Troubleshooting SignalARRR connection or invocation issues
+
+## Package structure
+
+| Package | Purpose |
+|---|---|
+| `Cocoar.SignalARRR.Server` | Server-side: HARRR hub, ServerMethods, auth, ClientManager |
+| `Cocoar.SignalARRR.Client` | Client-side .NET: HARRRConnection, typed proxies |
+| `Cocoar.SignalARRR.Contracts` | Shared: `[SignalARRRContract]` attribute + source generator (reference from shared interface projects) |
+| `Cocoar.SignalARRR.Common` | Wire protocol types (referenced automatically) |
+| `Cocoar.SignalARRR.ProxyGenerator` | Proxy factory infrastructure (referenced automatically) |
+| `Cocoar.SignalARRR.DynamicProxy` | Opt-in runtime proxy fallback via DispatchProxy |
+| `Cocoar.SignalARRR.SourceGenerator` | Roslyn source generator (bundled in Contracts) |
+| `@cocoar/signalarrr` (npm) | TypeScript/JavaScript client: `HARRRConnection`, `invoke`, `send`, `stream`, `onServerMethod` |
+
+## Quick start
+
+### 1. Define shared interfaces
+
+In your shared project, reference `Cocoar.SignalARRR.Contracts`:
+
+```csharp
+[SignalARRRContract]
+public interface IChatHub {
+    Task SendMessage(string user, string message);
+    Task<List<string>> GetHistory();
+    IAsyncEnumerable<string> StreamMessages(CancellationToken ct);
+}
+
+[SignalARRRContract]
+public interface IChatClient {
+    void ReceiveMessage(string user, string message);
+    Task<string> GetClientName();
+}
+```
+
+### 2. Server setup
+
+```csharp
+// Program.cs
+services.AddSignalR();
+services.AddSignalARRR(options => options
+    .AddServerMethodsFrom(typeof(Program).Assembly));
+
+app.UseRouting();
+app.UseAuthentication();  // if using auth
+app.UseAuthorization();   // if using auth
+app.MapHARRRController<ChatHub>("/chathub");
+```
+
+```csharp
+// Hub
+public class ChatHub : HARRR {
+    public ChatHub(IServiceProvider sp) : base(sp) { }
+}
+
+// Server methods (auto-discovered)
+public class ChatMethods : ServerMethods<ChatHub>, IChatHub {
+    public Task SendMessage(string user, string message) {
+        Clients.All.SendAsync("ReceiveMessage", user, message);
+        return Task.CompletedTask;
+    }
+
+    public Task<List<string>> GetHistory() => Task.FromResult(new List<string>());
+
+    public async IAsyncEnumerable<string> StreamMessages(
+        [EnumeratorCancellation] CancellationToken ct) {
+        while (!ct.IsCancellationRequested) {
+            yield return $"msg-{DateTime.Now:ss}";
+            await Task.Delay(1000, ct);
+        }
+    }
+}
+```
+
+### 3. Client setup
+
+```csharp
+var connection = HARRRConnection.Create(builder => {
+    builder.WithUrl("https://localhost:5001/chathub");
+});
+
+await connection.StartAsync();
+
+// Typed calls
+var chat = connection.GetTypedMethods<IChatHub>();
+await chat.SendMessage("Alice", "Hello!");
+var history = await chat.GetHistory();
+
+// Streaming
+await foreach (var msg in chat.StreamMessages(cancellationToken)) {
+    Console.WriteLine(msg);
+}
+```
+
+### 4. Server-to-client calls
+
+```csharp
+// Inside a ServerMethods class — use ClientContext
+var client = ClientContext.GetTypedMethods<IChatClient>();
+var name = await client.GetClientName();
+
+// Outside hub context — inject ClientManager
+public class NotificationService {
+    private readonly ClientManager _clients;
+    public NotificationService(ClientManager clients) => _clients = clients;
+
+    public void NotifyClient(string connectionId) {
+        var client = _clients.GetTypedMethods<IChatClient>(connectionId);
+        client.ReceiveMessage("System", "Hello from server!");
+    }
+}
+```
+
+## Reference documentation
+
+For detailed API documentation, see:
+- [Getting Started](references/getting-started.md) — full setup walkthrough
+- [Server API](references/server-api.md) — HARRR, ServerMethods, ClientManager, AddSignalARRR
+- [Client API](references/client-api.md) — HARRRConnection, typed proxies, event handlers
+- [Streaming](references/streaming.md) — IAsyncEnumerable, IObservable, ChannelReader patterns
+- [Authorization](references/authorization.md) — [Authorize], hub-level inheritance, token flow
+- [Proxy Generation](references/proxy-generation.md) — [SignalARRRContract], source generator, DynamicProxy
+- [Migration from v2.x](references/migration-v4.md) — breaking changes and upgrade guide