204 lines
8.0 KiB
Markdown
204 lines
8.0 KiB
Markdown
# 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)
|