stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save checkpoint

Browse Source
This commit is contained in:
master
2026-02-14 09:11:48 +02:00
parent 9ca2de05df
commit e9aeadc040
1512 changed files with 30863 additions and 4728 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/features/checked/router/asp-net-endpoint-discovery-and-router-dispatch-bridge.md Normal file
View File

@@ -0,0 +1,27 @@
# ASP.NET Endpoint Discovery and Router Dispatch Bridge
## Module
Router
## Status
IMPLEMENTED
## Description
SDK that bridges ASP.NET Core minimal API / controller endpoints to StellaRouter dispatch. Includes EndpointDiscoveryService, ASP.NET Core discovery provider (via reflection and source generation), authorization mapping, and DI extensions. Enables microservices to auto-register their endpoints with the StellaRouter without manual configuration.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Microservice/`, `src/Router/__Libraries/StellaOps.Microservice.SourceGen/`
- **Key Classes**:
- `EndpointDiscoveryService` (`src/Router/__Libraries/StellaOps.Microservice/EndpointDiscoveryService.cs`) - discovers ASP.NET Core endpoints for router registration
- `StellaEndpointGenerator` (`src/Router/__Libraries/StellaOps.Microservice.SourceGen/StellaEndpointGenerator.cs`) - Roslyn source generator for AOT-compatible endpoint registration
- `StellaEndpointAttribute` (`src/Router/__Libraries/StellaOps.Microservice/StellaEndpointAttribute.cs`) - attribute for marking router-discoverable endpoints
- `RouterConnectionManager` (`src/Router/__Libraries/StellaOps.Microservice/RouterConnectionManager.cs`) - manages HELLO/HEARTBEAT handshake with Gateway
- **Interfaces**: `IEndpointDiscoveryService`, `IRouterConnectionManager`
- **Source**: SPRINT_8100_0011_0001_router_sdk_aspnet_bridge.md
## E2E Test Plan
- [ ] Annotate endpoints with `[StellaEndpoint]` and verify `EndpointDiscoveryService` discovers them
- [ ] Verify auto-registration: start a microservice and confirm endpoints are registered with the Gateway
- [ ] Verify source-generated endpoint registration matches reflection-based discovery
- [ ] Verify authorization mapping: annotate endpoints with auth requirements and confirm they propagate to the router
- [ ] Verify `RouterConnectionManager` establishes HELLO handshake and sends periodic HEARTBEAT

30
docs/features/checked/router/gateway-core-routing-infrastructure.md Normal file
View File

@@ -0,0 +1,30 @@
# Gateway Core Routing Infrastructure
## Module
Router
## Status
IMPLEMENTED
## Description
Gateway core with `InMemoryRoutingState` for tracking connected microservice instances, `DefaultRoutingPlugin` with version-compatible/health-based/region-aware instance filtering, and rate limiting per instance.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Gateway/`, `src/Router/StellaOps.Gateway.WebService/`
- **Key Classes**:
- `InMemoryRoutingState` (`src/Router/__Libraries/StellaOps.Router.Gateway/State/InMemoryRoutingState.cs`) - tracks connected microservice instances and their endpoint descriptors
- `DefaultRoutingPlugin` (`src/Router/__Libraries/StellaOps.Router.Gateway/Routing/DefaultRoutingPlugin.cs`) - version-compatible, health-based, region-aware instance filtering
- `RequestRoutingMiddleware` (`src/Router/StellaOps.Gateway.WebService/Middleware/RequestRoutingMiddleware.cs`) - middleware dispatching HTTP requests to routed instances
- `ConnectionManager` (`src/Router/__Libraries/StellaOps.Router.Gateway/Services/ConnectionManager.cs`) - manages microservice connections to the gateway
- `HealthMonitorService` (`src/Router/__Libraries/StellaOps.Router.Gateway/Services/HealthMonitorService.cs`) - background health monitoring for connected instances
- `GatewayHostedService` (`src/Router/StellaOps.Gateway.WebService/Services/GatewayHostedService.cs`) - gateway lifecycle management
- `GatewayTransportClient` (`src/Router/StellaOps.Gateway.WebService/Services/GatewayTransportClient.cs`) - transport client for gateway-microservice communication
- **Interfaces**: `IGlobalRoutingState`, `IRoutingPlugin`
- **Source**: batch_51/file_20.md
## E2E Test Plan
- [ ] Connect a microservice to the gateway and verify `InMemoryRoutingState` tracks the instance
- [ ] Route a request via `DefaultRoutingPlugin` and verify it selects a healthy, version-compatible instance
- [ ] Verify rate limiting: send requests exceeding the per-instance limit and confirm throttling
- [ ] Verify region-aware routing: register instances in different regions and confirm regional preference
- [ ] Disconnect a microservice and verify `HealthMonitorService` removes it from routing state

