Stella Router ASP.NET WebService Integration Guide

This guide explains how to integrate any ASP.NET Core WebService with the Stella Router for automatic endpoint discovery and dispatch.

Prerequisites

Add a project reference to StellaOps.Router.AspNet:

<ProjectReference Include="../../__Libraries/StellaOps.Router.AspNet/StellaOps.Router.AspNet.csproj" />

Integration Steps

1. Add Router Options to Service Options

In your service’s options class (e.g., MyServiceOptions.cs), add:

using StellaOps.Router.AspNet;

public class MyServiceOptions
{
    // ... existing options ...

    /// <summary>
    /// Stella Router integration configuration (disabled by default).
    /// </summary>
    public StellaRouterOptionsBase? Router { get; set; }
}

2. Register Services in Program.cs

Add the using directive:

using StellaOps.Router.AspNet;

After service registration (e.g., after AddControllers()), add:

// Stella Router integration
builder.Services.TryAddStellaRouter(
    serviceName: "my-service-name",
    version: typeof(Program).Assembly.GetName().Version?.ToString() ?? "1.0.0",
    routerOptions: options.Router);

Optional: generic microservice transport registration

For services that should auto-register transport clients from configuration, use:

builder.Services.AddRouterMicroservice(
    builder.Configuration,
    serviceName: "my-service-name",
    version: typeof(Program).Assembly.GetName().Version?.ToString() ?? "1.0.0",
    routerOptionsSection: "MyService:Router");

AddRouterMicroservice(...) keeps TryAddStellaRouter(...) behavior and registers transport clients through RouterTransportPluginLoader based on configured gateway transport types (InMemory, Tcp, Certificate/tls, Udp, RabbitMq, Messaging).
The StellaOps.Router.AspNet library does not hard-reference transport assemblies; transports are activated from plugin DLLs and environment/config values.

For Valkey messaging mode, configure:

myservice:
  router:
    enabled: true
    region: "local"
    transportPlugins:
      directory: "plugins/router/transports"
      searchPattern: "StellaOps.Router.Transport.*.dll"
    gateways:
      - host: "router.stella-ops.local"
        port: 9100
        transportType: "Messaging"
    messaging:
      transport: "valkey"
      pluginDirectory: "plugins/messaging"
      searchPattern: "StellaOps.Messaging.Transport.*.dll"
      requestQueueTemplate: "router:requests:{service}"
      responseQueueName: "router:responses"
      consumerGroup: "myservice"
      requestTimeout: "30s"
      leaseDuration: "5m"
      batchSize: 10
      heartbeatInterval: "10s"
      valkey:
        connectionString: "cache.stella-ops.local:6379"

2.2 Gateway trust mode and identity envelope verification

Service-side Router bridge can enforce gateway-issued identity semantics:

myservice:
  router:
    authorizationTrustMode: "GatewayEnforced" # ServiceEnforced | Hybrid | GatewayEnforced
    identityEnvelopeSigningKey: "${ROUTER_IDENTITY_SIGNING_KEY}"
    identityEnvelopeClockSkewSeconds: 30

• ServiceEnforced: service-local checks remain primary.
• Hybrid: prefer signed envelope; fallback to legacy headers.
• GatewayEnforced: fail closed when envelope is missing/invalid.

2.3 Timeout precedence

Gateway dispatch timeout is now resolved with explicit precedence:

1. Endpoint timeout (including endpoint override/service default published by service).
2. Route default timeout (optional per gateway route via defaultTimeout).
3. Gateway routing default timeout (Gateway:Routing:DefaultTimeout).
4. Global gateway cap (Gateway:Routing:GlobalTimeoutCap).

Route-level timeout example:

gateway:
  routing:
    defaultTimeout: "30s"
    globalTimeoutCap: "120s"
  routes:
    - type: Microservice
      path: "/api/v1/timeline"
      translatesTo: "http://timelineindexer.stella-ops.local/api/v1/timeline"
      defaultTimeout: "15s"

2.1 Gateway SPA deep-link handling with microservice routes

When gateway route prefixes overlap with UI routes (for example /policy), browser navigations must still resolve to the SPA shell.
Gateway RouteDispatchMiddleware now serves the configured static SPA fallback route for browser document requests on both ReverseProxy and Microservice route types. API prefixes (/api, /v1) are explicitly excluded from this fallback and continue to dispatch to backend services.

3. Enable Middleware

After UseAuthorization(), add:

app.TryUseStellaRouter(resolvedOptions.Router);

4. Refresh Endpoint Cache

After all endpoints are mapped (before app.RunAsync()), add:

app.TryRefreshStellaRouterEndpoints(resolvedOptions.Router);

Configuration Example (YAML)

myservice:
  router:
    enabled: true
    region: "us-east-1"
    defaultTimeoutSeconds: 30
    heartbeatIntervalSeconds: 10
    gateways:
      - host: "router.stellaops.local"
        port: 9100
        transportType: "Tcp"
        useTls: true
        certificatePath: "/etc/certs/router.pem"

WebServices Integration Status

All WebServices have been updated with Router integration:

Files Created

The Router.AspNet library includes the following files:

• StellaOps.Router.AspNet.csproj - Project file
• StellaRouterOptions.cs - Unified router options
• StellaRouterExtensions.cs - DI extensions (AddStellaRouter, UseStellaRouter)
• CompositeRequestDispatcher.cs - Routes requests to ASP.NET or Stella endpoints
• StellaRouterOptionsBase.cs - Base options class for embedding in service options
• StellaRouterIntegrationHelper.cs - Helper methods for conditional integration