# 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)