Skip to content
Shiny.NET

Remoting

Other processes and devices call your actors through the same IActorSystem. The generator has already written a serializable contract and a remote proxy for every actor interface, so there’s nothing extra to declare.

Terminal window
dotnet add package Shiny.Actors.HttpServer

The server is Shiny.Net.HttpServer, so it runs on a phone too.

builder.Services.AddShinyActors(actors => actors.ServeOverHttp(
expose => expose
.Expose<ICounter>() // nothing is reachable unless exposed
.ExposeStream<OrderPlaced>(), // publish + server-sent events
http =>
{
http.AddAuthentication().AddApiKey(o => o.AddKey(key, "client"));
http.AddAuthorization(_ => { });
http.Configure((HttpServer s) => { s.UseAuthentication(); s.UseAuthorization(); });
},
authorizationPolicies: [] // every actor route requires authorization
));

Already building the server yourself? server.MapActors(expose => ...).RequireAuthorization() does the mapping alone.

Route policies decide who reaches the actor routes at all. Past that, each exposure takes an authorize callback that decides each call by user, actor id or method, and each stream publish or subscribe by user and key. A refusal answers 401 to an anonymous caller and 403 to an authenticated one:

expose
.Expose<IWallet>(call => call.ActorId == call.User.Identity?.Name) // your own wallet only
.Expose<IAdmin>(call => call.User.IsInRole("admin") || call.Method.Name == nameof(IAdmin.Status))
.ExposeStream<ChatMessage>(s => s.Access == ActorStreamAccess.Subscribe || s.User.Identity?.IsAuthenticated == true)
.MapRequestContext("user", user => user.Identity?.IsAuthenticated == true ? user.Identity.Name : null);
Option Default
Prefix /actors Where the routes live. / or empty serves them from the root
StreamHeartbeat 15 seconds An SSE comment on idle stream subscriptions, so proxies don’t drop them. null turns it off
IncludeExceptionDetails off Sends the exception type and message to callers. Development only

The client is in the core package and uses a plain HttpClient:

using var actors = new RemoteActorSystem(new Uri("http://192.168.1.20:8080/actors/")) { CallTimeout = TimeSpan.FromSeconds(10) };
await actors.Get<ICounter>("bob").Increment();
await foreach (var order in actors.GetStream<OrderPlaced>("store-1").ReadAllAsync(ct)) { ... }
  • HttpClient. new RemoteActorSystem(uri) creates one and disposes it with the system. Pass your own (new RemoteActorSystem(httpClient)) to share it; it’s then yours to dispose.
  • CallTimeout fails a call that takes longer with TimeoutException, apart from HttpClient.Timeout (which also surfaces as TimeoutException). Streams aren’t affected.
  • Equality. Two remote proxies for the same system, actor and id are equal, like local ones.
Wire POST {prefix}/call/{actor}/{id}/{method}, with a JSON array of arguments in and a JSON result out. Streams: POST/GET (SSE) {prefix}/streams/{type}/{key}.
JSON Every JsonSerializerContext in a project with actors is registered automatically, and primitives are built in. A type crossing the wire without metadata fails at MapActors, not on the first call.
Errors RemoteActorException.StatusCode: 400 bad or missing arguments (including null for a non-nullable parameter), 401/403 auth (and an UnauthorizedAccessException the actor or a filter throws), 404 not exposed or not implemented, 409 deadlock, 499 the caller went away, 500 the actor threw, 502 a remote call the actor made failed, 504 timeout. Exception details stay hidden unless IncludeExceptionDetails is on.
Deadlocks The caller’s call chain travels in x-actor-chain, so a cycle across processes (A -> remote B -> A) fails with 409 instead of hanging.
Ids Any string. Ids that aren’t plain are sent as ~base64url, because %2F and .. don’t survive every proxy.
Remote streams ReadAllAsync and Subscribe reconnect with backoff (1s, up to 30s). Durable streams resume from the last sequence seen. Others miss what was published meanwhile.
Tracing & context traceparent and x-actor-context headers carry the caller’s trace and ActorRequestContext.

IActorTransport is the seam for a transport other than HTTP. ActorDispatcher does the server side and works with bytes only.

Terminal window
dotnet add package Shiny.Actors.Discovery

Shiny.Actors.Discovery finds actor servers on the local network over mDNS/Bonjour, so nobody has to type an address:

builder.Services.AddShinyActors(x => x.UseDiscovery());
// server side: advertised while the actor server is running, withdrawn when it stops
builder.Services.AddShinyActors(x => x.UseDiscovery().AdvertiseOverMdns(DeviceInfo.Current.Name));
// ...or by hand: await using var published = await mdns.PublishActorsAsync(DeviceInfo.Current.Name, port);
// client side
await foreach (var peer in mdns.BrowseActorPeersAsync(ct))
if (peer.IsAvailable) actors = peer.Connect(http => http.DefaultRequestHeaders.Add("X-Api-Key", code));

Connect() returns a RemoteActorSystem that owns its HttpClient, so dispose it when you’re done with the peer. Connect(httpClient) uses one of yours instead. Inject ActorAdvertisement to show the advertised name, or react to Changed.

  • The server must listen on the LAN (Address = IPAddress.Any). Shiny.Net.HttpServer binds to loopback by default.
  • On Apple platforms, add _shinyactors._tcp to NSBonjourServices, plus an NSLocalNetworkUsageDescription.