git.stella-ops.org/src/Router/AGENTS.md

Router Module - Agent Guidelines

Module Overview

The Router module provides transport-agnostic microservice communication with a unified HTTP gateway. It includes the Gateway WebService, all transport implementations, the Microservice SDK, and messaging infrastructure.

Directory Structure

src/Router/
├── StellaOps.Gateway.WebService/     # HTTP ingress gateway
├── __Libraries/
│   ├── StellaOps.Router.Gateway/     # Gateway core logic
│   ├── StellaOps.Router.Common/      # Shared models, enums
│   ├── StellaOps.Router.Config/      # YAML configuration
│   ├── StellaOps.Router.AspNet/      # ASP.NET integration
│   ├── StellaOps.Microservice/       # Microservice SDK
│   ├── StellaOps.Microservice.AspNetCore/ # ASP.NET hosting
│   ├── StellaOps.Microservice.SourceGen/ # Compile-time generator
│   ├── StellaOps.Messaging/          # Queue abstractions
│   ├── StellaOps.Messaging.Transport.InMemory/
│   ├── StellaOps.Messaging.Transport.Valkey/
│   ├── StellaOps.Messaging.Transport.Postgres/
│   ├── StellaOps.Router.Transport.InMemory/
│   ├── StellaOps.Router.Transport.Tcp/
│   ├── StellaOps.Router.Transport.Tls/
│   ├── StellaOps.Router.Transport.RabbitMq/
│   ├── StellaOps.Router.Transport.Udp/
│   └── StellaOps.Router.Transport.Messaging/
├── __Tests/
│   ├── __Libraries/
│   │   └── StellaOps.Router.Testing/  # Test fixtures
│   ├── StellaOps.Gateway.WebService.Tests/
│   ├── StellaOps.Microservice.Tests/
│   ├── StellaOps.Microservice.SourceGen.Tests/
│   ├── StellaOps.Router.Common.Tests/
│   ├── StellaOps.Router.Config.Tests/
│   ├── StellaOps.Router.Integration.Tests/
│   ├── StellaOps.Router.Transport.*.Tests/
│   └── StellaOps.Messaging.Transport.*.Tests/
└── examples/
    ├── Examples.OrderService/
    ├── Examples.NotificationService/
    └── Examples.MultiTransport.Gateway/

Key Components

Gateway WebService

• Entry point for all HTTP traffic
• Aggregates OpenAPI from microservices
• Handles authentication/authorization

Microservice SDK

• [StellaEndpoint] attribute for routing
• IStellaEndpoint<TRequest, TResponse> for typed handlers
• IRawStellaEndpoint for streaming handlers
• Source generator creates endpoint descriptors at compile time

Transport Layer

• All transports implement ITransportServer/ITransportClient
• Binary frame protocol for efficiency
• Pluggable - services declare transport type in config

Messaging Layer

• Queue-based communication (Valkey, PostgreSQL)
• Message leasing for at-least-once delivery
• Consumer groups for load distribution

Development Guidelines

Adding a New Transport

1. Create library: StellaOps.Router.Transport.{Name}
2. Implement ITransportServer and ITransportClient
3. Create DI extension: AddXxxTransport()
4. Add tests in __Tests/StellaOps.Router.Transport.{Name}.Tests/
5. Update solution file

Adding a New Endpoint Type

1. Define attribute in StellaOps.Microservice
2. Update source generator to handle new attribute
3. Add generator tests with expected output
4. Document in /docs/router/

Common Patterns

Registering a transport:

builder.Services.AddInMemoryTransport();
// or
builder.Services.AddTcpTransportServer(options => { options.Port = 5100; });

Defining an endpoint:

[StellaEndpoint("POST", "/resource", TimeoutSeconds = 30)]
public sealed class MyEndpoint : IStellaEndpoint<Request, Response>
{
    public Task<Response> HandleAsync(Request req, CancellationToken ct) => ...;
}

Building RawResponse headers:

var headers = new HeaderCollection();
headers.Set("Content-Type", "application/json");
return new RawResponse { StatusCode = 200, Headers = headers, Body = stream };

Testing

Unit Tests

• Test individual components in isolation
• Use Moq for dependencies
• Located in __Tests/StellaOps.*.Tests/

Integration Tests

• Test gateway + microservice communication
• Use StellaOps.Router.Testing fixtures
• Located in __Tests/StellaOps.Router.Integration.Tests/

Running Tests

dotnet test src/Router/StellaOps.Router.sln

Test Categories

• Unit - Fast, no external dependencies
• Integration - Requires multiple services
• Transport - Tests specific transport

Build Commands

# Build entire Router module
dotnet build src/Router/StellaOps.Router.sln

# Build gateway only
dotnet build src/Router/StellaOps.Gateway.WebService/

# Run examples
dotnet run --project src/Router/examples/Examples.OrderService/

Dependencies

External

• Microsoft.Extensions.Hosting - Service hosting
• Microsoft.AspNetCore.* - HTTP/WebSocket
• System.IO.Pipelines - High-performance I/O
• RabbitMQ.Client - RabbitMQ transport
• StackExchange.Redis - Valkey transport
• Npgsql - PostgreSQL transport

Internal

• StellaOps.DependencyInjection - DI abstractions
• StellaOps.Plugin - Plugin infrastructure
• StellaOps.Auth.Security - Auth integration
• StellaOps.Configuration - Config loading

Common Issues

ValueTask vs Task

• Interface methods returning ValueTask must return ValueTask.CompletedTask
• Interface methods returning Task must return Task.CompletedTask

HeaderCollection

• IHeaderCollection indexer is read-only
• Create new HeaderCollection() and use .Set() method
• Pass to RawResponse constructor

Transport Registration

• Use AddXxxTransport() without Server/Client suffix for auto-detection
• Or use AddXxxTransportServer() / AddXxxTransportClient() explicitly

Documentation

• /docs/router/README.md - Product overview
• /docs/router/ARCHITECTURE.md - Technical architecture
• /docs/router/GETTING_STARTED.md - Tutorial
• /docs/router/examples/ - Example documentation