---
phase: 06-gateway-plugin-research
plan: 02
type: execute
wave: 1
depends_on: [006-01]
files_modified: []
autonomous: true
requirements: [PLUG-03]
must_haves:
  truths:
    - "插件通过路由 Metadata 启用"
    - "请求 Transform 轻量处理请求"
    - "目标选择在路由匹配后执行"
    - "插件按配置顺序执行"
  artifacts:
    - path: "src/yarpgateway/Plugins/PluginTransformProvider.cs"
      provides: "YARP Transform 提供者"
    - path: "src/yarpgateway/Plugins/YarpPluginMiddleware.cs"
      provides: "插件管道集成"
    - path: "src/yarpgateway/Plugins/PluginConfigWatcher.cs"
      provides: "Console DB 通知监听"
    - path: "tests/YarpGateway.Tests/Unit/Plugins/YarpIntegrationTests.cs"
      provides: "集成测试"
key_links:
  - from: "PluginTransformProvider"
    to: "PluginHost"
    via: "获取已加载插件"
  - from: "YarpPluginMiddleware"
    to: "PluginTransformProvider"
    via: "应用 Transform"
  - from: "PluginConfigWatcher"
    to: "PluginHost"
    via: "触发重载"
---

# 计划 02：YARP 插件集成

<objective>
将插件系统集成到 YARP 反向代理管道，实现 Transform 方式的请求/响应处理，以及通过 Metadata 驱动的插件启用机制。

**目的：** 实现 PLUG-03 - 插件隔离与生命周期管理，完成网关插件化。
**产出：** 可工作的 YARP 插件集成系统，含单元测试。
</objective>

<execution_context>
@/Users/mac/.config/opencode/get-shit-done/workflows/execute-plan.md
@/Users/mac/.config/opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/006-gateway-plugin-research/006-RESEARCH.md
@src/Fengling.Gateway.Plugin.Abstractions/IGatewayPlugin.cs
@src/yarpgateway/Plugins/PluginHost.cs
@src/yarpgateway/Program.cs
</context>

<interfaces>
## 现有插件接口

```csharp
// Fengling.Gateway.Plugin.Abstractions
public interface IGatewayPlugin
{
    string Name { get; }
    string Version { get; }
    string? Description { get; }
    Task OnLoadAsync();
    Task OnUnloadAsync();
}

public interface IRequestPlugin : IGatewayPlugin
{
    Task<HttpContext?> OnRequestAsync(HttpContext context);
    Task<HttpContext?> OnRouteMatchedAsync(HttpContext context, RouteConfig route);
    Task<HttpContext?> OnForwardingAsync(HttpContext context, HttpRequestMessage request);
}

public interface IResponsePlugin : IGatewayPlugin
{
    Task OnBackendResponseAsync(HttpContext context, HttpResponseMessage response);
    Task OnResponseFinalizingAsync(HttpContext context);
}

public interface IRouteTransformPlugin : IGatewayPlugin
{
    Task<RouteConfig> TransformRouteAsync(RouteConfig original, HttpContext context);
}
```

## YARP Transform 接口

```csharp
// YARP Transform
public interface IRequestTransform
{
    Task ApplyAsync(RequestTransformContext context);
}

public interface IResponseTransform
{
    Task ApplyAsync(ResponseTransformContext context);
}

public interface IClusterDestinationsTransform
{
    Task ApplyAsync(ClusterDestinationsContext context);
}
```
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: 创建 PluginTransformProvider</name>
  <files>
    src/yarpgateway/Plugins/PluginTransformProvider.cs,
    tests/YarpGateway.Tests/Unit/Plugins/PluginTransformProviderTests.cs
  </files>
  <behavior>
    - Test 1: 从路由 Metadata 发现启用的插件
    - Test 2: 按 PluginOrder 排序
    - Test 3: 创建 RequestTransform
    - Test 4: 创建 ResponseTransform
  </behavior>
  <action>
