feat(S4): add QQ WebSocket gateway with identify, heartbeat, resume and session persistence

This commit is contained in:
2026-11-09 22:13:13 +08:00
parent 968536e5b6
commit 43ea1a9971
8 changed files with 915 additions and 8 deletions
+262
View File
@@ -0,0 +1,262 @@
using System.Net;
using System.Text;
using System.Text.Json;
using Microsoft.Data.Sqlite;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using OshimaBot.Data;
using OshimaBot.Models;
using OshimaBot.Services;
using OshimaBot.Services.Gateway;
using Xunit;
namespace OshimaBot.Tests;
public sealed class GatewayProtocolTests
{
[Fact]
public void Identify_UsesOfficialTokenIntentsAndSingleShard()
{
using JsonDocument document = JsonDocument.Parse(
GatewayProtocol.BuildIdentify("ACCESS", QQBotOptions.DefaultIntents));
JsonElement payload = document.RootElement;
Assert.Equal(2, payload.GetProperty("op").GetInt32());
JsonElement data = payload.GetProperty("d");
Assert.Equal("QQBot ACCESS", data.GetProperty("token").GetString());
Assert.Equal(100663296, data.GetProperty("intents").GetInt32());
Assert.Equal(new[] { 0, 1 }, data.GetProperty("shard").EnumerateArray().Select(x => x.GetInt32()).ToArray());
Assert.True(data.GetProperty("properties").TryGetProperty("$os", out _));
}
[Fact]
public void Resume_CarriesSessionIdAndLastSeq()
{
using JsonDocument document = JsonDocument.Parse(
GatewayProtocol.BuildResume("ACCESS", "session-1", 1337));
JsonElement payload = document.RootElement;
Assert.Equal(6, payload.GetProperty("op").GetInt32());
JsonElement data = payload.GetProperty("d");
Assert.Equal("QQBot ACCESS", data.GetProperty("token").GetString());
Assert.Equal("session-1", data.GetProperty("session_id").GetString());
Assert.Equal(1337, data.GetProperty("seq").GetInt64());
}
[Fact]
public void Heartbeat_UsesNullBeforeFirstDispatch()
{
using JsonDocument first = JsonDocument.Parse(GatewayProtocol.BuildHeartbeat(null));
Assert.Equal(JsonValueKind.Null, first.RootElement.GetProperty("d").ValueKind);
using JsonDocument later = JsonDocument.Parse(GatewayProtocol.BuildHeartbeat(251));
Assert.Equal(251, later.RootElement.GetProperty("d").GetInt32());
}
[Fact]
public void Hello_ParsesIntervalWithSafeFallback()
{
using JsonDocument hello = JsonDocument.Parse("""{"heartbeat_interval":41250}""");
Assert.Equal(41250, GatewayProtocol.ParseHeartbeatInterval(hello.RootElement));
using JsonDocument broken = JsonDocument.Parse("""{}""");
Assert.Equal(45000, GatewayProtocol.ParseHeartbeatInterval(broken.RootElement));
using JsonDocument tooSmall = JsonDocument.Parse("""{"heartbeat_interval":1}""");
Assert.Equal(1000, GatewayProtocol.ParseHeartbeatInterval(tooSmall.RootElement));
}
[Fact]
public void Ready_ParsesSessionId()
{
using JsonDocument ready = JsonDocument.Parse(
"""{"version":1,"session_id":"082ee18c-0be3-491b-9d8b-fbd95c51673a","user":{"id":"1"}}""");
Assert.Equal("082ee18c-0be3-491b-9d8b-fbd95c51673a", GatewayProtocol.ParseSessionId(ready.RootElement));
Assert.Null(GatewayProtocol.ParseSessionId(JsonDocument.Parse("{}").RootElement));
}
[Theory]
[InlineData(4009, GatewayCloseAction.Resume)]
[InlineData(4008, GatewayCloseAction.Resume)]
[InlineData(4006, GatewayCloseAction.Identify)]
[InlineData(4007, GatewayCloseAction.Identify)]
[InlineData(4900, GatewayCloseAction.Identify)]
[InlineData(4913, GatewayCloseAction.Identify)]
[InlineData(4004, GatewayCloseAction.RefreshToken)]
[InlineData(4013, GatewayCloseAction.Stop)]
[InlineData(4014, GatewayCloseAction.Stop)]
[InlineData(4914, GatewayCloseAction.Stop)]
[InlineData(4915, GatewayCloseAction.Stop)]
[InlineData(4001, GatewayCloseAction.Stop)]
public void ClosePolicy_FollowsOfficialErrorTable(int code, GatewayCloseAction expected)
=> Assert.Equal(expected, GatewayProtocol.DecideCloseAction(code));
[Fact]
public void ClosePolicy_NormalClosureAllowsResume()
{
Assert.Equal(GatewayCloseAction.Resume, GatewayProtocol.DecideCloseAction(null));
Assert.Equal(GatewayCloseAction.Resume, GatewayProtocol.DecideCloseAction(1000));
}
}
public sealed class GatewayInfrastructureTests
{
private const string GatewayJson = """
{"url":"wss://api.bot.qq.com/websocket/","shards":9,
"session_start_limit":{"total":1000,"remaining":999,"reset_after":14400000,"max_concurrency":1}}
""";
[Fact]
public async Task GatewayApiClient_ParsesShardInfoAndCachesResult()
{
StubHttpHandler handler = new(_ => new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(GatewayJson, Encoding.UTF8, "application/json")
});
GatewayApiClient api = CreateApiClient(handler, new QQBotOptions { Enabled = true, AppId = "1", Secret = "s" });
GatewayInfo info = await api.GetGatewayAsync();
Assert.Equal("wss://api.bot.qq.com/websocket/", info.Url);
Assert.Equal(9, info.Shards);
Assert.Equal(1, info.MaxConcurrency);
Assert.Equal(999, info.Remaining);
Assert.Equal("/gateway/bot", Assert.Single(handler.Requests).RequestUri!.AbsolutePath);
Assert.Equal("QQBot", Assert.Single(handler.Requests).Headers.Authorization!.Scheme);
await api.GetGatewayAsync();
Assert.Single(handler.Requests);
}
[Fact]
public async Task GatewayApiClient_ConfiguredUrlSkipsRestCall()
{
StubHttpHandler handler = new(_ => new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(GatewayJson, Encoding.UTF8, "application/json")
});
GatewayApiClient api = CreateApiClient(handler, new QQBotOptions
{
Enabled = true, AppId = "1", Secret = "s", GatewayUrl = "wss://custom.example/ws"
});
GatewayInfo info = await api.GetGatewayAsync();
Assert.Equal("wss://custom.example/ws", info.Url);
Assert.Empty(handler.Requests);
}
[Fact]
public async Task SessionStore_RoundTripsAndClears()
{
using SqliteConnection connection = new("Data Source=:memory:");
await connection.OpenAsync();
ServiceCollection services = new();
services.AddDbContext<BotDbContext>(options => options.UseSqlite(connection));
await using ServiceProvider provider = services.BuildServiceProvider();
using (IServiceScope scope = provider.CreateScope())
{
await scope.ServiceProvider.GetRequiredService<BotDbContext>().Database.EnsureCreatedAsync();
}
GatewaySessionStore store = new(provider.GetRequiredService<IServiceScopeFactory>());
Assert.Null(await store.LoadAsync("APP1"));
await store.SaveAsync("APP1", "session-1", 42);
GatewaySessionState? loaded = await store.LoadAsync("APP1");
Assert.Equal("session-1", loaded!.SessionId);
Assert.Equal(42, loaded.LastSeq);
await store.SaveAsync("APP1", "session-1", 99);
Assert.Equal(99, (await store.LoadAsync("APP1"))!.LastSeq);
await store.ClearAsync("APP1");
Assert.Null(await store.LoadAsync("APP1"));
}
[Fact]
public void Status_TracksConnectionLifecycle()
{
GatewayStatus status = new();
Assert.False(status.Snapshot.Connected);
status.MarkConnected("session-1");
status.MarkSeq(7);
Assert.True(status.Snapshot.Connected);
Assert.Equal("session-1", status.Snapshot.SessionId);
Assert.Equal(7, status.Snapshot.LastSeq);
Assert.NotNull(status.Snapshot.ConnectedAtUtc);
status.MarkDisconnected("closed");
Assert.False(status.Snapshot.Connected);
Assert.Equal("closed", status.Snapshot.LastError);
}
[Fact]
public async Task GatewayClient_StaysIdleWhenBotIsDisabled()
{
StubHttpHandler handler = new(_ => new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(GatewayJson, Encoding.UTF8, "application/json")
});
GatewayApiClient api = CreateApiClient(handler, new QQBotOptions { Enabled = false });
QQBotGatewayClient client = new(
Options.Create(new QQBotOptions { Enabled = false, Mode = QQBotMode.WebSocket }),
api, new StubQQBotService(), new NoopDispatcher(), new InMemorySessionStore(),
new GatewayStatus(), NullLogger<QQBotGatewayClient>.Instance);
await client.StartAsync(CancellationToken.None);
await client.StopAsync(CancellationToken.None);
Assert.Empty(handler.Requests);
}
private static GatewayApiClient CreateApiClient(StubHttpHandler handler, QQBotOptions options)
=> new(new StubHttpClientFactory(handler), new StubQQBotService(), Options.Create(options),
NullLogger<GatewayApiClient>.Instance);
private sealed class StubHttpHandler(Func<HttpRequestMessage, HttpResponseMessage> respond) : HttpMessageHandler
{
public List<HttpRequestMessage> Requests { get; } = [];
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
Requests.Add(request);
return Task.FromResult(respond(request));
}
}
private sealed class StubHttpClientFactory(HttpMessageHandler handler) : IHttpClientFactory
{
public HttpClient CreateClient(string name) => new(handler, disposeHandler: false);
}
private sealed class StubQQBotService : IQQBotService
{
public Task SendC2CMessageAsync(string openid, string content, int msgType = 0, object? media = null, string? msgId = null, int? msgSeq = null, CancellationToken cancellationToken = default, string? eventId = null) => Task.CompletedTask;
public Task SendGroupMessageAsync(string groupOpenid, string content, int msgType = 0, object? media = null, string? msgId = null, int? msgSeq = null, CancellationToken cancellationToken = default, string? eventId = null) => Task.CompletedTask;
public Task SendC2CMarkdownAsync(string openid, MarkdownMessage markdown, KeyboardMessage? keyboard = null, string? msgId = null, int? msgSeq = null, CancellationToken cancellationToken = default, string? eventId = null) => Task.CompletedTask;
public Task SendGroupMarkdownAsync(string groupOpenid, MarkdownMessage markdown, KeyboardMessage? keyboard = null, string? msgId = null, int? msgSeq = null, CancellationToken cancellationToken = default, string? eventId = null) => Task.CompletedTask;
public Task<UploadMediaResult> UploadC2CMediaAsync(string openid, int fileType, string url, CancellationToken cancellationToken = default) => Task.FromResult(new UploadMediaResult());
public Task<UploadMediaResult> UploadGroupMediaAsync(string groupOpenid, int fileType, string url, CancellationToken cancellationToken = default) => Task.FromResult(new UploadMediaResult());
public Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default) => Task.FromResult("ACCESS");
public Task<string> RefreshTokenAsync(CancellationToken cancellationToken = default) => Task.FromResult("ACCESS");
public Task<bool> AckInteractionAsync(string interactionId, int code = 0, CancellationToken cancellationToken = default) => Task.FromResult(true);
}
private sealed class NoopDispatcher : IQQEventDispatcher
{
public Task<EventDispatchResult> DispatchAsync(Payload payload, QQEventSource source, CancellationToken cancellationToken = default)
=> Task.FromResult(EventDispatchResult.Accepted());
}
private sealed class InMemorySessionStore : IGatewaySessionStore
{
private GatewaySessionState? _state;
public Task<GatewaySessionState?> LoadAsync(string appId, CancellationToken cancellationToken = default) => Task.FromResult(_state);
public Task SaveAsync(string appId, string sessionId, long lastSeq, CancellationToken cancellationToken = default)
{
_state = new GatewaySessionState(sessionId, lastSeq);
return Task.CompletedTask;
}
public Task ClearAsync(string appId, CancellationToken cancellationToken = default)
{
_state = null;
return Task.CompletedTask;
}
}
}
+9
View File
@@ -47,6 +47,15 @@ namespace OshimaBot.Models
/// <summary>心跳周期由 op 10 Hello 下发,此处仅作为网关请求超时兜底。</summary>
public int GatewayRequestTimeoutSeconds { get; set; } = 15;
/// <summary>留空时通过 GET /gateway/bot 自动获取;可用于沙箱代理或显式指定网关。</summary>
public string GatewayUrl { get; set; } = "";
/// <summary>单连接起步,分片编号固定 0;分片总数取自 /gateway/bot 的 shards。</summary>
public int ShardId { get; set; }
/// <summary>断线重连的指数退避上限(秒)。</summary>
public int GatewayMaxReconnectDelaySeconds { get; set; } = 30;
public string ResolvedApiBaseAddress => string.IsNullOrWhiteSpace(ApiBaseAddress)
? Environment == QQBotEnvironment.Sandbox
? "https://sandbox.api.sgroup.qq.com"
+27 -7
View File
@@ -7,6 +7,7 @@ using OshimaBot.Messaging;
using OshimaBot.Models;
using OshimaBot.Security;
using OshimaBot.Services;
using OshimaBot.Services.Gateway;
FunGameRuntime.EnsureInitialized();
@@ -24,6 +25,8 @@ builder.Services.AddOptions<QQBotOptions>()
.Validate(options => options.Intents > 0, "QQBot Intents 必须大于 0。")
.Validate(options => options.SignatureMaxAgeSeconds is > 0 and <= 3600, "回调签名时间戳窗口必须在 1 到 3600 秒之间。")
.Validate(options => !options.EnableWebhook || !string.IsNullOrWhiteSpace(options.Secret), "启用 Webhook 回调时必须配置 Secret 用于验签。")
.Validate(options => options.ShardId >= 0, "QQBot ShardId 不能为负数。")
.Validate(options => options.GatewayMaxReconnectDelaySeconds is > 0 and <= 600, "网关重连退避上限必须在 1 到 600 秒之间。")
.ValidateOnStart();
builder.Services.AddOptions<ServerOptions>()
.Bind(builder.Configuration.GetSection(ServerOptions.SectionName))
@@ -64,8 +67,12 @@ builder.Services.AddSingleton<IBotMessageSink>(sp => sp.GetRequiredService<BotMe
builder.Services.AddSingleton<IEventDeduplicationStore, EventDeduplicationStore>();
builder.Services.AddSingleton<IInteractionAckService, InteractionAckService>();
builder.Services.AddSingleton<IQQEventDispatcher, QQEventDispatcher>();
builder.Services.AddSingleton<IGatewayApiClient, GatewayApiClient>();
builder.Services.AddSingleton<IGatewaySessionStore, GatewaySessionStore>();
builder.Services.AddSingleton<IGatewayStatus, GatewayStatus>();
builder.Services.AddHostedService<ProcessedEventCleanupService>();
builder.Services.AddHostedService<BotMessageBackgroundService>();
builder.Services.AddHostedService<QQBotGatewayClient>();
WebApplication app = builder.Build();
@@ -80,6 +87,7 @@ if (app.Environment.IsDevelopment())
}
QQBotOptions botOptions = app.Services.GetRequiredService<IOptions<QQBotOptions>>().Value;
IGatewayStatus gatewayStatus = app.Services.GetRequiredService<IGatewayStatus>();
app.Logger.LogInformation(
"OshimaBot 启动:Mode={Mode}, Environment={Environment}, Webhook={WebhookEnabled}, Intents={Intents}",
botOptions.Mode, botOptions.Environment, botOptions.EnableWebhook, botOptions.Intents);
@@ -95,14 +103,26 @@ app.MapGet("/", () => Results.Ok(new
items = FunGameService.AllItems.Count
}));
app.MapGet("/health", () => Results.Ok(new
app.MapGet("/health", () =>
{
status = "ok",
mode = botOptions.Mode.ToString(),
environment = botOptions.Environment.ToString(),
webhookEnabled = botOptions.EnableWebhook,
startedAt = FunGameRuntime.StartedAt
}));
GatewayStatusSnapshot gateway = gatewayStatus.Snapshot;
return Results.Ok(new
{
status = "ok",
mode = botOptions.Mode.ToString(),
environment = botOptions.Environment.ToString(),
webhookEnabled = botOptions.EnableWebhook,
gateway = new
{
connected = gateway.Connected,
sessionId = gateway.SessionId,
lastSeq = gateway.LastSeq,
connectedAtUtc = gateway.ConnectedAtUtc,
lastError = gateway.LastError
},
startedAt = FunGameRuntime.StartedAt
});
});
app.MapControllers();
@@ -0,0 +1,61 @@
using System.Net.Http.Headers;
using System.Text.Json;
using Microsoft.Extensions.Options;
using OshimaBot.Models;
namespace OshimaBot.Services.Gateway;
public interface IGatewayApiClient
{
Task<GatewayInfo> GetGatewayAsync(CancellationToken cancellationToken = default);
}
/// <summary>GET /gateway/bot 获取 WSS 地址与建议分片数;结果缓存,避免每次重连都消耗接口配额。</summary>
public sealed class GatewayApiClient(
IHttpClientFactory httpClientFactory,
IQQBotService qqBot,
IOptions<QQBotOptions> options,
ILogger<GatewayApiClient> logger) : IGatewayApiClient
{
private readonly QQBotOptions _options = options.Value;
private GatewayInfo? _cached;
public async Task<GatewayInfo> GetGatewayAsync(CancellationToken cancellationToken = default)
{
// 允许显式指定网关地址(沙箱调试、内网代理),此时不发 REST 请求。
if (!string.IsNullOrWhiteSpace(_options.GatewayUrl))
{
return new GatewayInfo(_options.GatewayUrl.Trim(), 1, 1, int.MaxValue);
}
if (_cached is not null) return _cached;
string token = await qqBot.GetAccessTokenAsync(cancellationToken);
using HttpRequestMessage request = new(HttpMethod.Get, $"{_options.ResolvedApiBaseAddress}/gateway/bot");
request.Headers.Authorization = new AuthenticationHeaderValue("QQBot", token);
using HttpResponseMessage response = await httpClientFactory
.CreateClient(QQBotService.HttpClientName).SendAsync(request, cancellationToken);
string body = await response.Content.ReadAsStringAsync(cancellationToken);
if (!response.IsSuccessStatusCode)
{
throw new HttpRequestException($"获取 QQ 网关地址失败:HTTP {(int)response.StatusCode},{body}");
}
using JsonDocument document = JsonDocument.Parse(body);
JsonElement root = document.RootElement;
string url = root.GetProperty("url").GetString() ?? "";
if (string.IsNullOrWhiteSpace(url)) throw new InvalidOperationException("QQ 网关响应缺少 url。");
int shards = Math.Max(1, root.TryGetProperty("shards", out JsonElement s) ? s.GetInt32() : 1);
int maxConcurrency = 1;
int remaining = int.MaxValue;
if (root.TryGetProperty("session_start_limit", out JsonElement limit))
{
if (limit.TryGetProperty("max_concurrency", out JsonElement mc)) maxConcurrency = Math.Max(1, mc.GetInt32());
if (limit.TryGetProperty("remaining", out JsonElement rem)) remaining = rem.GetInt32();
}
_cached = new GatewayInfo(url, shards, maxConcurrency, remaining);
logger.LogInformation("QQ WSS 网关:Url={Url}, Shards={Shards}, MaxConcurrency={MaxConcurrency}, Remaining={Remaining}",
url, shards, maxConcurrency, remaining);
return _cached;
}
}
@@ -0,0 +1,122 @@
using System.Text.Json;
namespace OshimaBot.Services.Gateway;
/// <summary>GET /gateway/bot 返回值中本项目需要的字段。</summary>
public sealed record GatewayInfo(string Url, int Shards, int MaxConcurrency, int Remaining);
/// <summary>持久化在 gateway_sessions 表中,供断线与进程重启后 Resume。</summary>
public sealed record GatewaySessionState(string SessionId, long LastSeq);
public enum GatewayCloseAction
{
/// <summary>用 session_id + seq 恢复。</summary>
Resume,
/// <summary>清 session,重新 Identify。</summary>
Identify,
/// <summary>凭据失效,刷新 AccessToken 后 Identify。</summary>
RefreshToken,
/// <summary>配置/权限错误,停止重连以免被官方限流。</summary>
Stop
}
public enum GatewayConnectionOutcome
{
Resume,
Identify,
RefreshToken,
Stop
}
/// <summary>QQ 官方 WebSocket 协议编解码与错误码策略(纯函数,便于单测)。</summary>
public static class GatewayProtocol
{
public const int OpDispatch = 0;
public const int OpHeartbeat = 1;
public const int OpIdentify = 2;
public const int OpResume = 6;
public const int OpReconnect = 7;
public const int OpInvalidSession = 9;
public const int OpHello = 10;
public const int OpHeartbeatAck = 11;
public const int DefaultHeartbeatIntervalMs = 45_000;
private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
/// <summary>token 格式官方要求 "QQBot {AccessToken}",intents 用位掩码,单分片 [0,1]。</summary>
public static string BuildIdentify(string accessToken, int intents, int shardId = 0, int shardCount = 1)
=> JsonSerializer.Serialize(new Dictionary<string, object?>
{
["op"] = OpIdentify,
["d"] = new Dictionary<string, object?>
{
["token"] = $"QQBot {accessToken}",
["intents"] = intents,
["shard"] = new[] { shardId, Math.Max(1, shardCount) },
["properties"] = new Dictionary<string, string>
{
["$os"] = "windows",
["$browser"] = "OshimaBot",
["$device"] = "OshimaBot"
}
}
}, JsonOptions);
public static string BuildResume(string accessToken, string sessionId, long seq)
=> JsonSerializer.Serialize(new Dictionary<string, object?>
{
["op"] = OpResume,
["d"] = new Dictionary<string, object?>
{
["token"] = $"QQBot {accessToken}",
["session_id"] = sessionId,
["seq"] = seq
}
}, JsonOptions);
/// <summary>首次连接 d 必须为 null,之后携带最新收到的 s。</summary>
public static string BuildHeartbeat(long? lastSeq)
=> JsonSerializer.Serialize(new Dictionary<string, object?>
{
["op"] = OpHeartbeat,
["d"] = lastSeq
}, JsonOptions);
public static int ParseHeartbeatInterval(JsonElement data)
{
if (data.ValueKind == JsonValueKind.Object
&& data.TryGetProperty("heartbeat_interval", out JsonElement interval)
&& interval.ValueKind == JsonValueKind.Number
&& interval.TryGetInt32(out int ms)
&& ms > 0)
{
return Math.Max(1_000, ms);
}
return DefaultHeartbeatIntervalMs;
}
public static string? ParseSessionId(JsonElement data)
=> data.ValueKind == JsonValueKind.Object
&& data.TryGetProperty("session_id", out JsonElement id)
&& id.ValueKind == JsonValueKind.String
? id.GetString()
: null;
/// <summary>
/// 官方 websocket.html 错误码表:
/// 4009/4008 可 RESUME;4006/4007/4900~4913 需重新 IDENTIFY;
/// 4001/4002/4010~4014/4914/4915 属于不可重试的配置或权限错误。
/// </summary>
public static GatewayCloseAction DecideCloseAction(int? closeCode) => closeCode switch
{
null or 1000 or 1001 => GatewayCloseAction.Resume,
4009 or 4008 => GatewayCloseAction.Resume,
4004 => GatewayCloseAction.RefreshToken,
4001 or 4002 or 4010 or 4011 or 4012 or 4013 or 4014 or 4914 or 4915 => GatewayCloseAction.Stop,
_ => GatewayCloseAction.Identify
};
}
@@ -0,0 +1,103 @@
using Microsoft.EntityFrameworkCore;
using OshimaBot.Data;
using OshimaBot.Data.Entities;
namespace OshimaBot.Services.Gateway;
public interface IGatewaySessionStore
{
Task<GatewaySessionState?> LoadAsync(string appId, CancellationToken cancellationToken = default);
Task SaveAsync(string appId, string sessionId, long lastSeq, CancellationToken cancellationToken = default);
Task ClearAsync(string appId, CancellationToken cancellationToken = default);
}
/// <summary>session_id / last_seq 落库,进程重启后仍可尝试 Resume(超时则回落 Identify)。</summary>
public sealed class GatewaySessionStore(IServiceScopeFactory scopeFactory) : IGatewaySessionStore
{
public async Task<GatewaySessionState?> LoadAsync(string appId, CancellationToken cancellationToken = default)
{
using IServiceScope scope = scopeFactory.CreateScope();
BotDbContext db = scope.ServiceProvider.GetRequiredService<BotDbContext>();
GatewaySession? row = await db.GatewaySessions.AsNoTracking()
.FirstOrDefaultAsync(x => x.BotAppId == appId, cancellationToken);
return row is null ? null : new GatewaySessionState(row.SessionId, row.LastSeq);
}
public async Task SaveAsync(string appId, string sessionId, long lastSeq, CancellationToken cancellationToken = default)
{
using IServiceScope scope = scopeFactory.CreateScope();
BotDbContext db = scope.ServiceProvider.GetRequiredService<BotDbContext>();
GatewaySession? row = await db.GatewaySessions.FirstOrDefaultAsync(x => x.BotAppId == appId, cancellationToken);
if (row is null)
{
db.GatewaySessions.Add(new GatewaySession
{
BotAppId = appId,
SessionId = sessionId,
LastSeq = lastSeq,
UpdatedAtUtc = DateTime.UtcNow
});
}
else
{
row.SessionId = sessionId;
row.LastSeq = lastSeq;
row.UpdatedAtUtc = DateTime.UtcNow;
}
await db.SaveChangesAsync(cancellationToken);
}
public async Task ClearAsync(string appId, CancellationToken cancellationToken = default)
{
using IServiceScope scope = scopeFactory.CreateScope();
BotDbContext db = scope.ServiceProvider.GetRequiredService<BotDbContext>();
await db.GatewaySessions.Where(x => x.BotAppId == appId).ExecuteDeleteAsync(cancellationToken);
}
}
public sealed record GatewayStatusSnapshot(
bool Connected, string? SessionId, long LastSeq, DateTime? ConnectedAtUtc, string? LastError);
public interface IGatewayStatus
{
GatewayStatusSnapshot Snapshot { get; }
void MarkConnected(string sessionId);
void MarkSeq(long seq);
void MarkDisconnected(string? error = null);
}
/// <summary>供 /health 观测的连接状态(进程内快照)。</summary>
public sealed class GatewayStatus : IGatewayStatus
{
private readonly object _lock = new();
private GatewayStatusSnapshot _snapshot = new(false, null, 0, null, null);
public GatewayStatusSnapshot Snapshot
{
get { lock (_lock) return _snapshot; }
}
public void MarkConnected(string sessionId)
{
lock (_lock)
{
_snapshot = _snapshot with
{
Connected = true,
SessionId = sessionId,
ConnectedAtUtc = DateTime.UtcNow,
LastError = null
};
}
}
public void MarkSeq(long seq)
{
lock (_lock) _snapshot = _snapshot with { LastSeq = seq };
}
public void MarkDisconnected(string? error = null)
{
lock (_lock) _snapshot = _snapshot with { Connected = false, LastError = error };
}
}
@@ -0,0 +1,327 @@
using System.Net.WebSockets;
using System.Text;
using System.Text.Json;
using Microsoft.Extensions.Options;
using OshimaBot.Models;
namespace OshimaBot.Services.Gateway;
/// <summary>
/// QQ 官方 WebSocket 单连接客户端(S4):GET /gateway/bot → Connect → Hello(10) → Identify(2)/Resume(6)
/// → READY → 心跳(1/11) → Dispatch(0) 统一投递 QQEventDispatcher。
/// 出站消息仍走 IQQBotService 的 REST;这里只负责接事件。
/// </summary>
public sealed class QQBotGatewayClient(
IOptions<QQBotOptions> options,
IGatewayApiClient gatewayApi,
IQQBotService qqBot,
IQQEventDispatcher dispatcher,
IGatewaySessionStore sessions,
IGatewayStatus status,
ILogger<QQBotGatewayClient> logger) : BackgroundService
{
private readonly QQBotOptions _options = options.Value;
private readonly SemaphoreSlim _sendLock = new(1, 1);
private long _lastSeq;
private string? _sessionId;
private bool _canResume;
private int _heartbeatIntervalMs = GatewayProtocol.DefaultHeartbeatIntervalMs;
private long _lastHeartbeatAckTicks = DateTime.UtcNow.Ticks;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
if (!_options.Enabled || _options.Mode != QQBotMode.WebSocket)
{
logger.LogInformation("QQ WebSocket 未启用(Enabled={Enabled}, Mode={Mode}),网关客户端不启动。",
_options.Enabled, _options.Mode);
return;
}
int failures = 0;
try
{
while (!stoppingToken.IsCancellationRequested)
{
GatewayConnectionOutcome outcome;
try
{
outcome = await RunConnectionAsync(stoppingToken);
failures = 0;
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
catch (Exception exception)
{
failures++;
status.MarkDisconnected(exception.Message);
logger.LogWarning(exception, "QQ WS 连接异常,第 {Failures} 次重连。", failures);
outcome = GatewayConnectionOutcome.Identify;
}
if (outcome == GatewayConnectionOutcome.Stop)
{
logger.LogError("QQ WS 遇到不可重试的网关错误(intents/权限/封禁),停止重连;请检查 QQBot 配置。");
break;
}
if (outcome == GatewayConnectionOutcome.RefreshToken)
{
await qqBot.RefreshTokenAsync(stoppingToken);
}
if (outcome is GatewayConnectionOutcome.Identify or GatewayConnectionOutcome.RefreshToken)
{
await InvalidateSessionAsync(stoppingToken);
}
TimeSpan delay = Backoff(failures);
logger.LogInformation("QQ WS 将在 {Delay} 后重连({Outcome})。", delay, outcome);
await Task.Delay(delay, stoppingToken);
}
}
finally
{
status.MarkDisconnected("网关客户端已停止");
}
}
private async Task<GatewayConnectionOutcome> RunConnectionAsync(CancellationToken cancellationToken)
{
GatewayInfo info = await gatewayApi.GetGatewayAsync(cancellationToken);
string token = await qqBot.GetAccessTokenAsync(cancellationToken);
if (_sessionId is null)
{
GatewaySessionState? persisted = await sessions.LoadAsync(_options.AppId, cancellationToken);
if (persisted is not null && !string.IsNullOrWhiteSpace(persisted.SessionId))
{
_sessionId = persisted.SessionId;
_lastSeq = Math.Max(_lastSeq, persisted.LastSeq);
_canResume = true;
logger.LogInformation("已从 gateway_sessions 恢复会话:SessionId={SessionId}, Seq={Seq}", _sessionId, _lastSeq);
}
}
using ClientWebSocket socket = new();
using CancellationTokenSource heartbeatCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
Task? heartbeatTask = null;
int? closeCode = null;
string? closeDescription = null;
GatewayConnectionOutcome? forcedOutcome = null;
Interlocked.Exchange(ref _lastHeartbeatAckTicks, DateTime.UtcNow.Ticks);
try
{
await socket.ConnectAsync(new Uri(info.Url), cancellationToken);
logger.LogInformation("QQ WS 已连接:{Url}", info.Url);
while (socket.State == WebSocketState.Open && !cancellationToken.IsCancellationRequested)
{
(string? raw, int? code, string? description) = await ReceiveAsync(socket, cancellationToken);
if (raw is null)
{
closeCode = code;
closeDescription = description;
break;
}
if (raw.Length == 0) continue;
using JsonDocument document = JsonDocument.Parse(raw);
JsonElement root = document.RootElement;
int op = root.TryGetProperty("op", out JsonElement opElement) && opElement.ValueKind == JsonValueKind.Number
? opElement.GetInt32()
: -1;
JsonElement data = root.TryGetProperty("d", out JsonElement dataElement) ? dataElement : default;
switch (op)
{
case GatewayProtocol.OpHello:
_heartbeatIntervalMs = GatewayProtocol.ParseHeartbeatInterval(data);
heartbeatTask ??= HeartbeatLoopAsync(socket, _heartbeatIntervalMs, heartbeatCts.Token);
if (_canResume && !string.IsNullOrWhiteSpace(_sessionId))
{
await SendRawAsync(socket, GatewayProtocol.BuildResume(token, _sessionId!, _lastSeq), cancellationToken);
logger.LogInformation("已发送 Resume:SessionId={SessionId}, Seq={Seq}", _sessionId, _lastSeq);
}
else
{
await SendRawAsync(socket, GatewayProtocol.BuildIdentify(token, _options.Intents,
_options.ShardId, Math.Max(1, info.Shards)), cancellationToken);
logger.LogInformation("已发送 Identify:Intents={Intents}, Shard=[{ShardId},{ShardCount}]",
_options.Intents, _options.ShardId, Math.Max(1, info.Shards));
}
break;
case GatewayProtocol.OpDispatch:
if (root.TryGetProperty("s", out JsonElement seqElement)
&& seqElement.ValueKind == JsonValueKind.Number
&& seqElement.TryGetInt64(out long seq))
{
_lastSeq = seq;
status.MarkSeq(seq);
// 每 10 个 seq 落库一次:崩溃重启后 Resume 最多补发少量事件,
// 配合 processed_events 去重可避免重复处理。
if (seq % 10 == 0 && !string.IsNullOrWhiteSpace(_sessionId))
{
await sessions.SaveAsync(_options.AppId, _sessionId!, seq, cancellationToken);
}
}
string eventType = root.TryGetProperty("t", out JsonElement typeElement)
? typeElement.GetString() ?? ""
: "";
if (eventType == "READY")
{
_sessionId = GatewayProtocol.ParseSessionId(data) ?? _sessionId;
_canResume = !string.IsNullOrWhiteSpace(_sessionId);
if (_sessionId is not null)
{
status.MarkConnected(_sessionId);
await sessions.SaveAsync(_options.AppId, _sessionId, _lastSeq, cancellationToken);
}
logger.LogInformation("QQ WS READY:SessionId={SessionId}", _sessionId);
}
else if (eventType == "RESUMED")
{
status.MarkConnected(_sessionId ?? "");
logger.LogInformation("QQ WS RESUMED:补发事件已完成。");
}
else if (!string.IsNullOrWhiteSpace(eventType))
{
Payload? payload = JsonSerializer.Deserialize<Payload>(raw);
if (payload is not null)
{
await dispatcher.DispatchAsync(payload, QQEventSource.WebSocket, cancellationToken);
}
}
break;
case GatewayProtocol.OpHeartbeat:
// 服务端要求立即回一次心跳。
await SendRawAsync(socket, GatewayProtocol.BuildHeartbeat(_lastSeq > 0 ? _lastSeq : null), cancellationToken);
break;
case GatewayProtocol.OpHeartbeatAck:
Interlocked.Exchange(ref _lastHeartbeatAckTicks, DateTime.UtcNow.Ticks);
break;
case GatewayProtocol.OpReconnect:
forcedOutcome = GatewayConnectionOutcome.Resume;
logger.LogInformation("收到 op=7 Reconnect,准备重连并尝试 Resume。");
await CloseSocketAsync(socket, cancellationToken);
break;
case GatewayProtocol.OpInvalidSession:
logger.LogWarning("收到 op=9 Invalid Session,清除会话并重新 Identify。");
await InvalidateSessionAsync(cancellationToken);
await SendRawAsync(socket, GatewayProtocol.BuildIdentify(token, _options.Intents,
_options.ShardId, Math.Max(1, info.Shards)), cancellationToken);
break;
default:
logger.LogDebug("忽略未处理的 QQ WS opcode:{Op}", op);
break;
}
}
}
finally
{
heartbeatCts.Cancel();
if (heartbeatTask is not null)
{
try { await heartbeatTask; }
catch (OperationCanceledException) { }
catch (Exception exception) { logger.LogDebug(exception, "心跳任务结束。"); }
}
status.MarkDisconnected(closeDescription ?? $"连接关闭(code={closeCode?.ToString() ?? "n/a"})");
await CloseSocketAsync(socket, CancellationToken.None);
}
if (forcedOutcome is not null) return forcedOutcome.Value;
return GatewayProtocol.DecideCloseAction(closeCode) switch
{
GatewayCloseAction.Resume => GatewayConnectionOutcome.Resume,
GatewayCloseAction.RefreshToken => GatewayConnectionOutcome.RefreshToken,
GatewayCloseAction.Stop => GatewayConnectionOutcome.Stop,
_ => GatewayConnectionOutcome.Identify
};
}
private async Task HeartbeatLoopAsync(ClientWebSocket socket, int intervalMs, CancellationToken cancellationToken)
{
using PeriodicTimer timer = new(TimeSpan.FromMilliseconds(intervalMs));
while (await timer.WaitForNextTickAsync(cancellationToken))
{
long ackTicks = Interlocked.Read(ref _lastHeartbeatAckTicks);
if (DateTime.UtcNow.Ticks - ackTicks > TimeSpan.FromMilliseconds(intervalMs * 2.5).Ticks)
{
logger.LogWarning("QQ WS 心跳 ACK 超时,判定连接僵死并主动重连。");
socket.Abort();
return;
}
await SendRawAsync(socket, GatewayProtocol.BuildHeartbeat(_lastSeq > 0 ? _lastSeq : null), cancellationToken);
}
}
private async Task InvalidateSessionAsync(CancellationToken cancellationToken)
{
_canResume = false;
_sessionId = null;
await sessions.ClearAsync(_options.AppId, cancellationToken);
}
private async Task SendRawAsync(ClientWebSocket socket, string payload, CancellationToken cancellationToken)
{
await _sendLock.WaitAsync(cancellationToken);
try
{
byte[] bytes = Encoding.UTF8.GetBytes(payload);
await socket.SendAsync(new ArraySegment<byte>(bytes), WebSocketMessageType.Text, true, cancellationToken);
}
finally
{
_sendLock.Release();
}
}
private static async Task<(string? Raw, int? CloseCode, string? Description)> ReceiveAsync(
ClientWebSocket socket, CancellationToken cancellationToken)
{
byte[] buffer = new byte[16 * 1024];
using MemoryStream stream = new();
while (true)
{
WebSocketReceiveResult result = await socket.ReceiveAsync(new ArraySegment<byte>(buffer), cancellationToken);
if (result.MessageType == WebSocketMessageType.Close)
{
return (null, (int?)result.CloseStatus, result.CloseStatusDescription);
}
stream.Write(buffer, 0, result.Count);
if (!result.EndOfMessage) continue;
return result.MessageType == WebSocketMessageType.Text
? (Encoding.UTF8.GetString(stream.ToArray()), null, null)
: ("", null, null);
}
}
private static async Task CloseSocketAsync(ClientWebSocket socket, CancellationToken cancellationToken)
{
if (socket.State != WebSocketState.Open) return;
try
{
await socket.CloseAsync(WebSocketCloseStatus.NormalClosure, "shutdown", cancellationToken);
}
catch (Exception)
{
// 断线或对端已关闭时无需再握手。
}
}
private TimeSpan Backoff(int failures)
{
int maxSeconds = Math.Max(1, _options.GatewayMaxReconnectDelaySeconds);
double seconds = Math.Min(maxSeconds, Math.Pow(2, Math.Min(failures, 10)));
return TimeSpan.FromMilliseconds(seconds * 1000 + Random.Shared.Next(0, 750));
}
}
+4 -1
View File
@@ -18,7 +18,10 @@
"RequestTimeoutSeconds": 30,
"Intents": 100663296,
"SignatureMaxAgeSeconds": 300,
"GatewayRequestTimeoutSeconds": 15
"GatewayRequestTimeoutSeconds": 15,
"GatewayUrl": "",
"ShardId": 0,
"GatewayMaxReconnectDelaySeconds": 30
},
"Database": {
"ConnectionString": "Data Source=oshimobot.db;Default Timeout=30",