From 43ea1a9971a5a9bcec4cd5c5c1e84f0a28f106d3 Mon Sep 17 00:00:00 2001 From: milimoe Date: Mon, 9 Nov 2026 22:13:13 +0800 Subject: [PATCH] feat(S4): add QQ WebSocket gateway with identify, heartbeat, resume and session persistence --- OshimaBot.Tests/GatewayTests.cs | 262 ++++++++++++++ OshimaBot/Models/BotOptions.cs | 9 + OshimaBot/Program.cs | 34 +- .../Services/Gateway/GatewayApiClient.cs | 61 ++++ OshimaBot/Services/Gateway/GatewayProtocol.cs | 122 +++++++ .../Services/Gateway/GatewaySessionStore.cs | 103 ++++++ .../Services/Gateway/QQBotGatewayClient.cs | 327 ++++++++++++++++++ OshimaBot/appsettings.json | 5 +- 8 files changed, 915 insertions(+), 8 deletions(-) create mode 100644 OshimaBot.Tests/GatewayTests.cs create mode 100644 OshimaBot/Services/Gateway/GatewayApiClient.cs create mode 100644 OshimaBot/Services/Gateway/GatewayProtocol.cs create mode 100644 OshimaBot/Services/Gateway/GatewaySessionStore.cs create mode 100644 OshimaBot/Services/Gateway/QQBotGatewayClient.cs diff --git a/OshimaBot.Tests/GatewayTests.cs b/OshimaBot.Tests/GatewayTests.cs new file mode 100644 index 0000000..7f6c619 --- /dev/null +++ b/OshimaBot.Tests/GatewayTests.cs @@ -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(options => options.UseSqlite(connection)); + await using ServiceProvider provider = services.BuildServiceProvider(); + using (IServiceScope scope = provider.CreateScope()) + { + await scope.ServiceProvider.GetRequiredService().Database.EnsureCreatedAsync(); + } + + GatewaySessionStore store = new(provider.GetRequiredService()); + 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.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.Instance); + + private sealed class StubHttpHandler(Func respond) : HttpMessageHandler + { + public List Requests { get; } = []; + + protected override Task 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 UploadC2CMediaAsync(string openid, int fileType, string url, CancellationToken cancellationToken = default) => Task.FromResult(new UploadMediaResult()); + public Task UploadGroupMediaAsync(string groupOpenid, int fileType, string url, CancellationToken cancellationToken = default) => Task.FromResult(new UploadMediaResult()); + public Task GetAccessTokenAsync(CancellationToken cancellationToken = default) => Task.FromResult("ACCESS"); + public Task RefreshTokenAsync(CancellationToken cancellationToken = default) => Task.FromResult("ACCESS"); + public Task AckInteractionAsync(string interactionId, int code = 0, CancellationToken cancellationToken = default) => Task.FromResult(true); + } + + private sealed class NoopDispatcher : IQQEventDispatcher + { + public Task DispatchAsync(Payload payload, QQEventSource source, CancellationToken cancellationToken = default) + => Task.FromResult(EventDispatchResult.Accepted()); + } + + private sealed class InMemorySessionStore : IGatewaySessionStore + { + private GatewaySessionState? _state; + public Task 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; + } + } +} diff --git a/OshimaBot/Models/BotOptions.cs b/OshimaBot/Models/BotOptions.cs index 4406118..9931b28 100644 --- a/OshimaBot/Models/BotOptions.cs +++ b/OshimaBot/Models/BotOptions.cs @@ -47,6 +47,15 @@ namespace OshimaBot.Models /// 心跳周期由 op 10 Hello 下发,此处仅作为网关请求超时兜底。 public int GatewayRequestTimeoutSeconds { get; set; } = 15; + /// 留空时通过 GET /gateway/bot 自动获取;可用于沙箱代理或显式指定网关。 + public string GatewayUrl { get; set; } = ""; + + /// 单连接起步,分片编号固定 0;分片总数取自 /gateway/bot 的 shards。 + public int ShardId { get; set; } + + /// 断线重连的指数退避上限(秒)。 + public int GatewayMaxReconnectDelaySeconds { get; set; } = 30; + public string ResolvedApiBaseAddress => string.IsNullOrWhiteSpace(ApiBaseAddress) ? Environment == QQBotEnvironment.Sandbox ? "https://sandbox.api.sgroup.qq.com" diff --git a/OshimaBot/Program.cs b/OshimaBot/Program.cs index 2908880..9197385 100644 --- a/OshimaBot/Program.cs +++ b/OshimaBot/Program.cs @@ -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() .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() .Bind(builder.Configuration.GetSection(ServerOptions.SectionName)) @@ -64,8 +67,12 @@ builder.Services.AddSingleton(sp => sp.GetRequiredService(); builder.Services.AddSingleton(); builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); builder.Services.AddHostedService(); builder.Services.AddHostedService(); +builder.Services.AddHostedService(); WebApplication app = builder.Build(); @@ -80,6 +87,7 @@ if (app.Environment.IsDevelopment()) } QQBotOptions botOptions = app.Services.GetRequiredService>().Value; +IGatewayStatus gatewayStatus = app.Services.GetRequiredService(); 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(); diff --git a/OshimaBot/Services/Gateway/GatewayApiClient.cs b/OshimaBot/Services/Gateway/GatewayApiClient.cs new file mode 100644 index 0000000..9e18316 --- /dev/null +++ b/OshimaBot/Services/Gateway/GatewayApiClient.cs @@ -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 GetGatewayAsync(CancellationToken cancellationToken = default); +} + +/// GET /gateway/bot 获取 WSS 地址与建议分片数;结果缓存,避免每次重连都消耗接口配额。 +public sealed class GatewayApiClient( + IHttpClientFactory httpClientFactory, + IQQBotService qqBot, + IOptions options, + ILogger logger) : IGatewayApiClient +{ + private readonly QQBotOptions _options = options.Value; + private GatewayInfo? _cached; + + public async Task 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; + } +} diff --git a/OshimaBot/Services/Gateway/GatewayProtocol.cs b/OshimaBot/Services/Gateway/GatewayProtocol.cs new file mode 100644 index 0000000..45a2adc --- /dev/null +++ b/OshimaBot/Services/Gateway/GatewayProtocol.cs @@ -0,0 +1,122 @@ +using System.Text.Json; + +namespace OshimaBot.Services.Gateway; + +/// GET /gateway/bot 返回值中本项目需要的字段。 +public sealed record GatewayInfo(string Url, int Shards, int MaxConcurrency, int Remaining); + +/// 持久化在 gateway_sessions 表中,供断线与进程重启后 Resume。 +public sealed record GatewaySessionState(string SessionId, long LastSeq); + +public enum GatewayCloseAction +{ + /// 用 session_id + seq 恢复。 + Resume, + + /// 清 session,重新 Identify。 + Identify, + + /// 凭据失效,刷新 AccessToken 后 Identify。 + RefreshToken, + + /// 配置/权限错误,停止重连以免被官方限流。 + Stop +} + +public enum GatewayConnectionOutcome +{ + Resume, + Identify, + RefreshToken, + Stop +} + +/// QQ 官方 WebSocket 协议编解码与错误码策略(纯函数,便于单测)。 +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); + + /// token 格式官方要求 "QQBot {AccessToken}",intents 用位掩码,单分片 [0,1]。 + public static string BuildIdentify(string accessToken, int intents, int shardId = 0, int shardCount = 1) + => JsonSerializer.Serialize(new Dictionary + { + ["op"] = OpIdentify, + ["d"] = new Dictionary + { + ["token"] = $"QQBot {accessToken}", + ["intents"] = intents, + ["shard"] = new[] { shardId, Math.Max(1, shardCount) }, + ["properties"] = new Dictionary + { + ["$os"] = "windows", + ["$browser"] = "OshimaBot", + ["$device"] = "OshimaBot" + } + } + }, JsonOptions); + + public static string BuildResume(string accessToken, string sessionId, long seq) + => JsonSerializer.Serialize(new Dictionary + { + ["op"] = OpResume, + ["d"] = new Dictionary + { + ["token"] = $"QQBot {accessToken}", + ["session_id"] = sessionId, + ["seq"] = seq + } + }, JsonOptions); + + /// 首次连接 d 必须为 null,之后携带最新收到的 s。 + public static string BuildHeartbeat(long? lastSeq) + => JsonSerializer.Serialize(new Dictionary + { + ["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; + + /// + /// 官方 websocket.html 错误码表: + /// 4009/4008 可 RESUME;4006/4007/4900~4913 需重新 IDENTIFY; + /// 4001/4002/4010~4014/4914/4915 属于不可重试的配置或权限错误。 + /// + 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 + }; +} diff --git a/OshimaBot/Services/Gateway/GatewaySessionStore.cs b/OshimaBot/Services/Gateway/GatewaySessionStore.cs new file mode 100644 index 0000000..7f6e194 --- /dev/null +++ b/OshimaBot/Services/Gateway/GatewaySessionStore.cs @@ -0,0 +1,103 @@ +using Microsoft.EntityFrameworkCore; +using OshimaBot.Data; +using OshimaBot.Data.Entities; + +namespace OshimaBot.Services.Gateway; + +public interface IGatewaySessionStore +{ + Task LoadAsync(string appId, CancellationToken cancellationToken = default); + Task SaveAsync(string appId, string sessionId, long lastSeq, CancellationToken cancellationToken = default); + Task ClearAsync(string appId, CancellationToken cancellationToken = default); +} + +/// session_id / last_seq 落库,进程重启后仍可尝试 Resume(超时则回落 Identify)。 +public sealed class GatewaySessionStore(IServiceScopeFactory scopeFactory) : IGatewaySessionStore +{ + public async Task LoadAsync(string appId, CancellationToken cancellationToken = default) + { + using IServiceScope scope = scopeFactory.CreateScope(); + BotDbContext db = scope.ServiceProvider.GetRequiredService(); + 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(); + 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(); + 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); +} + +/// 供 /health 观测的连接状态(进程内快照)。 +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 }; + } +} diff --git a/OshimaBot/Services/Gateway/QQBotGatewayClient.cs b/OshimaBot/Services/Gateway/QQBotGatewayClient.cs new file mode 100644 index 0000000..b4ca913 --- /dev/null +++ b/OshimaBot/Services/Gateway/QQBotGatewayClient.cs @@ -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; + +/// +/// QQ 官方 WebSocket 单连接客户端(S4):GET /gateway/bot → Connect → Hello(10) → Identify(2)/Resume(6) +/// → READY → 心跳(1/11) → Dispatch(0) 统一投递 QQEventDispatcher。 +/// 出站消息仍走 IQQBotService 的 REST;这里只负责接事件。 +/// +public sealed class QQBotGatewayClient( + IOptions options, + IGatewayApiClient gatewayApi, + IQQBotService qqBot, + IQQEventDispatcher dispatcher, + IGatewaySessionStore sessions, + IGatewayStatus status, + ILogger 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 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(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(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(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)); + } +} diff --git a/OshimaBot/appsettings.json b/OshimaBot/appsettings.json index f15567a..3004d41 100644 --- a/OshimaBot/appsettings.json +++ b/OshimaBot/appsettings.json @@ -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",