# 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:**
```csharp
builder.Services.AddInMemoryTransport();
// or
builder.Services.AddTcpTransportServer(options => { options.Port = 5100; });
```

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

**Building RawResponse headers:**
```csharp
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
```bash
dotnet test src/Router/StellaOps.Router.sln
```

### Test Categories
- `Unit` - Fast, no external dependencies
- `Integration` - Requires multiple services
- `Transport` - Tests specific transport

## Build Commands

```bash
# 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