Documentation

Session Contracts

Read time 2 minutes Package: Nalix.Abstractions
On this page

Namespace: Nalix.Abstractions.Networking.Sessions
Assembly: Nalix.Abstractions

Nalix.Abstractions.Networking.Sessions defines the contracts for capturing, storing, and atomically consuming session state to support zero-RTT session resumption (SessionResume).

Source Mapping

  • src/Nalix.Abstractions/Networking/Sessions/ISessionService.cs
  • src/Nalix.Abstractions/Networking/Sessions/ISessionFactory.cs
  • src/Nalix.Abstractions/Networking/Sessions/ISessionStore.cs
  • src/Nalix.Abstractions/Networking/Sessions/ISessionPersistencePolicy.cs
  • src/Nalix.Abstractions/Networking/Sessions/SessionEntry.cs
  • src/Nalix.Abstractions/Networking/Sessions/SessionSnapshot.cs
  • src/Nalix.Abstractions/Networking/Sessions/SessionScope.cs

Public Members at a Glance

TypeKindPublic Members
ISessionServiceinterface : IDisposableValueTask SaveSessionAsync(IConnection, CancellationToken), ValueTask<SessionScope> ConsumeAsync(ulong sessionToken, Func<SessionEntry, bool>? predicate = null, CancellationToken ct = default)
ISessionStoreinterfaceValueTask StoreAsync(SessionEntry, CancellationToken), ValueTask<SessionScope> ConsumeAsync(ulong sessionToken, Func<SessionEntry, bool>? predicate = null, CancellationToken ct = default)
ISessionFactoryinterfaceSessionEntry CreateSession(IConnection connection)
ISessionPersistencePolicyinterfacebool ShouldPersist(IConnection connection)
SessionScopereadonly struct : IDisposableSessionEntry? Value { get; }, bool IsValid { get; }, void Dispose(), implicit operator SessionEntry?(SessionScope)
SessionEntryclassSessionSnapshot Snapshot, ulong ConnectionId, void Return()
SessionSnapshotclassulong SessionToken, long CreatedAtUnixMilliseconds, long ExpiresAtUnixMilliseconds, Bytes32 Secret, CipherSuiteType Algorithm, PermissionLevel Level, IObjectMap<AttributeKey, object>? Attributes, void ClearSecret(), void Return()

ISessionService & ISessionStore

Both ISessionService.ConsumeAsync and ISessionStore.ConsumeAsync perform an atomic retrieve-and-remove operation and return a SessionScope:

using SessionScope scope = await sessionService.ConsumeAsync(
    sessionToken,
    predicate: entry => entry.Snapshot.ExpiresAtUnixMilliseconds > nowMs,
    cancellationToken: ct);

if (scope.IsValid)
{
    SessionEntry entry = scope.Value!;
    // Restore Secret, Algorithm, Level, and sequence counters onto the new connection
}

ISessionFactory & ISessionPersistencePolicy

  • ISessionFactory.CreateSession(IConnection): Creates a SessionEntry and populates its SessionSnapshot with the connection’s ConnectionId (SessionToken), 32-byte Secret (Bytes32), Algorithm, Level, and Attributes (including TCP/UDP sequence numbers).
  • ISessionPersistencePolicy.ShouldPersist(IConnection): Evaluates whether a connection’s session should be saved (default DefaultSessionPersistencePolicy verifies that a cryptographic handshake was completed and Secret is non-zero).