创建 YARP Transform 提供者：

1. 创建 `PluginTransformProvider.cs`：
   - 实现 `IProxyConfigFilter` 或 `IDynamicRouteConfigProvider`
   - 扫描路由 Metadata 中的 "Plugins" 键
   - 从 PluginHost 获取已加载的插件
   - 按 "PluginOrder" 排序

2. 核心逻辑：
```csharp
public class PluginTransformProvider : IProxyConfigFilter
{
    private readonly PluginHost _pluginHost;
    
    public async Task ApplyTransformAsync(HttpContext context, RouteConfig route)
    {
        var pluginIds = route.Metadata?["Plugins"]?.Split(',');
        if (pluginIds == null) return;
        
        var order = route.Metadata?["PluginOrder"]?.Split(',') ?? pluginIds;
        var orderedPlugins = order.Select(id => pluginIds.IndexOf(id))
            .Select(i => _pluginHost.GetPlugins().ElementAt(i));
            
        foreach (var plugin in orderedPlugins.OfType<IRequestPlugin>())
        {
            await plugin.OnRouteMatchedAsync(context, route);
        }
    }
}
```

3. 创建 Request/Response Transform 类：
   - `PluginRequestTransform` - 调用 IRequestPlugin
   - `PluginResponseTransform` - 调用 IResponsePlugin
   - `PluginRouteTransform` - 调用 IRouteTransformPlugin
  </action>
  <verify>
    <automated>dotnet test tests/YarpGateway.Tests --filter "FullyQualifiedName~PluginTransformProviderTests" --no-build</automated>
  </verify>
  <done>
    - PluginTransformProvider 存在
    - Transform 测试通过
  </done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: 创建目标选择器 (DestinationSelector)</name>
  <files>
    src/yarpgateway/Plugins/DestinationSelector.cs,
    tests/YarpGateway.Tests/Unit/Plugins/DestinationSelectorTests.cs
  </files>
  <behavior>
    - Test 1: OnRouteMatchedAsync 选择目标
    - Test 2: 根据上下文修改目标列表
    - Test 3: 特殊租户路由到特殊目标
  </behavior>
  <action>
创建目标选择器，用于 OnRouteMatchedAsync 阶段：

1. 创建 `DestinationSelector.cs`：
   - 实现 IClusterDestinationsTransform
   - 在路由匹配后、负载均衡前执行
   - 可以根据 HttpContext 修改可用目标列表

```csharp
public class DestinationSelector : IClusterDestinationsTransform
{
    private readonly PluginHost _pluginHost;
    
    public async Task ApplyAsync(ClusterDestinationsContext context)
    {
        var httpContext = context.HttpContext;
        
        // 获取路由上启用的插件
        var routeConfig = httpContext.GetRouteConfig();
        var pluginIds = routeConfig?.Metadata?["Plugins"]?.Split(',');
        
        if (pluginIds == null) return;
        
        foreach (var pluginId in pluginIds)
        {
            var plugin = _pluginHost.GetPlugin(pluginId);
            if (plugin is IRequestPlugin requestPlugin)
            {
                // 让插件过滤/修改目标列表
                var availableDestinations = context.Destinations.ToList();
                // 插件逻辑可以修改 availableDestinations
                context.Destinations = availableDestinations;
            }
        }
    }
}
```

2. 注册到 YARP：
```csharp
builder.Services.AddSingleton<IClusterDestinationsTransform, DestinationSelector>();
```
  </action>
  <verify>
    <automated>dotnet test tests/YarpGateway.Tests --filter "FullyQualifiedName~DestinationSelectorTests" --no-build</automated>
  </verify>
  <done>
    - DestinationSelector 存在
    - 目标选择逻辑工作正常
  </done>
</task>

