Hmz.Core.Realtime.Abstractions 0.1.0

dotnet add package Hmz.Core.Realtime.Abstractions --version 0.1.0
                    
NuGet\Install-Package Hmz.Core.Realtime.Abstractions -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Hmz.Core.Realtime.Abstractions" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Hmz.Core.Realtime.Abstractions" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Hmz.Core.Realtime.Abstractions" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Hmz.Core.Realtime.Abstractions --version 0.1.0
                    
#r "nuget: Hmz.Core.Realtime.Abstractions, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Hmz.Core.Realtime.Abstractions@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Hmz.Core.Realtime.Abstractions&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Hmz.Core.Realtime.Abstractions&version=0.1.0
                    
Install as a Cake Tool

Hmz.Core.Realtime.Abstractions

The contracts of the Hmz realtime engine (Hmz.Core.Realtime): what a feature calls to push a live hint to connected clients, and the seams an adapter implements to change how events travel. The package has no ASP.NET Core dependency, so a Contracts, Domain or worker project can publish.

Namespace: Hmz.Core.Realtime.Abstractions.

Types

Type Purpose
IRealtimePublisher The application port. Best effort and losable: never throws for a delivery failure.
RealtimePublisherExtensions.PublishAsync<T>(type, audience, data, JsonTypeInfo<T>, eventId?, ct) Serializes the payload once with source-generated JSON and publishes it.
RealtimeEvent Type, audience, optional id and the payload as UTF-8 JSON, shared by every recipient. RealtimeEvent.Create<T> serializes.
RealtimeEventTypes Type-name rules (IsValid, MaxLength) and the reserved heartbeat type Ping (ping).
RealtimeAudience, RealtimeUserAudience Who receives an event: RealtimeAudience.User(id) / Users(ids) today; groups or topics can be added later.
IRealtimeBackplane Fan-out across instances: PublishAsync and Subscribe(transport) for local delivery.
IRealtimeTransport The transport seam (SSE built in; a SignalR adapter later): Deliver, HasConnection, Name.
IRealtimePresence MayBeConnected(userId): lets a publisher skip per-user work for users nobody would receive it for.
IRealtimeEventAuthorizer, RealtimeSubscriber Optional per-connection filter: may this connection receive this event type?

Rules

  • Publish only what is durable. Publish after the transaction that wrote the fact has committed: a client that reacts and refetches must see the change. Events are hints, never the source of truth; a lost event costs a late refresh.
  • Event types are 1 to 100 ASCII letters, digits, ., _, : or - (notification, report.ready). ping is reserved for the stream heartbeat. An invalid type or id throws ArgumentException at publish time (a programming error), never a delivery error.
  • Event ids are optional (at most 200 characters, no line break or NUL). A client may use them to de-duplicate; the stream does not replay missed events.
  • Payloads are serialized once, at publish time, with a caller-supplied JsonTypeInfo<T> (no reflection, AOT friendly). Everything downstream carries the same bytes, so an out-of-process backplane moves them as they are.
  • Audiences are a closed set of kinds owned by this package. A transport skips a kind it does not know, so an event never reaches the wrong people.

Usage

[JsonSerializable(typeof(ReportReady))]
internal sealed partial class ReportJsonContext : JsonSerializerContext;

public sealed record ReportReady(Guid ReportId, string Name);

await publisher.PublishAsync(
    "report.ready",
    RealtimeAudience.User(requestedBy),
    new ReportReady(report.Id, report.Name),
    ReportJsonContext.Default.ReportReady,
    eventId: report.Id.ToString("D"),
    ct);

Writing an adapter

  • Backplane (several instances): implement IRealtimeBackplane, move the type, id, audience and payload bytes between instances, and on each instance hand every event to the subscribed transports. Implement IRealtimePresence too if you can tell who is connected anywhere; otherwise every user counts as possibly connected. Register it from your own extension method (services.AddRealtimeRedisBackplane(...)) after AddRealtime.
  • Transport (for example SignalR): implement IRealtimeTransport, register it with TryAddEnumerable as a singleton, map RealtimeUserAudience to your users, and never block in Deliver. Ask every registered IRealtimeEventAuthorizer through CanReceiveAsync off the publisher's thread (queue the event, decide in the connection's loop), from the DI scope of the connection's request (or one your transport keeps per connection), and cache the answer per connection and type. Handle RealtimeEventTypes.Reconnect as a control event: deliver it to every connection of the audience regardless of filters and authorizers, then close those connections. Return true from HasConnection if you do not track users.

Registration, the in-process backplane and the server-sent events stream are in the Hmz.Core.Realtime package.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Hmz.Core.Realtime.Abstractions:

Package Downloads
Hmz.Core.Realtime

Reusable realtime delivery engine for Hmz backends on ASP.NET Core: a best-effort publisher, an in-process backplane and one multiplexed server-sent events stream per client, each replaceable by an adapter package.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 76 11/17/2026