save progress
This commit is contained in:
StellaOps Bot
203
docs/router/transports/README.md
Normal file
203
docs/router/transports/README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# Router Transport Plugins
|
||||
|
||||
StellaOps Router uses a **plugin-based transport architecture** that enables runtime loading of transport implementations. This allows operators to deploy only the transports they need and swap implementations without recompiling the Gateway.
|
||||
|
||||
## Available Transports
|
||||
|
||||
| Transport | Plugin Assembly | Use Case | Status |
|
||||
|-----------|-----------------|----------|--------|
|
||||
| [TCP](./tcp.md) | `StellaOps.Router.Transport.Tcp.dll` | Internal services, same datacenter | Stable |
|
||||
| [TLS](./tls.md) | `StellaOps.Router.Transport.Tls.dll` | Cross-datacenter, mTLS | Stable |
|
||||
| [UDP](./udp.md) | `StellaOps.Router.Transport.Udp.dll` | Fire-and-forget, broadcast | Stable |
|
||||
| [RabbitMQ](./rabbitmq.md) | `StellaOps.Router.Transport.RabbitMq.dll` | Async processing, fan-out | Stable |
|
||||
| [InMemory](./inmemory.md) | `StellaOps.Router.Transport.InMemory.dll` | Development, testing | Stable |
|
||||
| Valkey | `StellaOps.Messaging.Transport.Valkey.dll` | Distributed, pub/sub | Stable |
|
||||
| PostgreSQL | `StellaOps.Messaging.Transport.Postgres.dll` | Transactional, LISTEN/NOTIFY | Stable |
|
||||
|
||||
## Plugin Architecture
|
||||
|
||||
### Loading Model
|
||||
|
||||
Transport plugins are loaded at Gateway startup via `RouterTransportPluginLoader`:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Gateway Startup │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||||
│ │ RouterTransportPluginLoader │ │
|
||||
│ │ │ │
|
||||
│ │ 1. Scan plugins/router/transports/ │ │
|
||||
│ │ 2. Load assemblies in isolation (AssemblyLoadContext) │ │
|
||||
│ │ 3. Discover IRouterTransportPlugin implementations │ │
|
||||
│ │ 4. Register configured transport with DI │ │
|
||||
│ └────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Transport Plugin (e.g., TLS) │ │
|
||||
│ │ │ │
|
||||
│ │ - TransportName: "tls" │ │
|
||||
│ │ - DisplayName: "TLS Transport" │ │
|
||||
│ │ - IsAvailable(): Check dependencies │ │
|
||||
│ │ - Register(): Wire up ITransportServer/ITransportClient │ │
|
||||
│ └────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
plugins/
|
||||
└── router/
|
||||
└── transports/
|
||||
├── StellaOps.Router.Transport.Tcp.dll
|
||||
├── StellaOps.Router.Transport.Tls.dll
|
||||
├── StellaOps.Router.Transport.Udp.dll
|
||||
├── StellaOps.Router.Transport.RabbitMq.dll
|
||||
└── StellaOps.Router.Transport.InMemory.dll
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Transport selection and options are configured in `router.yaml` or environment variables:
|
||||
|
||||
```yaml
|
||||
Router:
|
||||
Transport:
|
||||
Type: tls # Which transport plugin to use
|
||||
Tls: # Transport-specific options
|
||||
Port: 5101
|
||||
CertificatePath: /certs/server.pfx
|
||||
RequireClientCertificate: true
|
||||
Tcp:
|
||||
Port: 5100
|
||||
MaxConnections: 1000
|
||||
```
|
||||
|
||||
Environment override:
|
||||
```bash
|
||||
ROUTER__TRANSPORT__TYPE=tcp
|
||||
ROUTER__TRANSPORT__TCP__PORT=5100
|
||||
```
|
||||
|
||||
## Using Plugins in Gateway
|
||||
|
||||
### Programmatic Loading
|
||||
|
||||
```csharp
|
||||
using StellaOps.Router.Common.Plugins;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
// Load transport plugins from directory
|
||||
var pluginLoader = new RouterTransportPluginLoader(
|
||||
builder.Services.BuildServiceProvider().GetService<ILogger<RouterTransportPluginLoader>>());
|
||||
|
||||
var pluginsPath = Path.Combine(AppContext.BaseDirectory, "plugins", "router", "transports");
|
||||
pluginLoader.LoadFromDirectory(pluginsPath);
|
||||
|
||||
// Register the configured transport (reads Router:Transport:Type from config)
|
||||
pluginLoader.RegisterConfiguredTransport(
|
||||
builder.Services,
|
||||
builder.Configuration,
|
||||
RouterTransportMode.Both); // Register both server and client
|
||||
|
||||
var app = builder.Build();
|
||||
// ...
|
||||
```
|
||||
|
||||
### Gateway Integration
|
||||
|
||||
The Gateway automatically loads transport plugins during startup. Configure in `router.yaml`:
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
name: api-gateway
|
||||
plugins:
|
||||
transports:
|
||||
directory: plugins/router/transports
|
||||
searchPattern: "StellaOps.Router.Transport.*.dll"
|
||||
```
|
||||
|
||||
## Creating Custom Transports
|
||||
|
||||
See the [Transport Plugin Development Guide](./development.md) for creating custom transport implementations.
|
||||
|
||||
### Minimal Plugin Example
|
||||
|
||||
```csharp
|
||||
using StellaOps.Router.Common.Plugins;
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
|
||||
namespace MyCompany.Router.Transport.Custom;
|
||||
|
||||
public sealed class CustomTransportPlugin : IRouterTransportPlugin
|
||||
{
|
||||
public string TransportName => "custom";
|
||||
public string DisplayName => "Custom Transport";
|
||||
|
||||
public bool IsAvailable(IServiceProvider services) => true;
|
||||
|
||||
public void Register(RouterTransportRegistrationContext context)
|
||||
{
|
||||
var configSection = context.Configuration.GetSection("Router:Transport:Custom");
|
||||
|
||||
context.Services.Configure<CustomTransportOptions>(options =>
|
||||
{
|
||||
configSection.Bind(options);
|
||||
});
|
||||
|
||||
if (context.Mode.HasFlag(RouterTransportMode.Server))
|
||||
{
|
||||
context.Services.AddSingleton<CustomTransportServer>();
|
||||
context.Services.AddSingleton<ITransportServer>(sp =>
|
||||
sp.GetRequiredService<CustomTransportServer>());
|
||||
}
|
||||
|
||||
if (context.Mode.HasFlag(RouterTransportMode.Client))
|
||||
{
|
||||
context.Services.AddSingleton<CustomTransportClient>();
|
||||
context.Services.AddSingleton<ITransportClient>(sp =>
|
||||
sp.GetRequiredService<CustomTransportClient>());
|
||||
context.Services.AddSingleton<IMicroserviceTransport>(sp =>
|
||||
sp.GetRequiredService<CustomTransportClient>());
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Transport Selection Guide
|
||||
|
||||
| Scenario | Recommended Transport | Configuration |
|
||||
|----------|----------------------|---------------|
|
||||
| Development/Testing | InMemory | `Type: inmemory` |
|
||||
| Same-datacenter | TCP | `Type: tcp` |
|
||||
| Cross-datacenter secure | TLS | `Type: tls` with mTLS |
|
||||
| High-volume async | RabbitMQ | `Type: rabbitmq` |
|
||||
| Broadcast/fire-and-forget | UDP | `Type: udp` |
|
||||
| Distributed with replay | Valkey | Via Messaging plugins |
|
||||
| Transactional messaging | PostgreSQL | Via Messaging plugins |
|
||||
|
||||
## Air-Gap Deployment
|
||||
|
||||
For offline/air-gapped deployments:
|
||||
|
||||
1. Pre-package transport plugins with your deployment
|
||||
2. Configure the plugin directory path
|
||||
3. No external network access required
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
plugins:
|
||||
transports:
|
||||
directory: /opt/stellaops/plugins/router/transports
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Router Architecture](../ARCHITECTURE.md)
|
||||
- [Plugin SDK Guide](../../10_PLUGIN_SDK_GUIDE.md)
|
||||
- [Unified Plugin System](../../plugins/README.md)
|
||||
Reference in New Issue
Block a user