209 lines
7.7 KiB
Markdown
209 lines
7.7 KiB
Markdown
# 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
|