Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
183
src/Router/AGENTS.md
Normal file
183
src/Router/AGENTS.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user