28
docs/features/checked/router/inmemory-transport-plugin.md Normal file
View File

@@ -0,0 +1,28 @@
# InMemory Transport Plugin
## Module
Router
## Status
IMPLEMENTED
## Description
In-process transport using System.Threading.Channels for development and testing. Implements InMemoryTransportServer, InMemoryTransportClient, InMemoryConnectionRegistry, and InMemoryChannel with zero-copy semantics.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Transport.InMemory/`
- **Key Classes**:
- `InMemoryTransportPlugin` (`src/Router/__Libraries/StellaOps.Router.Transport.InMemory/InMemoryTransportPlugin.cs`) - plugin registration for in-memory transport
- `InMemoryTransportServer` (`src/Router/__Libraries/StellaOps.Router.Transport.InMemory/InMemoryTransportServer.cs`) - in-process transport server using System.Threading.Channels
- `InMemoryTransportClient` (`src/Router/__Libraries/StellaOps.Router.Transport.InMemory/InMemoryTransportClient.cs`) - in-process transport client with zero-copy semantics
- `InMemoryConnectionRegistry` (`src/Router/__Libraries/StellaOps.Router.Transport.InMemory/InMemoryConnectionRegistry.cs`) - tracks in-memory connections between server and clients
- `InMemoryChannel` (`src/Router/__Libraries/StellaOps.Router.Transport.InMemory/InMemoryChannel.cs`) - channel-based communication pipe
- **Interfaces**: `IRouterTransportPlugin`, `ITransportServer`, `ITransportClient`, `IMicroserviceTransport`
- **Source**: batch_51/file_17.md
## E2E Test Plan
- [ ] Register `InMemoryTransportPlugin` and verify a gateway and microservice can communicate in-process
- [ ] Send a request through `InMemoryTransportClient` and verify `InMemoryTransportServer` receives and processes it
- [ ] Verify zero-copy semantics: confirm no additional memory allocations for frame payload transfer
- [ ] Verify `InMemoryConnectionRegistry` tracks active connections
- [ ] Verify concurrent request handling: send multiple requests in parallel and confirm all complete

29
docs/features/checked/router/messaging-abstractions-library.md Normal file
View File

@@ -0,0 +1,29 @@
# Messaging Abstractions Library (Queue, Cache, Event Stream, Rate Limiter)
## Module
Router
## Status
IMPLEMENTED
## Description
Transport-agnostic messaging abstractions library providing IMessageQueue, IDistributedCache, IEventStream, IRateLimiter, IIdempotencyStore, and IAtomicTokenStore contracts. Includes InMemory, Postgres, and Valkey transport implementations with plugin-based transport registration.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Messaging/`, `src/Router/__Libraries/StellaOps.Messaging.Transport.InMemory/`, `src/Router/__Libraries/StellaOps.Messaging.Transport.Postgres/`, `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/`
- **Key Classes**:
- `InMemoryTransportPlugin` (`src/Router/__Libraries/StellaOps.Messaging.Transport.InMemory/InMemoryTransportPlugin.cs`) - in-memory messaging transport
- `PostgresTransportPlugin` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Postgres/PostgresTransportPlugin.cs`) - PostgreSQL-based messaging transport
- `ValkeyTransportPlugin` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs`) - Valkey/Redis-based messaging transport
- `ValkeyMessageQueue` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyMessageQueue.cs`) - Valkey message queue implementation
- `ValkeyEventStream` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyEventStream.cs`) - Valkey event stream implementation
- **Interfaces**: `IMessageQueue`, `IMessageQueueFactory`, `IDistributedCache`, `IEventStream`, `IRateLimiter`, `IIdempotencyStore`, `IAtomicTokenStore`, `ISetStore`, `ISortedIndex`, `IMessagingTransportPlugin` (all in `src/Router/__Libraries/StellaOps.Messaging/Abstractions/`)
- **Source**: Discovered via source verification (part of Router ecosystem, Sprint 7000 series)
## E2E Test Plan
- [ ] Enqueue and dequeue a message via `IMessageQueue` with each transport (InMemory, Postgres, Valkey)
- [ ] Store and retrieve cache entries via `IDistributedCache` with each transport
- [ ] Publish and subscribe to events via `IEventStream` with each transport
- [ ] Verify `IRateLimiter` throttles requests above the configured limit
- [ ] Verify `IIdempotencyStore` prevents duplicate processing of the same message
- [ ] Switch transports via plugin registration and verify seamless operation

