# 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`:

```xml
<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:

```csharp
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:

```csharp
using StellaOps.Router.AspNet;
```

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

```csharp
// 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:

```csharp
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:

```yaml
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:

```yaml
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:

```yaml
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:

```csharp
app.TryUseStellaRouter(resolvedOptions.Router);
```

### 4. Refresh Endpoint Cache

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

```csharp
app.TryRefreshStellaRouterEndpoints(resolvedOptions.Router);
```

## Configuration Example (YAML)

```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