<task type="auto" tdd="true">
  <name>Task 3: 创建 PluginConfigWatcher (Console DB 通知)</name>
  <files>
    src/yarpgateway/Plugins/PluginConfigWatcher.cs,
    tests/YarpGateway.Tests/Unit/Plugins/PluginConfigWatcherTests.cs
  </files>
  <behavior>
    - Test 1: 监听配置变更通知
    - Test 2: 触发插件重载
    - Test 3: 处理通知失败
  </behavior>
  <action>
创建配置监听器，监听 Console DB 通知：

1. 创建 `PluginConfigWatcher.cs`：
   - 实现 `IHostedService` 或使用现有的 `PgSqlConfigChangeListener`
   - 监听插件配置变更频道（如 `plugin_config_changed`）
   - 触发 PluginHost 重载

```csharp
public class PluginConfigWatcher : BackgroundService
{
    private readonly PluginHost _pluginHost;
    private readonly NpgsqlConnection _connection;
    private const string Channel = "plugin_config_changed";
    
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await _connection.OpenAsync(stoppingToken);
        await _connection.ListenAsync(Channel, stoppingToken);
        
        await foreach (var notification in _connection.Notifications(stoppingToken))
        {
            // 解析通知，获取需要重载的插件
            var payload = JsonSerializer.Deserialize<PluginConfigPayload>(notification.Payload);
            await _pluginHost.ReloadAsync(payload.PluginId);
        }
    }
}
```

2. 注册到 DI：
```csharp
builder.Services.AddHostedService<PluginConfigWatcher>();
```
  </action>
  <verify>
    <automated>dotnet test tests/YarpGateway.Tests --filter "FullyQualifiedName~PluginConfigWatcherTests" --no-build</automated>
  </verify>
  <done>
    - PluginConfigWatcher 存在
    - 监听器正确响应通知
  </done>
</task>

<task type="auto" tdd="true">
  <name>Task 4: 更新 Program.cs 集成插件系统</name>
  <files>
    src/yarpgateway/Program.cs
  </files>
  <behavior>
    - Test 1: 插件系统在启动时初始化
    - Test 2: Transform 被正确应用
  </behavior>
  <action>
更新 Program.cs 集成插件系统：

1. 注册插件服务：
```csharp
// 插件目录
var pluginDirectory = configuration.GetValue<string>("Plugin:Directory") ?? "plugins";

// 插件主机
builder.Services.AddSingleton(sp => new PluginHost(pluginDirectory));

// Transform 提供者
builder.Services.AddSingleton<IProxyConfigFilter, PluginTransformProvider>();

// 目标选择器
builder.Services.AddSingleton<IClusterDestinationsTransform, DestinationSelector>();

// 配置监听器
builder.Services.AddHostedService<PluginConfigWatcher>();
```

2. 初始化插件：
```csharp
var app = builder.Build();

// 启动时加载插件
var pluginHost = app.Services.GetRequiredService<PluginHost>();
await pluginHost.LoadAllAsync();
```

3. 配置 YARP 使用 Transform：
```csharp
builder.Services.AddReverseProxy()
    .AddTransforms<PluginTransformProvider>();
```
  </action>
  <verify>
    <automated>dotnet build src/yarpgateway/YarpGateway.csproj</automated>
  </verify>
  <done>
    - Program.cs 正确集成插件系统
    - 构建通过
  </done>
</task>

</tasks>

<verification>
1. dotnet build src/yarpgateway/YarpGateway.csproj 无错误
2. dotnet test tests/YarpGateway.Tests --filter "FullyQualifiedName~Plugin" 通过
3. 插件可通过 Metadata 启用
4. Transform 正确应用到请求/响应
</verification>

<success_criteria>
- 插件通过 YARP Transform 管道处理请求
- 目标选择在路由匹配后执行
- 插件通过 Metadata 启用
- Console DB 通知可触发插件重载
- 所有单元测试通过
</success_criteria>

<output>
完成后创建 `.planning/phases/006-gateway-plugin-research/006-02-SUMMARY.md`
</output>