git.stella-ops.org/docs/modules/router/webservice-integration-guide.md

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:

Service	Path	Status
Scanner.WebService	src/Scanner/StellaOps.Scanner.WebService	✅ Complete
Concelier.WebService	src/Concelier/StellaOps.Concelier.WebService	✅ Complete
Excititor.WebService	src/Excititor/StellaOps.Excititor.WebService	✅ Complete
Gateway.WebService	src/Router/StellaOps.Gateway.WebService (moved from src/Gateway/, Sprint 200)	✅ Complete
VexHub.WebService	src/VexHub/StellaOps.VexHub.WebService	✅ Complete
Attestor.WebService	src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService	✅ Complete
EvidenceLocker.WebService	src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.WebService	✅ Complete
Findings.Ledger.WebService	src/Findings/StellaOps.Findings.Ledger.WebService	✅ Complete
AdvisoryAI.WebService	src/AdvisoryAI/StellaOps.AdvisoryAI.WebService	✅ Complete
IssuerDirectory.WebService	src/IssuerDirectory/StellaOps.IssuerDirectory/StellaOps.IssuerDirectory.WebService	✅ Complete
Notifier.WebService	src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService	✅ Complete
Notify.WebService	src/Notify/StellaOps.Notify.WebService	✅ Complete
PacksRegistry.WebService	src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService	✅ Complete
RiskEngine.WebService	src/Findings/StellaOps.RiskEngine.WebService	✅ Complete
Signer.WebService	src/Signer/StellaOps.Signer/StellaOps.Signer.WebService	✅ Complete
TaskRunner.WebService	src/TaskRunner/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService	✅ Complete
TimelineIndexer.WebService	src/Timeline/StellaOps.TimelineIndexer.WebService	✅ Complete
Orchestrator.WebService	src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService	✅ Complete
Scheduler.WebService	src/Scheduler/StellaOps.Scheduler.WebService	✅ Complete
ExportCenter.WebService	src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.WebService	✅ Complete

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