@gakr-gakr/qqbot 0.1.0

package/src/engine/api/retry.ts

@@ -0,0 +1,217 @@
+/**
+ * Generic retry engine for QQ Bot API requests.
+ *
+ * Replaces the three separate retry implementations in the old `api.ts`:
+ * - `apiRequestWithRetry` (upload retry with exponential backoff)
+ * - `partFinishWithRetry` (part-finish retry + persistent retry on specific biz codes)
+ * - `completeUploadWithRetry` (unconditional retry for complete-upload)
+ *
+ * All three patterns are expressed as a single `withRetry` function
+ * parameterized by `RetryPolicy` and optional `PersistentRetryPolicy`.
+ */
+
+import type { EngineLogger } from "../types.js";
+import { formatErrorMessage } from "../utils/format.js";
+
+/** Standard retry policy with exponential or fixed backoff. */
+interface RetryPolicy {
+  /** Maximum retry attempts (excluding the initial attempt). */
+  maxRetries: number;
+  /** Base delay in milliseconds. */
+  baseDelayMs: number;
+  /** Backoff strategy. */
+  backoff: "exponential" | "fixed";
+  /**
+   * Predicate to decide whether an error is retryable.
+   * Return `false` to immediately rethrow.
+   * Defaults to always-retry when omitted.
+   */
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+
+/**
+ * Persistent retry policy for specific business error codes.
+ *
+ * When `shouldPersistRetry` returns true, the engine switches from
+ * the standard retry loop into a tight fixed-interval loop bounded
+ * only by the total timeout.
+ */
+interface PersistentRetryPolicy {
+  /** Total timeout in milliseconds for the persistent retry loop. */
+  timeoutMs: number;
+  /** Fixed interval between retries in milliseconds. */
+  intervalMs: number;
+  /** Predicate to decide whether an error triggers persistent retry. */
+  shouldPersistRetry: (error: Error) => boolean;
+}
+
+/**
+ * Execute an async operation with configurable retry semantics.
+ *
+ * @param fn - The async operation to retry.
+ * @param policy - Standard retry configuration.
+ * @param persistentPolicy - Optional persistent retry for specific error codes.
+ * @param logger - Optional logger for retry diagnostics.
+ * @returns The result of the first successful invocation.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  policy: RetryPolicy,
+  persistentPolicy?: PersistentRetryPolicy,
+  logger?: EngineLogger,
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(formatErrorMessage(err));
+
+      // Check for persistent-retry trigger before standard retry logic.
+      if (persistentPolicy?.shouldPersistRetry(lastError)) {
+        (logger?.warn ?? logger?.error)?.(
+          `[qqbot:retry] Hit persistent-retry trigger, entering persistent loop (timeout=${persistentPolicy.timeoutMs / 1000}s)`,
+        );
+        return await persistentRetryLoop(fn, persistentPolicy, logger);
+      }
+
+      // Check whether this error is retryable under the standard policy.
+      if (policy.shouldRetry?.(lastError, attempt) === false) {
+        throw lastError;
+      }
+
+      // Schedule the next retry with the configured backoff.
+      if (attempt < policy.maxRetries) {
+        const delay =
+          policy.backoff === "exponential" ? policy.baseDelayMs * 2 ** attempt : policy.baseDelayMs;
+
+        logger?.debug?.(
+          `[qqbot:retry] Attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 100)}`,
+        );
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
+/**
+ * Persistent retry loop: fixed-interval retries bounded by a total timeout.
+ *
+ * Used for `upload_part_finish` when the server returns specific business
+ * error codes indicating the backend is still processing.
+ */
+async function persistentRetryLoop<T>(
+  fn: () => Promise<T>,
+  policy: PersistentRetryPolicy,
+  logger?: EngineLogger,
+): Promise<T> {
+  const deadline = Date.now() + policy.timeoutMs;
+  let attempt = 0;
+  let lastError: Error | null = null;
+
+  while (Date.now() < deadline) {
+    try {
+      const result = await fn();
+      logger?.debug?.(`[qqbot:retry] Persistent retry succeeded after ${attempt} retries`);
+      return result;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(formatErrorMessage(err));
+
+      // If the error is no longer retryable, abort immediately.
+      if (!policy.shouldPersistRetry(lastError)) {
+        logger?.error?.(`[qqbot:retry] Persistent retry: error is no longer retryable, aborting`);
+        throw lastError;
+      }
+
+      attempt++;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        break;
+      }
+
+      const actualDelay = Math.min(policy.intervalMs, remaining);
+      (logger?.warn ?? logger?.error)?.(
+        `[qqbot:retry] Persistent retry #${attempt}: retrying in ${actualDelay}ms (remaining=${Math.round(remaining / 1000)}s)`,
+      );
+      await sleep(actualDelay);
+    }
+  }
+
+  logger?.error?.(
+    `[qqbot:retry] Persistent retry timed out after ${policy.timeoutMs / 1000}s (${attempt} attempts)`,
+  );
+  throw lastError ?? new Error(`Persistent retry timed out (${policy.timeoutMs / 1000}s)`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============ Pre-built Retry Policies ============
+
+/** Standard upload retry: exponential backoff, skip 400/401/timeout errors. */
+export const UPLOAD_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 2,
+  baseDelayMs: 1000,
+  backoff: "exponential",
+  shouldRetry: (error) => {
+    const msg = error.message;
+    return !(
+      msg.includes("400") ||
+      msg.includes("401") ||
+      msg.includes("Invalid") ||
+      msg.includes("timeout") ||
+      msg.includes("Timeout")
+    );
+  },
+};
+
+/** Complete-upload retry: unconditional retry with exponential backoff. */
+export const COMPLETE_UPLOAD_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 2,
+  baseDelayMs: 2000,
+  backoff: "exponential",
+  // Always retry — complete-upload failures are often transient server-side.
+};
+
+/** Part-finish standard retry policy. */
+export const PART_FINISH_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 2,
+  baseDelayMs: 1000,
+  backoff: "exponential",
+};
+
+/**
+ * Build a persistent retry policy for part-finish with a specific timeout.
+ *
+ * @param retryTimeoutMs - Total timeout (defaults to 2 minutes).
+ * @param retryableCodes - Business error codes that trigger persistent retry.
+ */
+export function buildPartFinishPersistentPolicy(
+  retryTimeoutMs?: number,
+  retryableCodes: Set<number> = PART_FINISH_RETRYABLE_CODES,
+): PersistentRetryPolicy {
+  return {
+    timeoutMs: retryTimeoutMs ?? 2 * 60 * 1000,
+    intervalMs: 1000,
+    shouldPersistRetry: (error) => {
+      if (retryableCodes.size === 0) {
+        return false;
+      }
+      // Check for ApiError with matching bizCode.
+      if ("bizCode" in error && typeof (error as { bizCode?: number }).bizCode === "number") {
+        return retryableCodes.has((error as { bizCode: number }).bizCode);
+      }
+      return false;
+    },
+  };
+}
+
+/** Business error codes that trigger persistent part-finish retry. */
+const PART_FINISH_RETRYABLE_CODES: Set<number> = new Set([40093001]);
+
+/** upload_prepare error code indicating daily limit exceeded. */
+export const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;

