@llblab/pi-telegram 0.21.1 → 0.22.0

package/lib/sync.ts

@@ -30,8 +30,7 @@ export interface TelegramLeaderThreadSyncDeps {
   getRandom?: () => number;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   getThreadReconciliationMachineState?: () =>
-    | ThreadReconciler.ThreadReconciliationMachineState
-    | undefined;
+    ThreadReconciler.ThreadReconciliationMachineState | undefined;
   recordThreadReconciliationPlan?: (
     plan: ThreadReconciler.ThreadReconciliationPlan,
   ) => void;
@@ -67,8 +66,7 @@ export interface TelegramTopicLifecycleSyncDeps {
   isTopicProvisioningActive?: () => boolean;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   getThreadReconciliationMachineState?: () =>
-    | ThreadReconciler.ThreadReconciliationMachineState
-    | undefined;
+    ThreadReconciler.ThreadReconciliationMachineState | undefined;
   recordThreadReconciliationPlan?: (
     plan: ThreadReconciler.ThreadReconciliationPlan,
   ) => void;
@@ -83,8 +81,9 @@ export type TelegramTopicLifecycleSyncHandler<TMessage = unknown> = (
   lifecycle: TelegramTopicLifecycleSyncUpdate<TMessage>,
 ) => Promise<void>;
 
-export interface TelegramObservedTopicLifecycleSyncDeps<TSyncState>
-  extends TelegramTopicLifecycleSyncDeps {
+export interface TelegramObservedTopicLifecycleSyncDeps<
+  TSyncState,
+> extends TelegramTopicLifecycleSyncDeps {
   getSyncState: () => TSyncState;
   setSyncState: (state: TSyncState) => void;
   getNowMs?: () => number;
@@ -122,6 +121,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
     body: Record<string, unknown>,
   ) => Promise<TResponse>;
   getLeaderTarget: () => TelegramTarget | undefined;
+  getCurrentLeaderEpoch?: () => number | string | undefined;
   clearLeaderTarget: () => void;
   getSyncState: () => TSyncState;
   setSyncState: (state: TSyncState) => void;
@@ -134,11 +134,9 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
   getNowMs?: () => number;
 }
 
-export function markTelegramConfigSyncChange<TSyncState extends TelegramSyncState>(
-  state: TSyncState,
-  action: string,
-  options?: { nowMs?: number },
-): TSyncState {
+export function markTelegramConfigSyncChange<
+  TSyncState extends TelegramSyncState,
+>(state: TSyncState, action: string, options?: { nowMs?: number }): TSyncState {
   const nowMs = options?.nowMs ?? Date.now();
   let nextState = markTelegramSyncSliceFresh(state, "pairing", {
     nowMs,
@@ -163,10 +161,18 @@ export function createTelegramManualThreadDisconnectHandler<
     if (currentRecord?.target.threadId) {
       const isManualFollower = currentRecord.owner?.kind === "manual-follower";
       if (!isManualFollower) {
+        const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+        const stillOwnsLeaderEpoch = () =>
+          !deps.getCurrentLeaderEpoch ||
+          (leaderEpoch !== undefined &&
+            deps.getCurrentLeaderEpoch() === leaderEpoch);
         await ThreadReconciler.applyThreadReconciliationPlan(
           ThreadReconciler.planDisconnectedInstanceThreadCleanup({
-            target: currentRecord.target as TelegramTarget & { threadId: number },
+            target: currentRecord.target as TelegramTarget & {
+              threadId: number;
+            },
             instanceId: deps.instanceId,
+            leaderEpoch,
           }),
           {
             callApi(method, body) {
@@ -175,11 +181,17 @@ export function createTelegramManualThreadDisconnectHandler<
             persist() {
               return deps.topicTargetStore.persist();
             },
+            getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
             recordRuntimeEvent: deps.recordRuntimeEvent,
           },
         );
-        if (deps.topicTargetStore.markOfflineByInstanceId(deps.instanceId) > 0) {
+        if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
+        const offlineChanged =
+          deps.topicTargetStore.markOfflineByInstanceId(deps.instanceId) > 0;
+        if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
+        if (offlineChanged) {
           await deps.topicTargetStore.persist();
+          if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
         }
       }
       const leaderTarget = deps.getLeaderTarget();
@@ -305,15 +317,27 @@ export async function recoverStaleTelegramTopicApiError<
 export async function ensureTelegramLeaderThreadBinding(
   deps: TelegramLeaderThreadSyncDeps,
 ): Promise<TelegramOwnTopicProvisionResult | undefined> {
-  await deps.topicTargetStore.load();
-  const priorTargets = deps.topicTargetStore
-    .list()
-    .filter((record) => {
-      return (
-        record.instanceId === deps.instanceId &&
-        (record.status === "active" || record.status === "starting")
+  const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+  const assertLeaderEpoch = (phase: string): void => {
+    if (
+      deps.getCurrentLeaderEpoch &&
+      (leaderEpoch === undefined ||
+        deps.getCurrentLeaderEpoch() !== leaderEpoch)
+    ) {
+      throw new Error(
+        `Telegram leader thread binding lost ownership (${phase}).`,
       );
-    });
+    }
+  };
+  assertLeaderEpoch("start");
+  await deps.topicTargetStore.load();
+  assertLeaderEpoch("after-load");
+  const priorTargets = deps.topicTargetStore.list().filter((record) => {
+    return (
+      record.instanceId === deps.instanceId &&
+      (record.status === "active" || record.status === "starting")
+    );
+  });
   // Short-circuit: when the instance already has an active thread and we are not
   // force-freshing, reuse it without re-provisioning. A thread belongs to the
   // live instance binding, not to one transient Pi session lifecycle.
@@ -330,6 +354,7 @@ export async function ensureTelegramLeaderThreadBinding(
         slot: record.slot,
       },
     );
+    assertLeaderEpoch("before-reuse");
     return {
       target: record.target,
       slot: record.slot ?? "A",
@@ -360,6 +385,7 @@ export async function ensureTelegramLeaderThreadBinding(
     }
     if (forcedUnnamedStale) await deps.topicTargetStore.persist();
   }
+  assertLeaderEpoch("before-provision");
   const ownTarget = await provisionOwnBusTopic({
     getAllowedUserId: deps.getAllowedUserId,
     instanceId: deps.instanceId,
@@ -375,6 +401,7 @@ export async function ensureTelegramLeaderThreadBinding(
     getRandom: deps.getRandom,
     recordEvent: deps.recordEvent,
   });
+  assertLeaderEpoch("after-provision");
   if (!ownTarget) return undefined;
   const replacementPlan = ThreadReconciler.planThreadReconciliation({
     nowMs: Date.now(),
@@ -404,7 +431,9 @@ export async function ensureTelegramLeaderThreadBinding(
     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
     recordRuntimeEvent: deps.recordEvent,
   });
+  assertLeaderEpoch("before-final-persist");
   await deps.topicTargetStore.persist();
+  assertLeaderEpoch("after-final-persist");
   return ownTarget;
 }
 
@@ -454,6 +483,53 @@ export function createUnknownTelegramSyncState(): TelegramSyncState {
   ) as TelegramSyncState;
 }
 
+export interface TelegramSyncStateRuntime {
+  getState(): TelegramSyncState;
+  setState(state: TelegramSyncState): void;
+  markConfigChange(action: string): void;
+  markSliceFresh(
+    slice: TelegramSyncSlice,
+    options: { nowMs: number; action: string },
+  ): void;
+}
+
+export function createTelegramSyncStateRuntime(
+  initialState = createUnknownTelegramSyncState(),
+): TelegramSyncStateRuntime {
+  let state = initialState;
+  return {
+    getState: () => state,
+    setState(nextState) {
+      state = nextState;
+    },
+    markConfigChange(action) {
+      state = markTelegramConfigSyncChange(state, action);
+    },
+    markSliceFresh(slice, options) {
+      state = markTelegramSyncSliceFresh(state, slice, options);
+    },
+  };
+}
+
+export interface TelegramProvisioningActivityRuntime {
+  isActive(): boolean;
+  start(): void;
+  end(): void;
+}
+
+export function createTelegramProvisioningActivityRuntime(): TelegramProvisioningActivityRuntime {
+  let activeCount = 0;
+  return {
+    isActive: () => activeCount > 0,
+    start() {
+      activeCount += 1;
+    },
+    end() {
+      activeCount = Math.max(0, activeCount - 1);
+    },
+  };
+}
+
 const RECONCILE_TRIGGERS = new Set<TelegramSyncTrigger>([
   "startup",
   "reload",
@@ -518,9 +594,8 @@ export function createTelegramObservedTopicLifecycleSyncHandler<
 >(
   deps: TelegramObservedTopicLifecycleSyncDeps<TSyncState>,
 ): TelegramTopicLifecycleSyncHandler<TMessage> {
-  const syncTopicLifecycle = createTelegramTopicLifecycleSyncHandler<TMessage>(
-    deps,
-  );
+  const syncTopicLifecycle =
+    createTelegramTopicLifecycleSyncHandler<TMessage>(deps);
   return async (lifecycle) => {
     const nowMs = deps.getNowMs ?? Date.now;
     deps.setSyncState(
@@ -580,14 +655,12 @@ export function createTelegramTopicLifecycleSyncHandler<TMessage = unknown>(
     const changed = result.changed;
     if (lifecycle.kind === "created" && deps.isBusEnabled()) {
       const target = lifecycle.target;
-      const isKnownInRecords = deps.topicTargetStore
-        .list()
-        .some((record) => {
-          return (
-            record.target.chatId === target.chatId &&
-            record.target.threadId === target.threadId
-          );
-        });
+      const isKnownInRecords = deps.topicTargetStore.list().some((record) => {
+        return (
+          record.target.chatId === target.chatId &&
+          record.target.threadId === target.threadId
+        );
+      });
       const isKnownInReservations = deps.topicTargetStore
         .listReservations()
         .some((reservation) => {

package/lib/telegram-api.ts

@@ -273,6 +273,7 @@ interface TelegramApiResponse<T> {
 export interface TelegramApiCallOptions {
   signal?: AbortSignal;
   maxAttempts?: number;
+  retrySafety?: "safe" | "non-idempotent";
   retryBaseDelayMs?: number;
   sleep?: (ms: number) => Promise<void>;
 }
@@ -449,6 +450,32 @@ function sanitizeFileName(name: string): string {
   return name.replace(/[^a-zA-Z0-9._-]+/g, "_");
 }
 
+class TelegramApiMalformedSuccessError extends Error {
+  constructor(method: string, detail: string) {
+    super(`Telegram API ${method} ${detail}`);
+    this.name = "TelegramApiMalformedSuccessError";
+  }
+}
+
+export class TelegramApiCommitUnknownError extends Error {
+  readonly kind = "commit-unknown" as const;
+  readonly method: string;
+  override readonly cause: unknown;
+
+  constructor(method: string, cause: unknown) {
+    super(`Telegram API ${method} may have committed before transport failed.`);
+    this.name = "TelegramApiCommitUnknownError";
+    this.method = method;
+    this.cause = cause;
+  }
+}
+
+export function isTelegramApiCommitUnknownError(
+  error: unknown,
+): error is TelegramApiCommitUnknownError {
+  return error instanceof TelegramApiCommitUnknownError;
+}
+
 class TelegramApiHttpError extends Error {
   readonly status: number | undefined;
   readonly retryAfterSeconds: number | undefined;
@@ -469,6 +496,30 @@ export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   );
 }
 
+const TELEGRAM_RETRY_SAFE_METHODS = new Set([
+  "answerCallbackQuery",
+  "closeForumTopic",
+  "deleteForumTopic",
+  "deleteMessage",
+  "deleteWebhook",
+  "editForumTopic",
+  "editMessageCaption",
+  "editMessageReplyMarkup",
+  "editMessageText",
+  "getChat",
+  "getFile",
+  "getMe",
+  "getUpdates",
+  "sendChatAction",
+  "sendMessageDraft",
+  "sendRichMessageDraft",
+  "setMyCommands",
+]);
+
+export function isTelegramApiMethodRetrySafe(method: string): boolean {
+  return TELEGRAM_RETRY_SAFE_METHODS.has(method);
+}
+
 function isRetryableTelegramApiError(error: unknown): boolean {
   return (
     error instanceof TelegramApiHttpError &&
@@ -579,22 +630,23 @@ async function parseTelegramApiResponse<TResponse>(
       Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
     );
   }
-  return (
-    data ?? {
-      ok: false,
-      description: `Telegram API ${method} returned invalid JSON`,
-    }
-  );
+  if (!data) {
+    throw new TelegramApiMalformedSuccessError(method, "returned invalid JSON");
+  }
+  return data;
 }
 
 function unwrapTelegramApiResult<TResponse>(
   method: string,
   data: TelegramApiResponse<TResponse>,
 ): TResponse {
-  if (!data.ok || data.result === undefined) {
+  if (data.ok && data.result === undefined) {
+    throw new TelegramApiMalformedSuccessError(method, "returned no result");
+  }
+  if (!data.ok) {
     throw new Error(data.description || `Telegram API ${method} failed`);
   }
-  return data.result;
+  return data.result as TResponse;
 }
 
 function getTelegramNetworkFamilyPolicy(
@@ -754,11 +806,13 @@ async function telegramFetch(
 
 async function callTelegramTransportRequest(
   request: (family?: TelegramNetworkFamily) => Promise<Response>,
+  allowFallback = true,
 ): Promise<Response> {
   const policy = getTelegramNetworkFamilyPolicy();
   if (policy === "auto") return request();
   const family = getTelegramNetworkFamily(policy);
   if (family) return request(family);
+  if (!allowFallback) return request();
   try {
     return await request();
   } catch (error) {
@@ -864,6 +918,10 @@ async function callTelegramWithRetry<TResponse>(
   request: (family?: TelegramNetworkFamily) => Promise<Response>,
   options: TelegramApiCallOptions | undefined,
 ): Promise<TResponse> {
+  const retrySafe =
+    options?.retrySafety === "safe" ||
+    (options?.retrySafety !== "non-idempotent" &&
+      isTelegramApiMethodRetrySafe(method));
   const maxAttempts = Math.max(1, options?.maxAttempts ?? 3);
   const retryBaseDelayMs = options?.retryBaseDelayMs ?? 500;
   const sleep = options?.sleep ?? sleepTelegramRetry;
@@ -872,14 +930,32 @@ async function callTelegramWithRetry<TResponse>(
       return unwrapTelegramApiResult(
         method,
         await parseTelegramApiResponse<TResponse>(
-          await callTelegramTransportRequest(request),
+          await callTelegramTransportRequest(request, retrySafe),
           method,
         ),
       );
     } catch (error) {
-      if (attempt >= maxAttempts - 1 || !isRetryableTelegramApiError(error)) {
+      const retryable = isRetryableTelegramApiError(error);
+      if (!retrySafe) {
+        if (error instanceof TelegramApiHttpError && error.status === 429) {
+          if (attempt >= maxAttempts - 1) throw error;
+          await sleep(
+            getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs),
+          );
+          continue;
+        }
+        if (
+          error instanceof TelegramApiMalformedSuccessError ||
+          isTelegramTransportFailure(error) ||
+          (error instanceof TelegramApiHttpError &&
+            error.status !== undefined &&
+            error.status >= 500)
+        ) {
+          throw new TelegramApiCommitUnknownError(method, error);
+        }
         throw error;
       }
+      if (attempt >= maxAttempts - 1 || !retryable) throw error;
       await sleep(getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs));
     }
   }

package/lib/text-groups.ts

@@ -22,14 +22,22 @@ export interface TelegramTextGroupState<TMessage, TContext = unknown> {
   messages: TMessage[];
   context?: TContext;
   flushTimer?: ReturnType<typeof setTimeout>;
+  dispatching?: boolean;
+  suspended?: boolean;
+  reschedule?: () => void;
 }
 
 export interface TelegramTextGroupController<TMessage, TContext = unknown> {
   queueMessage: (options: {
     message: TMessage;
     context: TContext;
-    dispatchMessages: (messages: TMessage[], ctx: TContext) => void;
+    dispatchMessages: (
+      messages: TMessage[],
+      ctx: TContext,
+    ) => unknown | Promise<unknown>;
   }) => boolean;
+  suspend: () => void;
+  resume: (context: TContext) => void;
   clear: () => void;
 }
 
@@ -71,9 +79,10 @@ function getTelegramTextGroupKey(
   if (message.media_group_id) return undefined;
   if (!message.from || message.from.is_bot) return undefined;
   if (typeof message.text !== "string") return undefined;
-  const threadKey = typeof message.message_thread_id === "number"
-    ? `thread:${message.message_thread_id}`
-    : "private";
+  const threadKey =
+    typeof message.message_thread_id === "number"
+      ? `thread:${message.message_thread_id}`
+      : "private";
   return `${message.chat.id}:${threadKey}:${message.from.id}`;
 }
 
@@ -114,7 +123,10 @@ export function queueTelegramTextGroupMessage<
   minSplitLength: number;
   setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
   clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
-  dispatchMessages: (messages: TMessage[], ctx: TContext) => void;
+  dispatchMessages: (
+    messages: TMessage[],
+    ctx: TContext,
+  ) => unknown | Promise<unknown>;
 }): boolean {
   const key = getTelegramTextGroupKey(options.message);
   if (!key) return false;
@@ -129,14 +141,45 @@ export function queueTelegramTextGroupMessage<
   const state = existing ?? { messages: [] };
   state.messages.push(options.message);
   state.context = options.context;
+  const scheduleDispatch = (): void => {
+    if (state.suspended) return;
+    state.flushTimer = options.setTimer(() => {
+      state.flushTimer = undefined;
+      const queued = options.groups.get(key);
+      if (!queued || queued.context === undefined) return;
+      if (queued.dispatching) {
+        scheduleDispatch();
+        return;
+      }
+      const dispatchedMessages = [...queued.messages];
+      const dispatchedIds = new Set(
+        dispatchedMessages.map((message) => message.message_id),
+      );
+      queued.dispatching = true;
+      void Promise.resolve(
+        options.dispatchMessages(dispatchedMessages, queued.context),
+      ).then(
+        () => {
+          if (options.groups.get(key) !== queued) return;
+          queued.messages = queued.messages.filter(
+            (message) => !dispatchedIds.has(message.message_id),
+          );
+          queued.dispatching = false;
+          if (queued.messages.length === 0) options.groups.delete(key);
+          else if (!queued.flushTimer) scheduleDispatch();
+        },
+        () => {
+          if (options.groups.get(key) !== queued) return;
+          queued.dispatching = false;
+          if (!queued.flushTimer) scheduleDispatch();
+        },
+      );
+    }, options.debounceMs);
+    state.flushTimer.unref?.();
+  };
+  state.reschedule = scheduleDispatch;
   if (state.flushTimer) options.clearTimer(state.flushTimer);
-  state.flushTimer = options.setTimer(() => {
-    const queued = options.groups.get(key);
-    options.groups.delete(key);
-    if (!queued || queued.context === undefined) return;
-    options.dispatchMessages(queued.messages, queued.context);
-  }, options.debounceMs);
-  state.flushTimer.unref?.();
+  scheduleDispatch();
   options.groups.set(key, state);
   return true;
 }
@@ -168,6 +211,20 @@ export function createTelegramTextGroupController<
         clearTimer,
         dispatchMessages,
       }),
+    suspend: () => {
+      for (const state of groups.values()) {
+        state.suspended = true;
+        if (state.flushTimer) clearTimer(state.flushTimer);
+        state.flushTimer = undefined;
+      }
+    },
+    resume: (context) => {
+      for (const state of groups.values()) {
+        state.context = context;
+        state.suspended = false;
+        if (!state.dispatching && !state.flushTimer) state.reschedule?.();
+      }
+    },
     clear: () => {
       for (const state of groups.values()) {
         if (state.flushTimer) clearTimer(state.flushTimer);
@@ -190,9 +247,8 @@ export function createTelegramTextGroupDispatchRuntime<
       const queuedTextGroup = deps.textGroups.queueMessage({
         message,
         context: ctx,
-        dispatchMessages: (messages, queuedCtx) => {
-          void deps.dispatchMessages(messages, queuedCtx);
-        },
+        dispatchMessages: (messages, queuedCtx) =>
+          deps.dispatchMessages(messages, queuedCtx),
       });
       if (queuedTextGroup) return;
       await deps.dispatchSingleMessage(message, ctx);