25
docs/features/checked/router/microservice-endpoint-yaml-configuration-overrides.md Normal file
View File

@@ -0,0 +1,25 @@
# Microservice Endpoint YAML Configuration Overrides
## Module
Router
## Status
IMPLEMENTED
## Description
Per-endpoint YAML configuration overrides for timeouts, claim requirements, streaming enablement, and payload limits. Merges code-level `[StellaEndpoint]` attributes with YAML overrides at runtime.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Microservice/`
- **Key Classes**:
- `EndpointOverrideMerger` (`src/Router/__Libraries/StellaOps.Microservice/EndpointOverrideMerger.cs`) - merges code-level `[StellaEndpoint]` attributes with YAML configuration overrides
- `EndpointOverrideConfig` (`src/Router/__Libraries/StellaOps.Microservice/MicroserviceYamlConfig.cs`) - YAML model for per-endpoint overrides (timeouts, claims, streaming, payload limits)
- **Interfaces**: `IEndpointOverrideMerger`
- **Source**: batch_52/file_08.md
## E2E Test Plan
- [ ] Define a YAML override for an endpoint timeout and verify `EndpointOverrideMerger` applies it
- [ ] Define a YAML override for claim requirements and verify they are merged with attribute-defined claims
- [ ] Enable streaming via YAML for a non-streaming endpoint and verify the override takes effect
- [ ] Set payload limits via YAML and verify requests exceeding the limit are rejected
- [ ] Verify code-level attributes are preserved when no YAML override is defined

27
docs/features/checked/router/microservice-sdk-core.md Normal file
View File

@@ -0,0 +1,27 @@
# Microservice SDK Core (Endpoint Discovery and Connection Management)
## Module
Router
## Status
IMPLEMENTED
## Description
SDK for building Stella microservices with `[StellaEndpoint]` attribute-based endpoint discovery, `RouterConnectionManager` for HELLO/HEARTBEAT handshake with Gateway, and `AddStellaMicroservice()` DI registration. Enables services to register endpoints and communicate through the Router Gateway.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Microservice/`
- **Key Classes**:
- `StellaEndpointAttribute` (`src/Router/__Libraries/StellaOps.Microservice/StellaEndpointAttribute.cs`) - attribute for endpoint declaration with path, method, claims, and metadata
- `RouterConnectionManager` (`src/Router/__Libraries/StellaOps.Microservice/RouterConnectionManager.cs`) - manages HELLO/HEARTBEAT handshake lifecycle with Gateway
- `EndpointDiscoveryService` (`src/Router/__Libraries/StellaOps.Microservice/EndpointDiscoveryService.cs`) - discovers `[StellaEndpoint]`-annotated handlers at startup
- `EndpointRegistry` (`src/Router/__Libraries/StellaOps.Microservice/EndpointRegistry.cs`) - registry of discovered endpoints for dispatch
- **Interfaces**: `IRouterConnectionManager`, `IEndpointDiscoveryService`, `IEndpointRegistry`
- **Source**: batch_51/file_18.md
## E2E Test Plan
- [ ] Call `AddStellaMicroservice()` in DI and verify all services are registered
- [ ] Verify `EndpointDiscoveryService` discovers `[StellaEndpoint]`-annotated handlers
- [ ] Verify `RouterConnectionManager` sends HELLO with endpoint descriptors to Gateway
- [ ] Verify HEARTBEAT: confirm the connection manager sends periodic heartbeats
- [ ] Verify reconnection: disconnect the Gateway and confirm the manager reconnects automatically

27
docs/features/checked/router/microservice-sdk-request-dispatcher-and-typed-endpoint-adapters.md Normal file
View File

@@ -0,0 +1,27 @@
# Microservice SDK Request Dispatcher and Typed Endpoint Adapters
## Module
Router
## Status
IMPLEMENTED
## Description
Request dispatch pipeline with `RequestDispatcher`, `TypedEndpointAdapter<TRequest,TResponse>` for strongly-typed endpoint handling, `PathMatcher` with wildcard support, `EndpointRegistry`, and per-request DI scoping. Handles frame routing from Gateway to the correct endpoint handler.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Microservice/`, `src/Router/__Libraries/StellaOps.Router.Common/`
- **Key Classes**:
- `RequestDispatcher` (`src/Router/__Libraries/StellaOps.Microservice/RequestDispatcher.cs`) - dispatches incoming frames to the correct endpoint handler with per-request DI scoping
- `TypedEndpointAdapter` (`src/Router/__Libraries/StellaOps.Microservice/TypedEndpointAdapter.cs`) - strongly-typed adapter for `TRequest`/`TResponse` endpoint handling
- `PathMatcher` (`src/Router/__Libraries/StellaOps.Router.Common/PathMatcher.cs`) - matches request paths with wildcard and parameterized segment support
- `EndpointRegistry` (`src/Router/__Libraries/StellaOps.Microservice/EndpointRegistry.cs`) - lookup registry for endpoint handlers by path
- **Interfaces**: `IRequestDispatcher`, `IEndpointRegistry`
- **Source**: batch_51/file_19.md
## E2E Test Plan
- [ ] Register a typed endpoint and dispatch a request via `RequestDispatcher`, verifying the correct handler is invoked
- [ ] Verify `TypedEndpointAdapter` deserializes the request and serializes the response correctly
- [ ] Verify `PathMatcher` matches exact paths, wildcard segments, and parameterized segments
- [ ] Verify per-request DI scoping: confirm scoped services are created per request and disposed after
- [ ] Dispatch a request to a non-existent endpoint and verify a proper error response

26
docs/features/checked/router/region-aware-routing-algorithm.md Normal file
View File

@@ -0,0 +1,26 @@
# Region-Aware Routing Algorithm
## Module
Router
## Status
IMPLEMENTED
## Description
Full routing algorithm with 3-tier region preference (Tier 0: same region, Tier 1: same continent, Tier 2: cross-continent), ping-based latency selection within tiers, heartbeat recency weighting, and round-robin/random tie-breaking for deterministic load distribution.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Gateway/Routing/`, `src/Router/__Libraries/StellaOps.Router.Gateway/Services/`
- **Key Classes**:
- `DefaultRoutingPlugin` (`src/Router/__Libraries/StellaOps.Router.Gateway/Routing/DefaultRoutingPlugin.cs`) - implements 3-tier region preference with latency-based selection
- `PingTracker` (`src/Router/__Libraries/StellaOps.Router.Gateway/Services/PingTracker.cs`) - tracks ping-based latency measurements per instance
- `InMemoryRoutingState` (`src/Router/__Libraries/StellaOps.Router.Gateway/State/InMemoryRoutingState.cs`) - routing state with instance region metadata
- **Interfaces**: `IRoutingPlugin`, `IGlobalRoutingState`, `IRegionProvider`
- **Source**: batch_51/file_24.md
## E2E Test Plan
- [ ] Register instances in the same region, same continent, and cross-continent, then route a request and verify Tier 0 preference
- [ ] Verify latency-based selection: within the same tier, confirm the lowest-latency instance is preferred
- [ ] Verify heartbeat recency weighting: stale instances are deprioritized
- [ ] Verify round-robin tie-breaking: when latency is equal, confirm requests distribute evenly
- [ ] Remove all Tier 0 instances and verify fallback to Tier 1, then Tier 2

24
docs/features/checked/router/roslyn-endpoint-source-generator.md Normal file
View File

@@ -0,0 +1,24 @@
# Roslyn Endpoint Source Generator (AOT-Compatible)
## Module
Router
## Status
IMPLEMENTED
## Description
Roslyn incremental source generator that detects `[StellaEndpoint]` attributes at compile time and generates AOT-compatible endpoint registration code, eliminating runtime reflection for endpoint discovery. Supports Native AOT deployment scenarios.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Microservice.SourceGen/`
- **Key Classes**:
- `StellaEndpointGenerator` (`src/Router/__Libraries/StellaOps.Microservice.SourceGen/StellaEndpointGenerator.cs`) - Roslyn incremental source generator detecting `[StellaEndpoint]` attributes and generating `StellaEndpoints` registration class
- **Interfaces**: `IIncrementalGenerator` (Roslyn API)
- **Source**: batch_52/file_10.md
## E2E Test Plan
- [ ] Compile a project with `[StellaEndpoint]` attributes and verify the source generator produces registration code
- [ ] Verify generated code is AOT-compatible: publish with Native AOT and confirm endpoints are discoverable without reflection
- [ ] Verify the generated `StellaEndpoints` class registers all annotated endpoints
- [ ] Add a new `[StellaEndpoint]` and verify incremental generation updates the output
- [ ] Verify compile-time diagnostics: use invalid attribute parameters and confirm helpful error messages

24
docs/features/checked/router/router-backpressure.md Normal file
View File

@@ -0,0 +1,24 @@
# Router Backpressure (HTTP 429/503 + Retry-After)
## Module
Router
## Status
IMPLEMENTED
## Description
Rate limiting and backpressure testing with dedicated chaos test suite for the router, including Testcontainers-based fixture for burst testing.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Gateway/RateLimit/`, `src/Router/__Libraries/StellaOps.Router.Transport.InMemory/`
- **Key Classes**:
- `ValkeyRateLimitStore` (`src/Router/__Libraries/StellaOps.Router.Gateway/RateLimit/ValkeyRateLimitStore.cs`) - Valkey-backed rate limit storage for per-instance throttling
- `InMemoryRateLimiter` (`src/Router/__Libraries/StellaOps.Messaging.Transport.InMemory/InMemoryRateLimiter.cs`) - in-memory rate limiter for testing
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Send requests exceeding the rate limit and verify HTTP 429 responses with Retry-After header
- [ ] Verify HTTP 503 response when all instances are overloaded
- [ ] Verify backpressure propagation: confirm the gateway signals backpressure to callers when queues are full
- [ ] Verify rate limit recovery: after throttling, confirm requests resume when the limit window expires
- [ ] Verify per-instance rate limiting: confirm each microservice instance has its own rate limit counter

25
docs/features/checked/router/router-common-models-and-abstractions-library.md Normal file
View File

@@ -0,0 +1,25 @@
# Router Common Models and Abstractions Library
## Module
Router
## Status
IMPLEMENTED
## Description
Core shared library defining frame types (REQUEST, RESPONSE, HELLO, HEARTBEAT, CANCEL, STREAM_DATA), transport abstractions (ITransportServer, ITransportClient), routing contracts (IGlobalRoutingState, IRoutingPlugin, IRegionProvider), and model types (EndpointDescriptor, InstanceDescriptor, ConnectionState, RoutingContext, RoutingDecision, PayloadLimits).
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Common/`
- **Key Classes**:
- `PathMatcher` (`src/Router/__Libraries/StellaOps.Router.Common/PathMatcher.cs`) - path matching with wildcard and parameterized segment support
- **Interfaces**: `ITransportServer`, `ITransportClient`, `IGlobalRoutingState`, `IRoutingPlugin`, `IRegionProvider` (all defined in Router.Common)
- **Models**: `EndpointDescriptor`, `InstanceDescriptor`, `ConnectionState`, `RoutingContext`, `RoutingDecision`, `PayloadLimits`, frame types (REQUEST, RESPONSE, HELLO, HEARTBEAT, CANCEL, STREAM_DATA)
- **Source**: batch_51/file_16.md
## E2E Test Plan
- [ ] Verify all frame types can be serialized and deserialized correctly
- [ ] Verify `PathMatcher` handles exact, wildcard, and parameterized path matching
- [ ] Verify `EndpointDescriptor` carries all required metadata (path, method, version, claims)
- [ ] Verify `RoutingContext` and `RoutingDecision` models are populated correctly during routing
- [ ] Verify `PayloadLimits` enforcement: send a payload exceeding limits and confirm rejection

30
docs/features/checked/router/router-microservice-sdk-solution-infrastructure.md Normal file
View File

@@ -0,0 +1,30 @@
# Router/Microservice SDK Solution Infrastructure
## Module
Router
## Status
IMPLEMENTED
## Description
Complete solution skeleton for the Router ecosystem including 17 library projects, 17 test projects, example applications, and Gateway WebService. Establishes the project structure for inter-service communication.
## Implementation Details
- **Modules**: `src/Router/`
- **Key Projects**:
- `StellaOps.Gateway.WebService` - Gateway API service with routing middleware
- `StellaOps.Router.Common` - shared models, frame types, and transport abstractions
- `StellaOps.Router.Gateway` - gateway routing logic, state management, rate limiting
- `StellaOps.Router.Config` - YAML/JSON configuration with hot-reload
- `StellaOps.Microservice` - microservice SDK (endpoint discovery, connection, dispatch)
- `StellaOps.Microservice.SourceGen` - Roslyn source generator for AOT endpoints
- Transport plugins: `Router.Transport.InMemory`, `Router.Transport.Tcp`, `Router.Transport.Tls`, `Router.Transport.Udp`, `Router.Transport.RabbitMq`, `Router.Transport.Messaging`
- Messaging: `StellaOps.Messaging`, `Messaging.Transport.InMemory`, `Messaging.Transport.Postgres`, `Messaging.Transport.Valkey`
- `StellaOps.Router.Plugin.Unified` - unified plugin adapter system
- **Source**: batch_51/file_15.md
## E2E Test Plan
- [ ] Build all 17 library projects and verify successful compilation
- [ ] Run all 17 test project suites and verify they pass
- [ ] Build and run the Gateway WebService and verify it starts and accepts connections
- [ ] Build and run example applications and verify end-to-end communication through the Gateway

28
docs/features/checked/router/router-reference-implementation-examples.md Normal file
View File

@@ -0,0 +1,28 @@
# Router Reference Implementation Examples
## Module
Router
## Status
IMPLEMENTED
## Description
Complete reference implementations including Examples.Gateway, Examples.Billing.Microservice, Examples.Inventory.Microservice, Examples.MultiTransport.Gateway, and Examples.NotificationService demonstrating all Router SDK capabilities with docker-compose orchestration.
## Implementation Details
- **Modules**: `src/Router/examples/`
- **Key Projects**:
- `Examples.Gateway` (`src/Router/examples/Examples.Gateway/`) - reference Gateway setup
- `Examples.Billing.Microservice` (`src/Router/examples/Examples.Billing.Microservice/`) - billing service with CreateInvoice, GetInvoice, UploadAttachment endpoints
- `Examples.Inventory.Microservice` (`src/Router/examples/Examples.Inventory.Microservice/`) - inventory service with GetItem, ListItems endpoints
- `Examples.MultiTransport.Gateway` (`src/Router/examples/Examples.MultiTransport.Gateway/`) - gateway with multiple transport plugins
- `Examples.NotificationService` (`src/Router/examples/Examples.NotificationService/`) - notification service with send, broadcast, subscribe, preferences endpoints
- `Examples.OrderService` (`src/Router/examples/Examples.OrderService/`) - order service with CRUD, streaming export, and event endpoints
- **Source**: batch_52/file_11.md
## E2E Test Plan
- [ ] Build and run `Examples.Gateway` with `Examples.Billing.Microservice` and verify invoice creation via router
- [ ] Run `Examples.Inventory.Microservice` and verify item listing through the gateway
- [ ] Run `Examples.MultiTransport.Gateway` and verify communication over multiple transport types
- [ ] Run `Examples.NotificationService` and verify notification send/subscribe flow
- [ ] Run `Examples.OrderService` and verify streaming data export endpoint

25
docs/features/checked/router/router-request-cancellation-propagation.md Normal file
View File

@@ -0,0 +1,25 @@
# Router Request Cancellation Propagation
## Module
Router
## Status
IMPLEMENTED
## Description
CANCEL frame type for explicit request cancellation, inflight request tracking, client disconnect detection with automatic cancellation propagation to microservices, and CancellationToken integration in endpoint handlers.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Common/`, `src/Router/__Libraries/StellaOps.Microservice/`
- **Key Classes**:
- `RequestDispatcher` (`src/Router/__Libraries/StellaOps.Microservice/RequestDispatcher.cs`) - tracks inflight requests and propagates cancellation tokens
- `PathMatcher` (`src/Router/__Libraries/StellaOps.Router.Common/PathMatcher.cs`) - used in dispatch pipeline with cancellation support
- **Frame Types**: CANCEL frame for explicit request cancellation
- **Source**: batch_52/file_00.md
## E2E Test Plan
- [ ] Send a CANCEL frame for an inflight request and verify the endpoint handler's CancellationToken is triggered
- [ ] Disconnect a client during a long-running request and verify automatic cancellation propagation
- [ ] Verify inflight request tracking: confirm the dispatcher tracks active requests and cleans up after cancellation
- [ ] Verify endpoint handlers receive CancellationToken and can respond to cancellation gracefully
- [ ] Verify cancellation of a non-existent request ID is handled without errors

25
docs/features/checked/router/router-streaming-data-transfer.md Normal file
View File

@@ -0,0 +1,25 @@
# Router Streaming Data Transfer
## Module
Router
## Status
IMPLEMENTED
## Description
REQUEST_STREAM_DATA and RESPONSE_STREAM_DATA frame types for chunked streaming, backpressure handling via flow control, and streaming endpoint support in the Microservice SDK.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Common/`, `src/Router/__Libraries/StellaOps.Microservice/`
- **Key Classes**:
- `RequestDispatcher` (`src/Router/__Libraries/StellaOps.Microservice/RequestDispatcher.cs`) - handles streaming frame dispatch with backpressure
- `TypedEndpointAdapter` (`src/Router/__Libraries/StellaOps.Microservice/TypedEndpointAdapter.cs`) - supports streaming request/response patterns
- **Frame Types**: REQUEST_STREAM_DATA, RESPONSE_STREAM_DATA for chunked transfer
- **Source**: batch_52/file_01.md
## E2E Test Plan
- [ ] Send a streaming request with multiple data chunks and verify the endpoint receives all chunks
- [ ] Verify streaming response: send a request to a streaming endpoint and confirm chunked response delivery
- [ ] Verify backpressure: send data faster than the receiver processes and confirm flow control signals
- [ ] Verify large file streaming: transfer a large payload via streaming and confirm complete delivery
- [ ] Verify streaming cancellation: cancel mid-stream and confirm resources are cleaned up

28
docs/features/checked/router/router-yaml-json-configuration-with-hot-reload.md Normal file
View File

@@ -0,0 +1,28 @@
# Router YAML/JSON Configuration with Hot-Reload
## Module
Router
## Status
IMPLEMENTED
## Description
Centralized router configuration supporting YAML and JSON formats with `IOptionsMonitor` integration and `FileSystemWatcher`-based hot-reload. Includes validation, change event notification, and per-service routing options.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Config/`
- **Key Classes**:
- `RouterConfig` (`src/Router/__Libraries/StellaOps.Router.Config/RouterConfig.cs`) - root configuration model for router settings
- `RouterConfigProvider` (`src/Router/__Libraries/StellaOps.Router.Config/RouterConfigProvider.cs`) - watches config files and provides hot-reload via `IOptionsMonitor`
- `RouterConfigOptions` (`src/Router/__Libraries/StellaOps.Router.Config/RouterConfigOptions.cs`) - options for config file paths and reload behavior
- `GatewayOptions` (`src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptions.cs`) - gateway-specific configuration options
- `GatewayOptionsValidator` (`src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptionsValidator.cs`) - validates gateway configuration
- **Interfaces**: `IRouterConfigProvider`
- **Source**: batch_52/file_07.md
## E2E Test Plan
- [ ] Load router configuration from a YAML file and verify `RouterConfig` is populated correctly
- [ ] Load configuration from a JSON file and verify equivalent behavior
- [ ] Modify the config file at runtime and verify `RouterConfigProvider` triggers hot-reload
- [ ] Verify change event notification: subscribe to config changes and confirm notification on reload
- [ ] Verify validation: provide invalid config values and confirm `GatewayOptionsValidator` rejects them

29
docs/features/checked/router/tls-mtls-transport-plugin.md Normal file
View File

@@ -0,0 +1,29 @@
# TLS/mTLS Transport Plugin
## Module
Router
## Status
IMPLEMENTED
## Description
TLS transport wrapping TCP with SslStream, supporting mutual TLS (mTLS) with client certificate validation, certificate hot-reload without connection drops, and configurable cipher suites.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Transport.Tls/`
- **Key Classes**:
- `TlsTransportPlugin` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/TlsTransportPlugin.cs`) - plugin registration for TLS/mTLS transport
- `TlsTransportServer` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/TlsTransportServer.cs`) - TLS-wrapped transport server with mTLS support
- `TlsTransportClient` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/TlsTransportClient.cs`) - TLS-wrapped transport client with client certificate
- `CertificateLoader` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/CertificateLoader.cs`) - loads certificates from file/store
- `CertificateWatcher` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/CertificateWatcher.cs`) - watches certificate files for hot-reload without connection drops
- `TlsConnection` (`src/Router/__Libraries/StellaOps.Router.Transport.Tls/TlsConnection.cs`) - TLS connection wrapper
- **Interfaces**: `IRouterTransportPlugin`, `ITransportServer`, `ITransportClient`, `IMicroserviceTransport`
- **Source**: batch_52/file_04.md
## E2E Test Plan
- [ ] Register `TlsTransportPlugin` and verify TLS-encrypted communication between gateway and microservice
- [ ] Enable mTLS and verify client certificate validation rejects connections without valid client certs
- [ ] Replace a server certificate and verify `CertificateWatcher` hot-reloads without dropping active connections
- [ ] Verify cipher suite configuration: restrict to specific ciphers and confirm they are enforced
- [ ] Verify connection fails with expired or self-signed certificates when validation is strict

31
docs/features/checked/router/valkey-messaging-transport-for-gateway.md Normal file
View File

@@ -0,0 +1,31 @@
# Valkey (Redis-Compatible) Messaging Transport for Gateway
## Module
Router
## Status
IMPLEMENTED
## Description
Adds Valkey (Redis-compatible) as a messaging transport option for the Gateway/Router, including DI wiring, HELLO/heartbeat handling, atomic token store, cache factory, and messaging dispatch. Provides a high-performance alternative to the existing messaging infrastructure.
## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/`
- **Key Classes**:
- `ValkeyTransportPlugin` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs`) - Valkey messaging transport plugin registration
- `ValkeyMessageQueue` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyMessageQueue.cs`) - Valkey-backed message queue with lease support
- `ValkeyMessageQueueFactory` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyMessageQueueFactory.cs`) - factory for creating Valkey message queues
- `ValkeyEventStream` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyEventStream.cs`) - Valkey-backed event stream for pub/sub
- `ValkeyAtomicTokenStore` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyAtomicTokenStore.cs`) - atomic token operations for idempotency
- `ValkeyCacheStore` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyCacheStore.cs`) - Valkey-backed distributed cache
- `ValkeyConnectionFactory` (`src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyConnectionFactory.cs`) - manages Valkey connections
- **Interfaces**: `IMessagingTransportPlugin`, `IMessageQueue`, `IEventStream`, `IAtomicTokenStore`, `IDistributedCache`
- **Source**: SPRINT_8100_0011_0003_gateway_valkey_messaging_transport.md
## E2E Test Plan
- [ ] Register `ValkeyTransportPlugin` and verify messaging operations work through Valkey
- [ ] Enqueue and dequeue messages via `ValkeyMessageQueue` and verify ordering
- [ ] Publish and subscribe to events via `ValkeyEventStream` and verify delivery
- [ ] Verify `ValkeyAtomicTokenStore` provides atomic compare-and-set operations
- [ ] Verify `ValkeyCacheStore` stores and retrieves cached entries with TTL
- [ ] Verify connection pooling via `ValkeyConnectionFactory` under concurrent load