Convex 动作检索器

动作有时会因网络错误、服务器重启或问题而失败 加上第3个政党API,经常可以重试. 行动检索器 组件使得这真的容易.

import { ActionRetrier } from "@convex-dev/action-retrier";
import { components } from "./convex/_generated/server";

const retrier = new ActionRetrier(components.actionRetrier);

// `retrier.run` will automatically retry your action up to four times before giving up.
await retrier.run(ctx, internal.module.myAction, { arg: 123 });

反射器组件将运行动作,并在失败时重试,与 指数后退, 直至动作成功或重复的最大次数 已经到达.

预先要求: Convex

你需要一个现有的 Convex 项目来使用组件。 Convex 是一个主机 后端平台,包括数据库、无服务器功能和多一个吨 可以学习 这里。 。 。 .

运行 npm create convex 或遵循其中任何一条 快速启动 来设置一个.

安装

第一,添加 @convex-dev/action-retrier 作为国家预防机制的依赖:

npm install @convex-dev/action-retrier

然后,将组件安装到您的 Convex 工程中 convex/convex.config.ts 配置文件 :

// convex/convex.config.ts
import { defineApp } from "convex/server";
import actionRetrier from "@convex-dev/action-retrier/convex.config.js";

const app = defineApp();
app.use(actionRetrier);
export default app;

最后,创建一个新的 ActionRetrier 在您的 Convex 项目中, 并指示它 至已安装组件:

// convex/index.ts
import { ActionRetrier } from "@convex-dev/action-retrier";
import { components } from "./_generated/api";

export const retrier = new ActionRetrier(components.actionRetrier);

您可以在 ActionRetrier 建筑师.

const retrier = new ActionRetrier(components.actionRetrier, {
  initialBackoffMs: 10000,
  base: 10,
  maxFailures: 4,
});

• initialBackoffMs 是重试前失败后的初始延迟 (默认:250).
• base 是指数后退的基数( 默认: 2) .
• maxFailures 是重试动作的最大次数( 默认 4) .

API 密码

开始运行

在安装组件后,使用 run 从变异或 行动启动行动.

export const kickoffExampleAction = mutation({
  handler: async (ctx) => {
    const runId = await retrier.run(ctx, internal.index.exampleAction, {
      foo: "bar",
    });
    // ... optionally persist or pass along the runId
  },
});

export const exampleAction = internalAction({
  args: { foo: v.string() },
  handler: async (ctx, args) => {
    return operationThatMightFail(args);
  },
});

返回值为 retrier.run 不是行动的结果,而是 用于查询其状态或取消其状态的ID。 动作的返回值 当它成功时,随状态一起保存.

您可以在选项中选择指定对后退参数的覆盖 参数.

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(
    ctx,
    internal.index.exampleAction,
    { failureRate: 0.8 },
    {
      initialBackoffMs: 125,
      base: 2.71,
      maxFailures: 3,
    },
  );
});

您可以指定一个 onComplete 选项参数中的突变回调 不错 这种突变可以保证最终精确运行一次.

// convex/index.ts

import { runResultValidator, runIdValidator } from "@convex-dev/action-retrier";

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(
    ctx,
    internal.index.exampleAction,
    { failureRate: 0.8 },
    {
      onComplete: internal.index.exampleCallback,
    },
  );
});

export const exampleCallback = internalMutation({
  args: { id: runIdValidator, result: runResultValidator },
  handler: async (ctx, args) => {
    if (args.result.type === "success") {
      console.log(
        "Action succeeded with return value:",
        args.result.returnValue,
      );
    } else if (args.result.type === "failed") {
      console.log("Action failed with error:", args.result.error);
    } else if (args.result.type === "canceled") {
      console.log("Action was canceled.");
    }
  },
});

运行状态

这个 run 方法返回 a RunId,然后可用于查询运行的 状态.

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  while (true) {
    const status = await retrier.status(ctx, runId);
    if (status.type === "inProgress") {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      continue;
    } else {
      console.log("Run completed with result:", status.result);
      break;
    }
  }
});

取消运行

您可以使用 cancel 方法.

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  await new Promise((resolve) => setTimeout(resolve, 1000));
  await retrier.cancel(ctx, runId);
});

正在执行的运行将被取消, 因此可能 仍在执行。 一个成功的呼吁 cancel不过 保证以后 status 电话将表示取消.

清理已完成的运行

运行占用了数据库中的空间,因为它们存储了返回值. 之后 运行完成后,您可立即使用 retrier.cleanup(ctx, runId)。系统将自动清理完成 7天后运行.

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  try {
    while (true) {
      const status = await retrier.status(ctx, runId);
      if (status.type === "inProgress") {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        continue;
      } else {
        console.log("Run completed with result:", status.result);
        break;
      }
    }
  } finally {
    await retrier.cleanup(ctx, runId);
  }
});

日志

你可以设置 ACTION_RETRIER_LOG_LEVEL 改为 DEBUG 拥有回溯日志 更多的内部信息,然后你可以查看 Convex 仪表板.

npx convex env set ACTION_RETRIER_LOG_LEVEL DEBUG

默认日志级别为 INFO但你也可以设置它 ERROR 对偶数 木头少.