package/src/engine/api/routes.ts

@@ -0,0 +1,95 @@
+/**
+ * Centralized API route templates for the QQ Open Platform.
+ *
+ * Eliminates C2C/Group path duplication by parameterizing on `ChatScope`.
+ * Inspired by `bot-node-sdk/src/openapi/v1/resource.ts`.
+ */
+
+import type { ChatScope } from "../types.js";
+
+/**
+ * Build the message-send path for C2C or Group.
+ *
+ * - C2C:   `/v2/users/{id}/messages`
+ * - Group: `/v2/groups/{id}/messages`
+ */
+export function messagePath(scope: ChatScope, targetId: string): string {
+  return scope === "c2c" ? `/v2/users/${targetId}/messages` : `/v2/groups/${targetId}/messages`;
+}
+
+/** Channel message path. */
+export function channelMessagePath(channelId: string): string {
+  return `/channels/${channelId}/messages`;
+}
+
+/** DM (direct message inside a guild) path. */
+export function dmMessagePath(guildId: string): string {
+  return `/dms/${guildId}/messages`;
+}
+
+/**
+ * Build the media upload (small-file) path for C2C or Group.
+ *
+ * - C2C:   `/v2/users/{id}/files`
+ * - Group: `/v2/groups/{id}/files`
+ */
+export function mediaUploadPath(scope: ChatScope, targetId: string): string {
+  return scope === "c2c" ? `/v2/users/${targetId}/files` : `/v2/groups/${targetId}/files`;
+}
+
+/**
+ * Build the upload_prepare path for C2C or Group.
+ *
+ * - C2C:   `/v2/users/{id}/upload_prepare`
+ * - Group: `/v2/groups/{id}/upload_prepare`
+ */
+export function uploadPreparePath(scope: ChatScope, targetId: string): string {
+  return scope === "c2c"
+    ? `/v2/users/${targetId}/upload_prepare`
+    : `/v2/groups/${targetId}/upload_prepare`;
+}
+
+/**
+ * Build the upload_part_finish path for C2C or Group.
+ */
+export function uploadPartFinishPath(scope: ChatScope, targetId: string): string {
+  return scope === "c2c"
+    ? `/v2/users/${targetId}/upload_part_finish`
+    : `/v2/groups/${targetId}/upload_part_finish`;
+}
+
+/**
+ * Build the complete-upload (files) path for C2C or Group.
+ * (Same as mediaUploadPath — the complete endpoint reuses the files path.)
+ */
+export function uploadCompletePath(scope: ChatScope, targetId: string): string {
+  return mediaUploadPath(scope, targetId);
+}
+
+/** Stream message path (C2C only). */
+export function streamMessagePath(openid: string): string {
+  return `/v2/users/${openid}/stream_messages`;
+}
+
+/** Gateway URL path. */
+export function gatewayPath(): string {
+  return "/gateway";
+}
+
+/** Interaction acknowledgement path. */
+export function interactionPath(interactionId: string): string {
+  return `/interactions/${interactionId}`;
+}
+
+// ============ Shared Helpers ============
+
+/**
+ * Generate a message sequence number in the 0..65535 range.
+ *
+ * Used by both `messages.ts` and `media.ts` to avoid duplicate definitions.
+ */
+export function getNextMsgSeq(_msgId: string): number {
+  const timePart = Date.now() % 100_000_000;
+  const random = Math.floor(Math.random() * 65536);
+  return (timePart ^ random) % 65536;
+}

