OutWit.Common.Blazor.WitRPC 1.0.0

OutWit.Common.Blazor.WitRPC

Overview

OutWit.Common.Blazor.WitRPC is a Blazor WebAssembly channel factory for WitRPC communication over WebSocket. It bridges the gap between the browser environment and the WitRPC server by handling:

• RSA/AES encryption entirely in the browser via the Web Crypto API
• Automatic reconnection with exponential backoff after disconnects
• Retry policies for transient failures (server errors, timeouts, I/O)
• Authentication integration � reconnects on sign-in, disconnects on sign-out
• One-line DI registration with optional configuration

All of this is exposed through a single IChannelFactory interface that lazily establishes a WebSocket connection and hands back typed service proxies.

Install

Install-Package OutWit.Common.Blazor.WitRPC

or

dotnet add package OutWit.Common.Blazor.WitRPC

Target Framework

net10.0

Getting Started

1. Register Services

In Program.cs, call AddWitRpcChannel() on the service collection. The method registers EncryptorClientWeb, ChannelTokenProvider, and IChannelFactory in a single call:

using OutWit.Common.Blazor.WitRPC;

builder.Services.AddWitRpcChannel(options =>
{
    options.ApiPath = "api";          // WebSocket endpoint path (default: "api")
    options.TimeoutSeconds = 15;      // Connection & request timeout (default: 10)
});

The registered service lifetimes are:

2. Obtain a Service Proxy

Inject IChannelFactory into any component or service and call GetServiceAsync<T>(). The factory lazily connects on first use:

@inject IChannelFactory ChannelFactory

@code {
    private IMyService? _service;

    protected override async Task OnInitializedAsync()
    {
        _service = await ChannelFactory.GetServiceAsync<IMyService>();
    }

    private async Task DoWork()
    {
        var result = await _service!.SomethingAsync();
    }
}

3. Force Reconnection

If you need to re-establish the connection (e.g. after a configuration change or server restart):

await ChannelFactory.ReconnectAsync();

This tears down the existing WitClient, creates a new one with fresh encryption keys, and reconnects.

Connection Lifecycle

ChannelFactory manages the WebSocket connection through a SemaphoreSlim gate to ensure thread safety.

                 GetServiceAsync<T>()
                        ?
                        ?
              ????????????????????
              ? Client == null?  ????? no ???? return proxy
              ????????????????????
                     ? yes
                     ?
              ????????????????
              ?  m_gate.Wait ?     (semaphore � one connect at a time)
              ????????????????
                     ?
              ????????????????????????
              ?  EncryptorClientWeb  ?     generates RSA-2048 via JS
              ?     .InitAsync()     ?     exports JWK ? byte[]
              ????????????????????????
                     ?
              ????????????????????????
              ?  WitClientBuilder    ?
              ?    .Build(options)   ?
              ?  ?? WebSocket(url)   ?     ws:// or wss:// from NavigationManager
              ?  ?? MemoryPack       ?     binary serialization
              ?  ?? Encryptor        ?     EncryptorClientWeb
              ?  ?? TokenProvider    ?     ChannelTokenProvider
              ?  ?? AutoReconnect    ?     unlimited, 1s ? 2min
              ?  ?? RetryPolicy      ?     3�, 500ms ? 10s
              ????????????????????????
                     ?
              ????????????????????????
              ?  client.ConnectAsync ?     with configured timeout
              ????????????????????????
                     ?
              ????????????????????
              ?  m_gate.Release  ?
              ????????????????????

The WebSocket URL is derived automatically from NavigationManager.BaseUri:

https://example.com/  ?  wss://example.com/api
http://localhost:5000/ ?  ws://localhost:5000/api

Authentication Integration

ChannelFactory subscribes to AuthenticationStateProvider.AuthenticationStateChanged during construction:

ChannelTokenProvider obtains access tokens from Blazor's IAccessTokenProvider and makes them available to the WitRPC transport layer:

// Internally:
var result = await TokenProvider.RequestAccessToken(new AccessTokenRequestOptions());
if (result.TryGetToken(out var token))
    return token.Value;

If the token request fails, an empty string is returned and an error is logged.

Resilience

Auto-Reconnect

The built-in auto-reconnect policy fires whenever the underlying WebSocket disconnects unexpectedly:

Retry Policy

Individual RPC calls are retried on transient failures:

Encryption

The library implements end-to-end encryption between the browser and the WitRPC server using a two-phase handshake:

Phase 1 � RSA Key Exchange

1. EncryptorClientWeb.InitAsync() calls cryptoInterop.generateKeys(2048) via JS interop
2. The browser generates an RSA-OAEP key pair using the Web Crypto API
3. Public and private keys are exported in JWK format
4. DualNameJsonConverter re-serializes the keys, converting Base64Url to standard Base64 and mapping JWK field names (n, e, d, p, q, dp, dq, qi) to .NET-compatible property names (mod, exp, d, p, q, dp, dq, iq)
5. The public key is sent to the server, which uses it to encrypt a symmetric AES key

Phase 2 � AES Symmetric Encryption

1. The server encrypts an AES-CBC key + IV with the client's RSA public key
2. EncryptorClientWeb.DecryptRsa() decrypts it in the browser
3. ResetAes() stores the symmetric key and IV
4. All subsequent communication uses Encrypt() / Decrypt() with AES-CBC

RSA Parameters Mapping

JavaScript Interop

The library ships wwwroot/js/cryptoInterop.js which is automatically available as a static web asset. It exposes the following functions on window.cryptoInterop:

Note: The script uses window.crypto.subtle which requires a secure context (HTTPS or localhost).

Configuration Reference

ChannelFactoryOptions provides the following settings:

API Reference

IChannelFactory

EncryptorClientWeb

ChannelTokenProvider

Architecture

???????????????????????????????????????????????????????
?  Blazor WebAssembly Application                     ?
?                                                     ?
?    builder.Services.AddWitRpcChannel(options => ...) ?
?    var svc = await factory.GetServiceAsync<T>();     ?
???????????????????????????????????????????????????????
?  IChannelFactory ? ChannelFactory (sealed)          ?
?    ??? NavigationManager  (base URI ? ws:// / wss://)?
?    ??? AuthenticationStateProvider  (sign-in/out)   ?
?    ??? EncryptorClientWeb  (RSA/AES via JS interop) ?
?    ??? ChannelTokenProvider  (bearer access tokens) ?
?    ??? ChannelFactoryOptions  (ApiPath, Timeout)    ?
?    ??? ILogger<ChannelFactory>  (structured logs)   ?
???????????????????????????????????????????????????????
?  Encryption Layer                                   ?
?    EncryptorClientWeb ??? cryptoInterop.js           ?
?    RSAParametersWeb  (JWK ? .NET field mapping)     ?
?    DualNameJsonConverter  (Base64Url ? Base64)       ?
?    RsaUtils  (Base64Url padding helper)             ?
???????????????????????????????????????????????????????
?  Transport                                          ?
?    OutWit.Communication.Client.WebSocket (NuGet)    ?
?    WitClientBuilder  ?  WitClient                   ?
?    MemoryPack serialization                         ?
?    Auto-reconnect + Retry policies                  ?
???????????????????????????????????????????????????????

Dependencies

Attribution

OutWit.Common.Blazor.WitRPC is part of the OutWit ecosystem.
Copyright � 2020�2026 Dmitry Ratner.

Trademarks

"OutWit" is a trademark of Dmitry Ratner.

License

Licensed under Apache-2.0.