public override async ValueTask<int> ReadAsync( Memory<byte> destination, CancellationToken cancellationToken = default)
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 StreamFab.KeepStreams.Generic.Hook-Smeagol-TheR...
var encrypted = new HookSmeagol<EncryptionHook>(baseStream, encryptionHook); var logged = new HookSmeagol<LoggingHook>(encrypted, loggingHook); var throttled = new HookSmeagol<ThrottlingHook>(logged, throttlingHook); The order matters: the outermost hook sees data all inner hooks have processed it. In the example above, the logger records encrypted bytes, then the throttler sees the same encrypted payload. 6. Performance considerations | Aspect | Guidance | |--------|----------| | Allocation avoidance | Prefer the ReadAsync(Memory<byte>) / WriteAsync(ReadOnlyMemory<byte>) overloads to avoid array rentals. HookSmeagol forwards the exact Memory instance to the hook. | | Buffer reuse | If a hook needs a temporary buffer (e.g., for decryption), allocate it once in the hook’s constructor and reuse it across calls. | | Async‑over‑sync | Never call .Result or .Wait() inside a hook; it can dead‑lock the caller. Use await all the way. | | Seek support | Some inner streams are non‑seekable (e.g., network sockets). The hook must check inner.CanSeek before forwarding Seek . A typical pattern is to throw NotSupportedException if the underlying stream can’t seek. | | Cancellation | Pass the caller’s CancellationToken straight to inner async calls and to any async hook work. This keeps the whole pipeline responsive. | | Thread‑safety | HookSmeagol itself is not thread‑safe – it mirrors the underlying stream’s contract. If you need concurrent reads/writes, wrap the whole pipeline in a SemaphoreSlim or expose a thread‑safe façade. | | var compressor = new GZipStream(_inner, CompressionMode
// 1. Pre‑hook (may adjust the requested length) _hook.BeforeReadAsync(_ctx, destination, cancellationToken); | await _rateLimiter
// 2. The inner stream performs the real read int bytesRead = _inner.Read(buffer, offset, count);
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:
Typical overhead for a (i.e., a hook that just forwards everything) is ≈ 30–50 ns per call on modern .NET runtimes – negligible for most I/O‑bound workloads. Real‑world hooks (logging, encryption, compression) dominate the cost, not the wrapper. 7. Debugging & diagnostics HookSmeagol ships with a built‑in diagnostic source ( System.Diagnostics.DiagnosticListener ) named "StreamFab.KeepStreams.HookSmeagol" . It emits the following events: