Maps passive stream authorization results to safe pre-SSE HTTP responses and log fields.
Provides an in-memory implementation of IRazorWireStreamHub
using Channel{T}
for message distribution.
Live subscriber state is tracked separately from replay state. Empty live channels are removed after the last subscriber disconnects or after publish-time pruning finds stale writers, while replay buffers remain available until the bounded replay retention policy removes them. The hub keeps up to 25 retained messages per replay channel and prunes inactive replay channels when more than 256 replay channels are retained.
ValueTask PublishAsync(string channel, string message)
Publishes a message to all subscribers of the specified channel. Any subscribers that are closed or unable to accept the message are removed during the process.
channel
message
`ValueTask.CompletedTask` on success, or a faulted `ValueTask` containing the exception if publishing failed.
ChannelReader<string> Subscribe(string channel)
Subscribes to a named channel and returns a reader that receives messages published to that channel. The subscription uses an in-memory bounded buffer with capacity 100 that drops the oldest messages when full.
channel
A ChannelReader{String}
that yields messages published to the specified channel until the subscription is removed or the writer is completed.
void Unsubscribe(string channel, ChannelReader<string> reader)
Unregisters a subscriber from the specified channel and completes its associated writer.
channel
reader
ChannelReader{String}
; its paired writer will be completed and removed from channel tracking.InMemoryRazorWireStreamHubDiagnostics GetDiagnostics()
Gets internal stream state counts used by regression tests to verify cleanup behavior.
A snapshot of live and replay tracking counts.
bool TryCompleteSubscriberWriterForTesting(ChannelReader<string> reader)
Completes the writer for an active subscription without removing the subscription maps.
reader
true
when the reader belongs to an active subscription; otherwise, false
.
This internal test seam simulates a writer closed by channel infrastructure so publish-time pruning can be verified through the same cleanup path that handles stale live subscribers.
Action? AfterLiveChannelRetiredForTesting { get; set; }
Source
Gets or sets an internal test hook that runs after an empty live channel state is retired and before it is removed from the live channel map.
Production code leaves this unset. Regression tests use it to force subscribe/cleanup interleavings that would otherwise depend on timing.
Action<string>? BeforeReplayPruneCandidateForTesting { get; set; }
Source
Gets or sets an internal test hook that runs before a replay prune candidate takes its channel stripe lock.
Production code leaves this unset. Regression tests use it to force publish/prune interleavings that would otherwise depend on timing.
Represents a snapshot of internal stream tracking counts used by the RazorWire test suite.
LiveChannelCount
LiveSubscriberCount
SubscriptionCount
ReplayChannelCount
Options that control how a RazorWire stream message is published.
Replay is disabled by default so existing channels remain live-only. Enable Replay
only for idempotent state snapshots or bounded progress events that are safe for late subscribers to receive after publish. The in-memory hub retains at most 25 messages per replay channel and prunes inactive replay channels when more than 256 replay channels are retained.
bool Replay { get; init; }
Source
Gets a value indicating whether this message should be retained in the bounded replay buffer for its channel. Retained messages survive live subscriber disconnects until normal replay pruning removes them.
Options that control how a RazorWire stream subscription is created.
Replay is opt-in per subscription. A replaying subscriber first receives the channel's retained messages, then receives live messages like any other subscriber. The in-memory hub bounds replay storage and drops the oldest retained messages when the channel exceeds its replay capacity of 25 messages, and prunes inactive replay channels when more than 256 replay channels are retained.
bool Replay { get; init; }
Source
Gets a value indicating whether retained channel messages should be delivered before live messages. A replay subscription to a channel with no retained messages does not create a durable replay buffer.
Defines the contract for a message hub that supports pub/sub operations over named channels.
Implementations may keep live subscriber state and replay retention state separately. Live subscriptions should be released when readers disconnect, while opt-in replay buffers may outlive live subscribers until the implementation's bounded retention policy prunes them.
ValueTask PublishAsync(string channel, string message)
Publishes a trusted stream message to the specified channel.
channel
message
A ValueTask
that completes when the publish operation has finished.
Prefer publishing output from Bridge.RazorWireStreamBuilder
so plain-text values are encoded before the message reaches the hub. If composing a raw message, encode user-supplied values before publishing.
ValueTask PublishAsync(string channel, string message, RazorWireStreamPublishOptions? options)
Publishes a trusted stream message to the specified channel with explicit delivery options.
channel
message
options
PublishAsync(string, string)
. Implementations that support replay retention or other optioned semantics must override this overload.
A ValueTask
that completes when the publish operation has finished.
Pitfall: callers should not expect RazorWireStreamPublishOptions
to be honored unless the concrete IRazorWireStreamHub
implementation overrides this member. The hub is also a raw transport boundary: use Bridge.RazorWireStreamBuilder
or encode user-supplied values before publishing raw stream strings.
ChannelReader<string> Subscribe(string channel)
Subscribes to a named message channel and provides a reader for incoming messages.
channel
A ChannelReader{String}
that yields messages published to the specified channel; the reader completes when the subscription is removed or the hub shuts down.
ChannelReader<string> Subscribe(string channel, RazorWireStreamSubscribeOptions? options)
Subscribes to a named message channel with explicit subscription options.
channel
options
Subscribe(string)
.
A ChannelReader{String}
for the specified channel. Replay semantics are available only when the concrete implementation overrides this overload.
Pitfall: RazorWireStreamSubscribeOptions.Replay
is an opt-in contract between caller and hub implementation; the interface fallback remains live-only for backward compatibility. Replay should be reserved for idempotent retained state, not one-shot commands or sensitive payloads.
void Unsubscribe(string channel, ChannelReader<string> reader)
Unsubscribes the specified reader from the named channel so it no longer receives messages from that channel.
channel
reader
Defines the result-bearing contract for authorizing RazorWire stream subscription requests.
Implement this interface when a stream needs to distinguish unauthenticated, forbidden, stale-session, unsafe-navigation, or host setup-failure outcomes. RazorWire consumes the passive AppSurfaceAuthResult
before opening Server-Sent Events; it does not challenge, forbid, redirect, mutate cookies, evaluate host policies, or echo app-supplied auth messages.
ValueTask<AppSurfaceAuthResult> AuthorizeAsync(RazorWireStreamAuthorizationContext context)
Authorizes the current HTTP request for the requested RazorWire stream channel.
context
A non-null AppSurfaceAuthResult
describing whether the subscription may proceed. RazorWire defensively treats a null
result from a misbehaving implementation as a setup failure.
Carries request and configuration context for a RazorWire stream authorization decision.
ConfiguredAuthorizationMode
is diagnostic context from RazorWireOptions.Streams
. It is not proof of the effective decision when the host registers a custom IRazorWireStreamAuthorizer
or legacy IRazorWireChannelAuthorizer
.
HttpContext HttpContext { get; }
Source
Gets the current HTTP request context.
string Channel { get; }
Source
Gets the validated stream channel name requested by the client.
RazorWireStreamAuthorizationMode ConfiguredAuthorizationMode { get; }
Source
Gets the configured stream authorization mode from RazorWireOptions.Streams
.
CancellationToken RequestAborted { get; }
Source
Gets the request-aborted cancellation token for the stream subscription request.
Defines the contract for authorizing subscription requests to RazorWire channels.
ValueTask<bool> CanSubscribeAsync(HttpContext context, string channel)
Determines whether the current HTTP request is permitted to subscribe to the specified channel.
context
channel
true
if subscription is permitted, false
otherwise.
Provides a built-in implementation of IRazorWireChannelAuthorizer
that denies all subscriptions.
This is RazorWire's safe default when no app-specific authorizer is registered. Keep ForgeTrust.RazorWire.RazorWireStreamAuthorizationMode.DenyAll
for production defaults, set ForgeTrust.RazorWire.RazorWireStreamOptions.AuthorizationMode
to ForgeTrust.RazorWire.RazorWireStreamAuthorizationMode.AllowAll
only for public/demo streams, and register a custom IRazorWireStreamAuthorizer
for user, tenant, or workflow-specific channels. Use this bool authorizer contract when simple legacy allow/deny compatibility is enough.
ValueTask<bool> CanSubscribeAsync(HttpContext context, string channel)
Determines whether the request represented by the context
may subscribe to the specified channel.
context
channel
false
for every request.
Provides a built-in implementation of IRazorWireChannelAuthorizer
that permits all subscriptions.
This authorizer is intended for public, demo, or local-development streams only. Do not use it for channels that include user-specific, tenant-specific, workflow-specific, or otherwise sensitive data.
ValueTask<bool> CanSubscribeAsync(HttpContext context, string channel)
Determines whether the request represented by the context
may subscribe to the specified channel.
context
channel
true
for every request.
Prefer a custom IRazorWireStreamAuthorizer
for production streams that depend on HttpContext.User
or other request state. Use IRazorWireChannelAuthorizer
when a simple legacy allow/deny decision is enough.
Controls admission for live RazorWire stream subscriptions in the current application process.
The controller is the endpoint-side guardrail that sits before IRazorWireStreamHub.Subscribe(string, RazorWireStreamSubscribeOptions)
. It validates decoded channel names, enforces the configured live-channel and live-subscription limits from RazorWireStreamOptions
, and returns a disposable lease for accepted requests.
Use this controller for bounded in-process SSE fanout. It is not a distributed quota system, an IP/user fairness mechanism, or a replacement for ASP.NET Core rate limiting, reverse-proxy limits, SignalR, or managed pub/sub. Each accepted live SSE request consumes one subscription slot until the lease is disposed.
State changes are synchronized by an internal lock. Callers must dispose accepted leases exactly once the endpoint is done with the matching hub subscription; the lease itself is idempotent, but skipping disposal leaves admission capacity reserved for the lifetime of the process. Rejection metrics are low-cardinality diagnostics tagged only by rejection reason.
RazorWireStreamAdmissionResult TryAcquire(string channel)
Attempts to reserve live stream capacity for a decoded channel name.
channel
An accepted result with a disposable lease when the channel is valid and all configured limits allow the subscription; otherwise, a rejected result that identifies the first failed validation or capacity check.
This method validates channel grammar before capacity checks. Accepted callers must subscribe to the hub only after this method succeeds and must dispose the returned lease after unsubscribing. Failed results record the rejection metric and do not reserve capacity.
RazorWireStreamAdmissionResult RejectPreAuthorizationValidation(string channel, RazorWireStreamAdmissionRejectionReason reason)
Records a pre-authorization channel validation rejection without reserving live stream capacity.
channel
reason
RazorWireStreamAdmissionRejectionReason.InvalidChannelName
and RazorWireStreamAdmissionRejectionReason.ChannelNameTooLong
are valid here. A rejected result that includes the current live-count snapshot and records the rejection metric.
RazorWire validates malformed channels before resolving custom authorizers so bad input returns 400
without invoking host authorization code. Use this method for that non-acquiring path so diagnostics and metrics stay consistent with capacity rejections. Do not use it for authorization denials or capacity failures.
RazorWireStreamAdmissionSnapshot Snapshot { get; }
Source
Gets the current in-process live subscription and live channel counts.
The snapshot is moment-in-time diagnostic state. It is useful for development responses, logs, and tests, but it should not be treated as a stable concurrency token because another request can change the counts immediately after the snapshot is read.
Represents one accepted live stream admission reservation.
Dispose the lease after the corresponding hub subscription is removed. Disposal is idempotent so nested cleanup paths can call it safely, but the endpoint should still keep lease lifetime aligned with the hub reader lifetime.
void Dispose()
Releases the reserved subscription slot and, when this was the final subscriber, the live channel slot.
Describes the outcome of a RazorWire stream admission attempt.
Accepted
Lease
null
for rejections.RejectionReason
null
for accepted results.ChannelLength
Current
Snapshot
Consumers should branch on Accepted
. Do not assume Lease
is present unless admission was accepted, and do not expose raw channel names in logs or diagnostics when building responses from rejected results.
RazorWireStreamAdmissionResult Accept(RazorWireStreamAdmissionController.RazorWireStreamAdmissionLease lease, RazorWireStreamAdmissionSnapshot snapshot)
Creates an accepted result for a reserved subscription.
lease
snapshot
An accepted admission result.
RazorWireStreamAdmissionResult Rejected(RazorWireStreamAdmissionRejectionReason reason, int channelLength, int current, RazorWireStreamAdmissionSnapshot snapshot)
Creates a rejected result without reserving capacity.
reason
channelLength
current
snapshot
A rejected admission result.
Captures live stream admission counts at one point in time.
LiveSubscriptions
LiveChannels
Snapshots are diagnostic values for logs, development responses, and tests. They are not durable counters and should not be used for distributed fairness or cross-node capacity planning.
Provides an optional pre-authorizer for RazorWire stream subscriptions before the active stream authorizer runs.
Register filters when a package or module owns a reserved channel and must enforce a channel-specific gate that normal host IRazorWireStreamAuthorizer
replacement should not bypass. Return null
when the filter does not apply to the requested channel. Return an allowed result to let later filters and the active stream authorizer continue, or return a denial/setup-failure result to stop the subscription before the stream opens.
ValueTask<AppSurfaceAuthResult?> AuthorizeAsync(RazorWireStreamAuthorizationContext context)
Evaluates a pre-authorization gate for the requested stream subscription.
context
null
when the filter does not apply; otherwise an AppSurface auth result whose denial stops the subscription and whose allowed outcome lets normal stream authorization continue.
Bridges legacy bool channel authorizers into the result-bearing stream authorization contract.
The adapter resolves IRazorWireChannelAuthorizer
from the current request services on every authorization call. This preserves legacy before/after AddRazorWire
registration behavior and avoids capturing scoped or transient authorizers in a singleton adapter.
ValueTask<(AppSurfaceAuthResult Result, string AuthorizerType)> AuthorizeWithResolvedAuthorizerAsync(RazorWireStreamAuthorizationContext context, IRazorWireChannelAuthorizer? channelAuthorizer = null)
Authorizes a stream by mapping the legacy channel authorizer's boolean decision to an auth result.
context
channelAuthorizer
The mapped result and the resolved legacy authorizer type. true
maps to AppSurfaceAuthResult.Allowed
; false
maps to AppSurfaceAuthResult.Challenge
for anonymous callers and AppSurfaceAuthResult.Forbidden
for authenticated callers.
Use channelAuthorizer
only when it was resolved from the same HttpContext.RequestServices
scope represented by context
. Supplying a cached scoped or transient legacy authorizer from another request can break host lifetime expectations.
IRazorWireChannelAuthorizer ResolveChannelAuthorizer(RazorWireStreamAuthorizationContext context)
Resolves the effective legacy channel authorizer from the current request service scope.
context
HttpContext.RequestServices
scope is active.
The request-scoped IRazorWireChannelAuthorizer
used for the current subscription attempt.
This method intentionally resolves per request instead of capturing the channel authorizer in the singleton adapter. That preserves scoped and transient legacy authorizers and keeps before/after AddRazorWire
registration behavior compatible.
string GetAuthorizerType(IRazorWireChannelAuthorizer channelAuthorizer)
Returns the diagnostic type name for a resolved legacy channel authorizer.
channelAuthorizer
The authorizer's full type name when available, otherwise its simple type name. The returned value is safe for low-cardinality diagnostics and avoids exception messages, channel names, users, and claims.
Identifies why a RazorWire stream admission request was rejected.
Validation reasons map to HTTP 400
. Capacity reasons map to HTTP 429
. Authorization denials are handled separately and continue to map to HTTP 403
.