package/src/engine/api/token.ts

@@ -0,0 +1,277 @@
+/**
+ * Token management for the QQ Open Platform.
+ *
+ * All state (cache, singleflight promises, background refresh controllers)
+ * is encapsulated in the `TokenManager` class instance — no module-level
+ * globals, fully supporting multi-account concurrent operation.
+ */
+
+import type { EngineLogger } from "../types.js";
+import { formatErrorMessage } from "../utils/format.js";
+
+const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+
+interface CachedToken {
+  token: string;
+  expiresAt: number;
+  appId: string;
+}
+
+interface BackgroundRefreshOptions {
+  refreshAheadMs?: number;
+  randomOffsetMs?: number;
+  minRefreshIntervalMs?: number;
+  retryDelayMs?: number;
+}
+
+/**
+ * Per-appId token manager with caching, singleflight, and background refresh.
+ *
+ * Usage:
+ * ```ts
+ * const tm = new TokenManager({ logger, userAgent: 'QQBotPlugin/1.0' });
+ * const token = await tm.getAccessToken('appId', 'secret');
+ * ```
+ */
+export class TokenManager {
+  private readonly cache = new Map<string, CachedToken>();
+  private readonly fetchPromises = new Map<string, Promise<string>>();
+  private readonly refreshControllers = new Map<string, AbortController>();
+  private readonly logger?: EngineLogger;
+  private readonly resolveUserAgent: () => string;
+
+  constructor(config?: { logger?: EngineLogger; userAgent?: string | (() => string) }) {
+    this.logger = config?.logger;
+    const ua = config?.userAgent ?? "QQBotPlugin/unknown";
+    this.resolveUserAgent = typeof ua === "function" ? ua : () => ua;
+  }
+
+  /**
+   * Obtain an access token with caching and singleflight semantics.
+   *
+   * When multiple callers request a token for the same appId concurrently,
+   * only one actual HTTP request is made — the others await the same promise.
+   */
+  async getAccessToken(appId: string, clientSecret: string): Promise<string> {
+    const normalizedId = appId.trim();
+    const cached = this.cache.get(normalizedId);
+
+    // Refresh slightly before expiry without making short-lived tokens unusable.
+    const refreshAheadMs = cached
+      ? Math.min(5 * 60 * 1000, (cached.expiresAt - Date.now()) / 3)
+      : 0;
+
+    if (cached && Date.now() < cached.expiresAt - refreshAheadMs) {
+      return cached.token;
+    }
+
+    // Singleflight: reuse an in-progress fetch.
+    let pending = this.fetchPromises.get(normalizedId);
+    if (pending) {
+      this.logger?.debug?.(`[qqbot:token:${normalizedId}] Fetch in progress, reusing promise`);
+      return pending;
+    }
+
+    pending = (async () => {
+      try {
+        return await this.doFetchToken(normalizedId, clientSecret);
+      } finally {
+        this.fetchPromises.delete(normalizedId);
+      }
+    })();
+
+    this.fetchPromises.set(normalizedId, pending);
+    return pending;
+  }
+
+  /** Clear the cached token for one appId, or all. */
+  clearCache(appId?: string): void {
+    if (appId) {
+      this.cache.delete(appId.trim());
+      this.logger?.debug?.(`[qqbot:token:${appId}] Cache cleared`);
+    } else {
+      this.cache.clear();
+      this.logger?.debug?.(`[token] All caches cleared`);
+    }
+  }
+
+  /** Return token status for diagnostics. */
+  getStatus(appId: string): {
+    status: "valid" | "expired" | "refreshing" | "none";
+    expiresAt: number | null;
+  } {
+    if (this.fetchPromises.has(appId)) {
+      return { status: "refreshing", expiresAt: this.cache.get(appId)?.expiresAt ?? null };
+    }
+    const cached = this.cache.get(appId);
+    if (!cached) {
+      return { status: "none", expiresAt: null };
+    }
+    const remaining = cached.expiresAt - Date.now();
+    const isValid = remaining > Math.min(5 * 60 * 1000, remaining / 3);
+    return { status: isValid ? "valid" : "expired", expiresAt: cached.expiresAt };
+  }
+
+  /** Start a background token refresh loop for one appId. */
+  startBackgroundRefresh(
+    appId: string,
+    clientSecret: string,
+    options?: BackgroundRefreshOptions,
+  ): void {
+    if (this.refreshControllers.has(appId)) {
+      this.logger?.info?.(`[qqbot:token:${appId}] Background refresh already running`);
+      return;
+    }
+
+    const {
+      refreshAheadMs = 5 * 60 * 1000,
+      randomOffsetMs = 30 * 1000,
+      minRefreshIntervalMs = 60 * 1000,
+      retryDelayMs = 5 * 1000,
+    } = options ?? {};
+
+    const controller = new AbortController();
+    this.refreshControllers.set(appId, controller);
+    const { signal } = controller;
+
+    const loop = async () => {
+      this.logger?.info?.(`[qqbot:token:${appId}] Background refresh started`);
+
+      while (!signal.aborted) {
+        try {
+          await this.getAccessToken(appId, clientSecret);
+          const cached = this.cache.get(appId);
+
+          if (cached) {
+            const expiresIn = cached.expiresAt - Date.now();
+            const randomOffset = Math.random() * randomOffsetMs;
+            const refreshIn = Math.max(
+              expiresIn - refreshAheadMs - randomOffset,
+              minRefreshIntervalMs,
+            );
+            this.logger?.debug?.(
+              `[qqbot:token:${appId}] Next refresh in ${Math.round(refreshIn / 1000)}s`,
+            );
+            await this.abortableSleep(refreshIn, signal);
+          } else {
+            await this.abortableSleep(minRefreshIntervalMs, signal);
+          }
+        } catch (err) {
+          if (signal.aborted) {
+            break;
+          }
+          this.logger?.error?.(
+            `[qqbot:token:${appId}] Background refresh failed: ${formatErrorMessage(err)}`,
+          );
+          await this.abortableSleep(retryDelayMs, signal);
+        }
+      }
+
+      this.refreshControllers.delete(appId);
+      this.logger?.info?.(`[qqbot:token:${appId}] Background refresh stopped`);
+    };
+
+    loop().catch((err) => {
+      this.refreshControllers.delete(appId);
+      this.logger?.error?.(`[qqbot:token:${appId}] Background refresh crashed: ${err}`);
+    });
+  }
+
+  /** Stop background refresh for one appId, or all. */
+  stopBackgroundRefresh(appId?: string): void {
+    if (appId) {
+      const ctrl = this.refreshControllers.get(appId);
+      if (ctrl) {
+        ctrl.abort();
+        this.refreshControllers.delete(appId);
+      }
+    } else {
+      for (const ctrl of this.refreshControllers.values()) {
+        ctrl.abort();
+      }
+      this.refreshControllers.clear();
+    }
+  }
+
+  /** Check whether background refresh is running. */
+  isBackgroundRefreshRunning(appId?: string): boolean {
+    if (appId) {
+      return this.refreshControllers.has(appId);
+    }
+    return this.refreshControllers.size > 0;
+  }
+
+  // ---- Internal ----
+
+  private async doFetchToken(appId: string, clientSecret: string): Promise<string> {
+    this.logger?.debug?.(`[qqbot:token:${appId}] >>> POST ${TOKEN_URL}`);
+
+    let response: Response;
+    try {
+      response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": this.resolveUserAgent(),
+        },
+        body: JSON.stringify({ appId, clientSecret }),
+      });
+    } catch (err) {
+      this.logger?.error?.(`[qqbot:token:${appId}] Network error: ${formatErrorMessage(err)}`);
+      throw new Error(`Network error getting access_token: ${formatErrorMessage(err)}`, {
+        cause: err,
+      });
+    }
+
+    const traceId = response.headers.get("x-tps-trace-id") ?? "";
+    this.logger?.debug?.(
+      `[qqbot:token:${appId}] <<< ${response.status}${traceId ? ` | TraceId: ${traceId}` : ""}`,
+    );
+
+    let rawBody: string;
+    try {
+      rawBody = await response.text();
+    } catch (err) {
+      throw new Error(`Failed to read access_token response: ${formatErrorMessage(err)}`, {
+        cause: err,
+      });
+    }
+    const logBody = rawBody.replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token": "***"');
+    this.logger?.debug?.(`[qqbot:token:${appId}] <<< Body: ${logBody}`);
+
+    let data: { access_token?: string; expires_in?: number };
+    try {
+      data = JSON.parse(rawBody);
+    } catch {
+      throw new Error("QQBot access_token response was malformed JSON");
+    }
+
+    if (!data.access_token) {
+      throw new Error(`Failed to get access_token: ${JSON.stringify(data)}`);
+    }
+
+    const expiresAt = Date.now() + (data.expires_in ?? 7200) * 1000;
+    this.cache.set(appId, { token: data.access_token, expiresAt, appId });
+    this.logger?.debug?.(
+      `[qqbot:token:${appId}] Cached, expires at: ${new Date(expiresAt).toISOString()}`,
+    );
+
+    return data.access_token;
+  }
+
+  private abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(resolve, ms);
+      if (signal.aborted) {
+        clearTimeout(timer);
+        reject(new Error("Aborted"));
+        return;
+      }
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("Aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}