docs consolidation work

2025-12-24 16:26:06 +02:00
parent 2c2bbf1005
commit 8197588e74
20 changed files with 403 additions and 37 deletions
--- a/docs/modules/router/migration-guide.md
+++ b/docs/modules/router/migration-guide.md
@@ -96,6 +96,169 @@ Best for major refactoring or when HTTP compatibility is not needed.
 - More upfront work
 - Requires domain extraction

+### Strategy C: ASP.NET Endpoint Bridge (Recommended)
+
+Best for services that want automatic Router registration from existing ASP.NET endpoints without code changes.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  StellaOps.*.WebService                                         │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  ASP.NET Endpoints (unchanged)                              ││
+│  │  • Minimal APIs: app.MapGet("/api/...", handler)            ││
+│  │  • Controllers: [ApiController] with [HttpGet], etc.        ││
+│  │  • Route groups: app.MapGroup("/api").MapEndpoints()        ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                            │                                    │
+│                            ▼ Auto-discovery                     │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  StellaOps.Microservice.AspNetCore                          ││
+│  │  • Discovers all endpoints from EndpointDataSource          ││
+│  │  • Extracts authorization metadata automatically            ││
+│  │  • Registers with Router via HELLO                          ││
+│  │  • Dispatches Router requests through ASP.NET pipeline      ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                            │                                    │
+│                            ▼ Binary transport                   │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  Router Gateway                                             ││
+│  │  • Routes external HTTP → internal microservice             ││
+│  │  • Aggregates OpenAPI                                       ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Steps:**
+
+1. Add `StellaOps.Microservice.AspNetCore` package reference
+2. Configure bridge in `Program.cs`:
+
+```csharp
+using StellaOps.Microservice.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add authorization (required for claim mapping)
+builder.Services.AddAuthorization();
+
+// Add the ASP.NET Endpoint Bridge
+builder.Services.AddStellaRouterBridge(options =>
+{
+    options.ServiceName = "my-service";
+    options.Version = "1.0.0";
+    options.Region = "us-east-1";
+});
+
+var app = builder.Build();
+
+// Register ASP.NET endpoints as usual
+app.MapGet("/api/health", () => "healthy");
+app.MapGet("/api/items/{id}", (string id) => new { id, name = "Item " + id })
+    .RequireAuthorization("read-items");
+app.MapPost("/api/items", (CreateItemRequest req) => new { id = Guid.NewGuid() })
+    .RequireAuthorization("write-items");
+
+// Activate the bridge (discovers and registers endpoints)
+app.UseStellaRouterBridge();
+
+app.Run();
+```
+
+3. (Optional) Add YAML overrides for security hardening:
+
+```yaml
+# router.yaml
+endpoints:
+  - path: "/api/admin/**"
+    requiringClaims:
+      - type: "Role"
+        value: "admin"
+    timeoutMs: 60000
+```
+
+4. Test via Gateway
+5. Deploy to production
+
+**Pros:**
+- **Zero code changes** to existing endpoints
+- Automatic authorization metadata extraction
+- Full ASP.NET pipeline execution (filters, binding, validation)
+- Deterministic endpoint ordering
+- YAML overrides for security hardening without code changes
+- Supports both minimal APIs and controllers
+
+**Cons:**
+- Slightly more runtime overhead (HttpContext synthesis)
+- Some ASP.NET features not supported (see limitations below)
+
+#### Authorization Mapping
+
+The bridge automatically extracts authorization requirements:
+
+| ASP.NET Source | Router Mapping |
+|----------------|----------------|
+| `[Authorize(Policy = "policy-name")]` | Resolved via `IAuthorizationPolicyProvider` → `RequiringClaims` |
+| `[Authorize(Roles = "admin,user")]` | `ClaimRequirement(Role, admin)`, `ClaimRequirement(Role, user)` |
+| `.RequireAuthorization("policy")` | Resolved via policy provider |
+| `.RequireAuthorization(new AuthorizeAttribute { Roles = "..." })` | Direct role mapping |
+| `[AllowAnonymous]` | Empty `RequiringClaims` (public endpoint) |
+
+#### Authorization Mapping Strategies
+
+Configure how the bridge handles authorization:
+
+```csharp
+builder.Services.AddStellaRouterBridge(options =>
+{
+    options.ServiceName = "my-service";
+    options.Version = "1.0.0";
+    options.Region = "us-east-1";
+
+    // Strategy options:
+    // - YamlOnly: YAML claims replace code claims entirely
+    // - AspNetMetadataOnly: Code claims only, ignore YAML (default)
+    // - Hybrid: Merge code + YAML claims by type
+    options.AuthorizationMappingStrategy = AuthorizationMappingStrategy.Hybrid;
+
+    // Behavior when endpoint has no authorization:
+    // - RequireExplicit: Fail validation (secure default)
+    // - AllowAuthenticated: Require authentication but no specific claims
+    // - WarnAndAllow: Log warning, allow request (dev only)
+    options.MissingAuthorizationBehavior = MissingAuthorizationBehavior.RequireExplicit;
+});
+```
+
+#### Route Filtering
+
+Control which endpoints are bridged:
+
+```csharp
+builder.Services.AddStellaRouterBridge(options =>
+{
+    options.ServiceName = "my-service";
+    options.Version = "1.0.0";
+    options.Region = "us-east-1";
+
+    // Include only /api/* endpoints
+    options.IncludePathPatterns = ["/api/**"];
+
+    // Exclude internal endpoints
+    options.ExcludePathPatterns = ["/internal/**", "/metrics", "/health/**"];
+});
+```
+
+#### Limitations
+
+The ASP.NET Endpoint Bridge does **not** support:
+
+| Feature | Alternative |
+|---------|-------------|
+| SignalR/WebSocket | Use direct HTTP for real-time features |
+| gRPC endpoints | Use separate gRPC channel |
+| Streaming request bodies | Use `IRawStellaEndpoint` for streaming |
+| Custom route constraints (`{id:guid}`) | Constraints execute at dispatch, but not in discovery |
+| Header/query-based API versioning | Use path-based versioning (`/api/v1/...`) |
+
 ## Controller to Handler Mapping

 ### Before (ASP.NET Controller)