// Then the inner stream is disposed (unless the hook says otherwise) _inner.Dispose(); base.Dispose(disposing);

| Responsibility | Why it matters | |----------------|----------------| | inbound/outbound data flowing through any System.IO.Stream ‑derived object without breaking the original contract. | Enables logging, diagnostics, transformation, or throttling of data pipelines (e.g., network sockets, file streams, compression streams). | | Preserve the original stream’s semantics (async/sync, seeking, length, timeouts). | Guarantees drop‑in replacement – callers do not need to change their code. | | Compose multiple hooks (e.g., logging + encryption + compression) in a deterministic order. | Keeps the pipeline modular and testable. | | Dispose safely – the hook forwards Dispose / DisposeAsync while also releasing its own resources (buffers, diagnostic listeners). | Prevents resource leaks in long‑running services. |

The async version ( DisposeAsync ) follows the same order with await . | Hook name | Typical use‑case | Sample code fragment | |-----------|------------------|----------------------| | LoggingHook | Write a line‑by‑line trace of every read/write, optionally throttling large payloads. | await logger.LogAsync($"bytesRead bytes read from ctx.StreamId"); | | CompressionHook | Transparent GZip/Deflate compression on the fly. | var compressor = new GZipStream(_inner, CompressionMode.Compress, leaveOpen:true); | | EncryptionHook | Apply AES‑CTR or ChaCha20 encryption per‑chunk. | Array.Copy(_cipher.TransformBlock(buffer, offset, count), 0, buffer, offset, count); | | MetricsHook | Emit Prometheus counters or OpenTelemetry spans for each operation. | meter.CreateHistogram<long>("stream.read.bytes").Record(bytesRead); | | ThrottlingHook | Enforce a max‑bytes‑per‑second quota. | await _rateLimiter.WaitAsync(bytesRead, cancellationToken); | Why the name “Smeagol”? In the original open‑source demo the author likened the hook to Smeagol – it “follows” the stream everywhere, silently observing and occasionally meddling. The name stuck and became part of the public API. 5. Extending the hook – writing your own THook 5.1 Minimal stub public sealed class MyCustomHook : IStreamHook

public override async ValueTask<int> ReadAsync( Memory<byte> destination, CancellationToken cancellationToken = default)

services.AddSingleton<IHookFactory<MyCustomHook>, MyCustomHookFactory>(); services.AddTransient(typeof(Stream), provider =>

// 3. Hook can post‑process the data (e.g., logging, decryption) _hook.AfterRead(_ctx, buffer, offset, bytesRead);

// 3. Post‑hook (e.g., logging, decryption, metrics) await _hook.AfterReadAsync(_ctx, destination.Slice(0, bytesRead), cancellationToken) .ConfigureAwait(false);

// 2. Actual read from inner stream int bytesRead = await _inner.ReadAsync(destination, cancellationToken) .ConfigureAwait(false);

// Async overloads (optional but recommended) public ValueTask BeforeReadAsync(IHookContext ctx, Memory<byte> destination, CancellationToken ct) => default; public ValueTask AfterReadAsync(IHookContext ctx, ReadOnlyMemory<byte> data, CancellationToken ct) => default; // … similar for Write, Seek, etc.

public void BeforeRead(IHookContext ctx, byte[] buffer, int offset, int count) /* … */ public void AfterRead(IHookContext ctx, byte[] buffer, int offset, int bytesRead) /* … */

var listener = new DiagnosticListener("StreamFab.KeepStreams.HookSmeagol"); listener.Subscribe(new MyObserver()); These events are invaluable when you need to without modifying the hook code itself. 8. Common pitfalls & how to avoid them | Pitfall | Symptom | Fix | |---------|---------|-----| | Double‑dispose | ObjectDisposedException on later reads/writes. | Ensure the hook does not call Dispose on the inner stream unless it owns it. The wrapper already disposes the inner stream once. | | Blocking async hooks | Thread‑pool starvation, deadlocks. | Never use .Result / .Wait() inside async hook methods; always await . | | Changing CanSeek | Consumer thinks the stream is seekable but it isn’t. | Propagate CanSeek from the inner stream unchanged; if you need to add seeking (e.g., buffering), expose a new wrapper type rather than HookSmeagol . | | Unbounded memory growth | Hook buffers grow without limit (e.g., a logging hook that stores every payload). | Use bounded buffers or stream the data to a file/DB as it arrives. | | Incorrect async signature | ValueTask returned but not awaited → lost exceptions. | Always await the returned ValueTask inside the wrapper (the library already does this). | 9. Sample end‑to‑end usage Below is a short, self‑contained console demo that composes three hooks: