Add unit tests for Router configuration and transport layers

- Implemented tests for RouterConfig, RoutingOptions, StaticInstanceConfig, and RouterConfigOptions to ensure default values are set correctly.
- Added tests for RouterConfigProvider to validate configurations and ensure defaults are returned when no file is specified.
- Created tests for ConfigValidationResult to check success and error scenarios.
- Developed tests for ServiceCollectionExtensions to verify service registration for RouterConfig.
- Introduced UdpTransportTests to validate serialization, connection, request-response, and error handling in UDP transport.
- Added scripts for signing authority gaps and hashing DevPortal SDK snippets.

examples/router/src/Examples.Billing.Microservice/Endpoints/CreateInvoiceEndpoint.cs

@@ -0,0 +1,70 @@
+using Microsoft.Extensions.Logging;
+using StellaOps.Microservice;
+
+namespace Examples.Billing.Microservice.Endpoints;
+
+/// <summary>
+/// Request model for creating an invoice.
+/// </summary>
+public sealed record CreateInvoiceRequest
+{
+    public required string CustomerId { get; init; }
+    public required decimal Amount { get; init; }
+    public string? Description { get; init; }
+    public List<LineItem> LineItems { get; init; } = [];
+}
+
+/// <summary>
+/// Line item for an invoice.
+/// </summary>
+public sealed record LineItem
+{
+    public required string Description { get; init; }
+    public required decimal Amount { get; init; }
+    public int Quantity { get; init; } = 1;
+}
+
+/// <summary>
+/// Response model after creating an invoice.
+/// </summary>
+public sealed record CreateInvoiceResponse
+{
+    public required string InvoiceId { get; init; }
+    public required DateTime CreatedAt { get; init; }
+    public required string Status { get; init; }
+}
+
+/// <summary>
+/// Endpoint for creating a new invoice.
+/// Demonstrates a typed endpoint with JSON request/response.
+/// </summary>
+[StellaEndpoint("POST", "/invoices", TimeoutSeconds = 30)]
+public sealed class CreateInvoiceEndpoint : IStellaEndpoint<CreateInvoiceRequest, CreateInvoiceResponse>
+{
+    private readonly ILogger<CreateInvoiceEndpoint> _logger;
+
+    public CreateInvoiceEndpoint(ILogger<CreateInvoiceEndpoint> logger)
+    {
+        _logger = logger;
+    }
+
+    public Task<CreateInvoiceResponse> HandleAsync(
+        CreateInvoiceRequest request,
+        CancellationToken cancellationToken)
+    {
+        _logger.LogInformation(
+            "Creating invoice for customer {CustomerId} with amount {Amount}",
+            request.CustomerId,
+            request.Amount);
+
+        // Simulate invoice creation
+        var invoiceId = $"INV-{Guid.NewGuid():N}".ToUpperInvariant()[..16];
+
+        return Task.FromResult(new CreateInvoiceResponse
+        {
+            InvoiceId = invoiceId,
+            CreatedAt = DateTime.UtcNow,
+            Status = "draft"
+        });
+    }
+}

examples/router/src/Examples.Billing.Microservice/Endpoints/GetInvoiceEndpoint.cs

@@ -0,0 +1,58 @@
+using Microsoft.Extensions.Logging;
+using StellaOps.Microservice;
+
+namespace Examples.Billing.Microservice.Endpoints;
+
+/// <summary>
+/// Request model for getting an invoice.
+/// </summary>
+public sealed record GetInvoiceRequest
+{
+    public required string Id { get; init; }
+}
+
+/// <summary>
+/// Response model for an invoice.
+/// </summary>
+public sealed record GetInvoiceResponse
+{
+    public required string InvoiceId { get; init; }
+    public required string CustomerId { get; init; }
+    public required decimal Amount { get; init; }
+    public required string Status { get; init; }
+    public required DateTime CreatedAt { get; init; }
+    public DateTime? PaidAt { get; init; }
+}
+
+/// <summary>
+/// Endpoint for retrieving an invoice by ID.
+/// Demonstrates a GET endpoint with path parameters.
+/// </summary>
+[StellaEndpoint("GET", "/invoices/{id}", TimeoutSeconds = 10, RequiredClaims = ["invoices:read"])]
+public sealed class GetInvoiceEndpoint : IStellaEndpoint<GetInvoiceRequest, GetInvoiceResponse>
+{
+    private readonly ILogger<GetInvoiceEndpoint> _logger;
+
+    public GetInvoiceEndpoint(ILogger<GetInvoiceEndpoint> logger)
+    {
+        _logger = logger;
+    }
+
+    public Task<GetInvoiceResponse> HandleAsync(
+        GetInvoiceRequest request,
+        CancellationToken cancellationToken)
+    {
+        _logger.LogInformation("Fetching invoice {InvoiceId}", request.Id);
+
+        // Simulate invoice lookup
+        return Task.FromResult(new GetInvoiceResponse
+        {
+            InvoiceId = request.Id,
+            CustomerId = "CUST-001",
+            Amount = 199.99m,
+            Status = "paid",
+            CreatedAt = DateTime.UtcNow.AddDays(-7),
+            PaidAt = DateTime.UtcNow.AddDays(-1)
+        });
+    }
+}

examples/router/src/Examples.Billing.Microservice/Endpoints/UploadAttachmentEndpoint.cs

@@ -0,0 +1,60 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using StellaOps.Microservice;
+
+namespace Examples.Billing.Microservice.Endpoints;
+
+/// <summary>
+/// Endpoint for uploading attachments to an invoice.
+/// Demonstrates streaming upload using IRawStellaEndpoint.
+/// </summary>
+[StellaEndpoint("POST", "/invoices/{id}/attachments", SupportsStreaming = true, TimeoutSeconds = 300)]
+public sealed class UploadAttachmentEndpoint : IRawStellaEndpoint
+{
+    private readonly ILogger<UploadAttachmentEndpoint> _logger;
+
+    public UploadAttachmentEndpoint(ILogger<UploadAttachmentEndpoint> logger)
+    {
+        _logger = logger;
+    }
+
+    public async Task<RawResponse> HandleAsync(
+        RawRequestContext context,
+        CancellationToken cancellationToken)
+    {
+        var invoiceId = context.PathParameters.GetValueOrDefault("id") ?? "unknown";
+
+        var contentType = context.Headers["Content-Type"] ?? "application/octet-stream";
+        _logger.LogInformation(
+            "Uploading attachment for invoice {InvoiceId}, Content-Type: {ContentType}",
+            invoiceId,
+            contentType);
+
+        // Read the streamed body
+        long totalBytes = 0;
+        var buffer = new byte[8192];
+        int bytesRead;
+
+        while ((bytesRead = await context.Body.ReadAsync(buffer, cancellationToken)) > 0)
+        {
+            totalBytes += bytesRead;
+            // In a real implementation, you would write to storage here
+        }
+
+        _logger.LogInformation(
+            "Received {TotalBytes} bytes for invoice {InvoiceId}",
+            totalBytes,
+            invoiceId);
+
+        // Return success response
+        var response = new
+        {
+            invoiceId,
+            attachmentId = $"ATT-{Guid.NewGuid():N}"[..16].ToUpperInvariant(),
+            size = totalBytes,
+            uploadedAt = DateTime.UtcNow
+        };
+
+        return RawResponse.Ok(JsonSerializer.Serialize(response));
+    }
+}

examples/router/src/Examples.Billing.Microservice/Examples.Billing.Microservice.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Microservice\StellaOps.Microservice.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Common\StellaOps.Router.Common.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Transport.InMemory\StellaOps.Router.Transport.InMemory.csproj" />
+    <!-- Reference the source generator -->
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Microservice.SourceGen\StellaOps.Microservice.SourceGen.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="microservice.yaml" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+</Project>

examples/router/src/Examples.Billing.Microservice/Program.cs

@@ -0,0 +1,40 @@
+using Examples.Billing.Microservice.Endpoints;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using StellaOps.Microservice;
+using StellaOps.Router.Common.Enums;
+using StellaOps.Router.Transport.InMemory;
+
+var builder = Host.CreateApplicationBuilder(args);
+
+// Configure the Stella microservice
+builder.Services.AddStellaMicroservice(options =>
+{
+    options.ServiceName = "billing";
+    options.Version = "1.0.0";
+    options.Region = "demo";
+    options.InstanceId = $"billing-{Environment.MachineName}";
+    options.ConfigFilePath = "microservice.yaml";
+    options.Routers =
+    [
+        new RouterEndpointConfig
+        {
+            Host = "localhost",
+            Port = 5100,
+            TransportType = TransportType.InMemory
+        }
+    ];
+});
+
+// Register endpoint handlers
+builder.Services.AddScoped<CreateInvoiceEndpoint>();
+builder.Services.AddScoped<GetInvoiceEndpoint>();
+builder.Services.AddScoped<UploadAttachmentEndpoint>();
+
+// Add in-memory transport
+builder.Services.AddInMemoryTransport();
+
+var host = builder.Build();
+
+Console.WriteLine("Billing microservice starting...");
+await host.RunAsync();

examples/router/src/Examples.Billing.Microservice/microservice.yaml

@@ -0,0 +1,21 @@
+# Microservice YAML Configuration for Billing Service
+# Overrides code-defined endpoint settings
+
+endpoints:
+  # Override timeout for invoice creation
+  - method: POST
+    path: /invoices
+    timeout: 45s  # Allow more time for complex invoice creation
+
+  # Override streaming settings for file upload
+  - method: POST
+    path: /invoices/{id}/attachments
+    timeout: 5m   # Allow large file uploads
+    streaming: true
+
+  # Add claim requirements for getting invoices
+  - method: GET
+    path: /invoices/{id}
+    requiringClaims:
+      - type: "scope"
+        value: "invoices:read"

examples/router/src/Examples.Gateway/Examples.Gateway.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Gateway\StellaOps.Gateway.WebService\StellaOps.Gateway.WebService.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Transport.InMemory\StellaOps.Router.Transport.InMemory.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Config\StellaOps.Router.Config.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="router.yaml" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+</Project>

examples/router/src/Examples.Gateway/Program.cs

@@ -0,0 +1,53 @@
+using StellaOps.Gateway.WebService;
+using StellaOps.Gateway.WebService.Authorization;
+using StellaOps.Gateway.WebService.Middleware;
+using StellaOps.Router.Config;
+using StellaOps.Router.Transport.InMemory;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Router configuration from YAML
+builder.Services.AddRouterConfig(options =>
+{
+    options.ConfigPath = "router.yaml";
+    options.EnableHotReload = true;
+});
+
+// Gateway routing services
+builder.Services.AddGatewayRouting(builder.Configuration);
+
+// In-memory transport for demo (can switch to TCP/TLS for production)
+builder.Services.AddInMemoryTransport();
+
+// Authority integration (no-op for demo)
+builder.Services.AddNoOpAuthorityIntegration();
+
+var app = builder.Build();
+
+// Middleware pipeline
+app.UseForwardedHeaders();
+app.UseMiddleware<PayloadLimitsMiddleware>();
+app.UseAuthentication();
+app.UseMiddleware<EndpointResolutionMiddleware>();
+app.UseClaimsAuthorization();
+app.UseMiddleware<RoutingDecisionMiddleware>();
+
+// Simple health endpoint
+app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
+
+// Catch-all for routed requests
+app.MapFallback(async context =>
+{
+    // The RoutingDecisionMiddleware would have dispatched the request
+    // If we reach here, no route was found
+    context.Response.StatusCode = 404;
+    await context.Response.WriteAsJsonAsync(new { error = "Not Found", message = "No matching endpoint" });
+});
+
+app.Run();
+
+// Partial class for WebApplicationFactory integration testing
+namespace Examples.Gateway
+{
+    public partial class Program { }
+}

examples/router/src/Examples.Gateway/appsettings.json

@@ -0,0 +1,13 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*",
+  "GatewayNode": {
+    "Region": "demo",
+    "NodeId": "gw-demo-01"
+  }
+}

examples/router/src/Examples.Gateway/router.yaml

@@ -0,0 +1,50 @@
+# Router Configuration for Example Gateway
+# This file configures how the gateway routes requests to microservices
+
+gateway:
+  nodeId: "gw-demo-01"
+  region: "demo"
+  listenPort: 8080
+
+  # Payload limits
+  payloadLimits:
+    maxRequestBodyBytes: 10485760  # 10 MB
+    maxStreamingChunkBytes: 65536   # 64 KB
+
+  # Health monitoring
+  healthMonitoring:
+    staleThreshold: "00:00:30"
+    checkInterval: "00:00:05"
+
+# Transport configuration
+transports:
+  # In-memory transport (for demo)
+  inMemory:
+    enabled: true
+
+  # TCP transport (production)
+  # tcp:
+  #   enabled: true
+  #   port: 5100
+  #   backlog: 100
+
+  # TLS transport (production with encryption)
+  # tls:
+  #   enabled: true
+  #   port: 5101
+  #   certificatePath: "certs/gateway.pfx"
+  #   certificatePassword: "demo"
+
+# Routing configuration
+routing:
+  # Default routing algorithm
+  algorithm: "round-robin"
+
+  # Region affinity (prefer local microservices)
+  regionAffinity: true
+  affinityWeight: 0.8
+
+# Logging
+logging:
+  level: "Information"
+  requestLogging: true

examples/router/src/Examples.Inventory.Microservice/Endpoints/GetItemEndpoint.cs

@@ -0,0 +1,64 @@
+using Microsoft.Extensions.Logging;
+using StellaOps.Microservice;
+
+namespace Examples.Inventory.Microservice.Endpoints;
+
+/// <summary>
+/// Request model for getting a single inventory item.
+/// </summary>
+public sealed record GetItemRequest
+{
+    public required string Sku { get; init; }
+}
+
+/// <summary>
+/// Response model for a single inventory item with details.
+/// </summary>
+public sealed record GetItemResponse
+{
+    public required string Sku { get; init; }
+    public required string Name { get; init; }
+    public required string Description { get; init; }
+    public required string Category { get; init; }
+    public required int QuantityOnHand { get; init; }
+    public required int ReorderPoint { get; init; }
+    public required decimal UnitPrice { get; init; }
+    public required string Location { get; init; }
+    public required DateTime LastUpdated { get; init; }
+}
+
+/// <summary>
+/// Endpoint for getting a single inventory item by SKU.
+/// Demonstrates path parameter extraction.
+/// </summary>
+[StellaEndpoint("GET", "/items/{sku}", TimeoutSeconds = 10)]
+public sealed class GetItemEndpoint : IStellaEndpoint<GetItemRequest, GetItemResponse>
+{
+    private readonly ILogger<GetItemEndpoint> _logger;
+
+    public GetItemEndpoint(ILogger<GetItemEndpoint> logger)
+    {
+        _logger = logger;
+    }
+
+    public Task<GetItemResponse> HandleAsync(
+        GetItemRequest request,
+        CancellationToken cancellationToken)
+    {
+        _logger.LogInformation("Fetching inventory item {Sku}", request.Sku);
+
+        // Simulate item lookup
+        return Task.FromResult(new GetItemResponse
+        {
+            Sku = request.Sku,
+            Name = "Widget A",
+            Description = "A high-quality widget for general purpose use",
+            Category = "widgets",
+            QuantityOnHand = 100,
+            ReorderPoint = 25,
+            UnitPrice = 9.99m,
+            Location = "Warehouse A, Aisle 3, Shelf 2",
+            LastUpdated = DateTime.UtcNow.AddHours(-2)
+        });
+    }
+}

examples/router/src/Examples.Inventory.Microservice/Endpoints/ListItemsEndpoint.cs

@@ -0,0 +1,107 @@
+using Microsoft.Extensions.Logging;
+using StellaOps.Microservice;
+
+namespace Examples.Inventory.Microservice.Endpoints;
+
+/// <summary>
+/// Request model for listing inventory items.
+/// </summary>
+public sealed record ListItemsRequest
+{
+    public int Page { get; init; } = 1;
+    public int PageSize { get; init; } = 20;
+    public string? Category { get; init; }
+}
+
+/// <summary>
+/// Response model for listing inventory items.
+/// </summary>
+public sealed record ListItemsResponse
+{
+    public required List<InventoryItem> Items { get; init; }
+    public required int TotalCount { get; init; }
+    public required int Page { get; init; }
+    public required int PageSize { get; init; }
+}
+
+/// <summary>
+/// Inventory item model.
+/// </summary>
+public sealed record InventoryItem
+{
+    public required string Sku { get; init; }
+    public required string Name { get; init; }
+    public required string Category { get; init; }
+    public required int QuantityOnHand { get; init; }
+    public required decimal UnitPrice { get; init; }
+}
+
+/// <summary>
+/// Endpoint for listing inventory items.
+/// Demonstrates pagination and filtering.
+/// </summary>
+[StellaEndpoint("GET", "/items", TimeoutSeconds = 15)]
+public sealed class ListItemsEndpoint : IStellaEndpoint<ListItemsRequest, ListItemsResponse>
+{
+    private readonly ILogger<ListItemsEndpoint> _logger;
+
+    public ListItemsEndpoint(ILogger<ListItemsEndpoint> logger)
+    {
+        _logger = logger;
+    }
+
+    public Task<ListItemsResponse> HandleAsync(
+        ListItemsRequest request,
+        CancellationToken cancellationToken)
+    {
+        _logger.LogInformation(
+            "Listing inventory items - Page: {Page}, PageSize: {PageSize}, Category: {Category}",
+            request.Page,
+            request.PageSize,
+            request.Category ?? "(all)");
+
+        // Simulate item list
+        var items = new List<InventoryItem>
+        {
+            new()
+            {
+                Sku = "SKU-001",
+                Name = "Widget A",
+                Category = "widgets",
+                QuantityOnHand = 100,
+                UnitPrice = 9.99m
+            },
+            new()
+            {
+                Sku = "SKU-002",
+                Name = "Widget B",
+                Category = "widgets",
+                QuantityOnHand = 50,
+                UnitPrice = 14.99m
+            },
+            new()
+            {
+                Sku = "SKU-003",
+                Name = "Gadget X",
+                Category = "gadgets",
+                QuantityOnHand = 25,
+                UnitPrice = 29.99m
+            }
+        };
+
+        // Filter by category if specified
+        if (!string.IsNullOrWhiteSpace(request.Category))
+        {
+            items = items.Where(i =>
+                i.Category.Equals(request.Category, StringComparison.OrdinalIgnoreCase)).ToList();
+        }
+
+        return Task.FromResult(new ListItemsResponse
+        {
+            Items = items,
+            TotalCount = items.Count,
+            Page = request.Page,
+            PageSize = request.PageSize
+        });
+    }
+}

examples/router/src/Examples.Inventory.Microservice/Examples.Inventory.Microservice.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Microservice\StellaOps.Microservice.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Common\StellaOps.Router.Common.csproj" />
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Router.Transport.InMemory\StellaOps.Router.Transport.InMemory.csproj" />
+    <!-- Reference the source generator -->
+    <ProjectReference Include="..\..\..\..\src\__Libraries\StellaOps.Microservice.SourceGen\StellaOps.Microservice.SourceGen.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
+  </ItemGroup>
+</Project>

examples/router/src/Examples.Inventory.Microservice/Program.cs

@@ -0,0 +1,38 @@
+using Examples.Inventory.Microservice.Endpoints;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using StellaOps.Microservice;
+using StellaOps.Router.Common.Enums;
+using StellaOps.Router.Transport.InMemory;
+
+var builder = Host.CreateApplicationBuilder(args);
+
+// Configure the Stella microservice
+builder.Services.AddStellaMicroservice(options =>
+{
+    options.ServiceName = "inventory";
+    options.Version = "1.0.0";
+    options.Region = "demo";
+    options.InstanceId = $"inventory-{Environment.MachineName}";
+    options.Routers =
+    [
+        new RouterEndpointConfig
+        {
+            Host = "localhost",
+            Port = 5100,
+            TransportType = TransportType.InMemory
+        }
+    ];
+});
+
+// Register endpoint handlers
+builder.Services.AddScoped<ListItemsEndpoint>();
+builder.Services.AddScoped<GetItemEndpoint>();
+
+// Add in-memory transport
+builder.Services.AddInMemoryTransport();
+
+var host = builder.Build();
+
+Console.WriteLine("Inventory microservice starting...");
+await host.RunAsync();