Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

fix(planka-import): retry rate-limited requests using Retry-After

Tin2ed1f6ea46f2
diff --git a/apps/docs/core/migrations/from-planka.mdx b/apps/docs/core/migrations/from-planka.mdx
index c51f7d74f..26466bd16 100644
--- a/apps/docs/core/migrations/from-planka.mdx
+++ b/apps/docs/core/migrations/from-planka.mdx
@@ -133,6 +133,8 @@ The in-app [troubleshooting](#troubleshooting) for terms, two-factor authenticat
**A board failed partway**: failures are isolated per board, so the rest still import and the summary names the one that failed. Delete the half-created Kaneo project and run the importer interactively again, selecting only the failed board. The `--project` flag filters PLANKA projects, which can contain several boards.
+**"Kaneo rate limit reached, waiting…"**: a large board can use up the Kaneo API key's [rate limit](/api-reference/authentication#rate-limits). The importer waits as long as Kaneo's `Retry-After` asks, then continues, so leave it running. If the key has a usage quota that won't refill for more than five minutes, the importer stops with the time left instead. Raise the key's limits or run again later.
+
**Re-running**: the importer always creates new projects; it never updates ones it created earlier. Running it twice gives you two copies, so delete the previous project before retrying.
### Options
diff --git a/packages/planka-import/src/index.ts b/packages/planka-import/src/index.ts
index d1791d8d1..94cd3bd57 100644
--- a/packages/planka-import/src/index.ts
+++ b/packages/planka-import/src/index.ts
@@ -6,6 +6,7 @@ import prompts from "prompts";
import { DEFAULT_KANEO_URL, HELP_TEXT, parseArgs } from "./args.js";
import { KaneoClient } from "./kaneo.js";
import { type BoardReport, type BoardTarget, migrate } from "./migrate.js";
+import { formatWait } from "./retry-after.js";
const require = createRequire(import.meta.url);
const { version } = require("../package.json") as { version: string };
@@ -108,6 +109,8 @@ async function main(): Promise<number> {
const kaneo = new KaneoClient({
baseUrl: args.kaneoUrl ?? DEFAULT_KANEO_URL,
apiKey: kaneoApiKey ?? "",
+ onRateLimit: (waitMs) =>
+ log(`Kaneo rate limit reached, waiting ${formatWait(waitMs)}…`),
});
let workspaceId = args.workspace ?? "";
diff --git a/packages/planka-import/src/kaneo.test.ts b/packages/planka-import/src/kaneo.test.ts
new file mode 100644
index 000000000..0bcd9f146
--- /dev/null
+++ b/packages/planka-import/src/kaneo.test.ts
@@ -0,0 +1,110 @@
+import {
+ afterEach,
+ beforeEach,
+ describe,
+ expect,
+ it,
+ vi,
+} from "vite-plus/test";
+import { KaneoClient } from "./kaneo.js";
+
+function limited(retryAfter?: string): Response {
+ return new Response(JSON.stringify({ message: "Rate limit exceeded" }), {
+ status: 429,
+ headers: retryAfter ? { "Retry-After": retryAfter } : {},
+ });
+}
+
+function ok(body: unknown): Response {
+ return new Response(JSON.stringify(body), { status: 200 });
+}
+
+describe("KaneoClient rate limiting", () => {
+ const fetchMock = vi.fn<typeof fetch>();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.stubGlobal("fetch", fetchMock);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ fetchMock.mockReset();
+ });
+
+ it("waits for Retry-After, reports the wait, and retries", async () => {
+ fetchMock
+ .mockResolvedValueOnce(limited("30"))
+ .mockResolvedValueOnce(ok([]));
+ const onRateLimit = vi.fn();
+ const client = new KaneoClient({
+ baseUrl: "https://kaneo.test",
+ apiKey: "key",
+ onRateLimit,
+ });
+
+ const result = client.listWorkspaces();
+ await vi.advanceTimersByTimeAsync(29_999);
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ await vi.advanceTimersByTimeAsync(1);
+
+ await expect(result).resolves.toEqual([]);
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(onRateLimit).toHaveBeenCalledWith(30_000);
+ });
+
+ it("fails fast when Retry-After is a long usage quota", async () => {
+ fetchMock.mockResolvedValueOnce(limited(String(6 * 3600)));
+ const client = new KaneoClient({
+ baseUrl: "https://kaneo.test",
+ apiKey: "key",
+ });
+
+ await expect(client.listWorkspaces()).rejects.toThrow(
+ /usage limit reached.*retry in about 6 h/,
+ );
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ });
+
+ it("fails when a 429 has no Retry-After", async () => {
+ fetchMock.mockResolvedValueOnce(limited());
+ const client = new KaneoClient({
+ baseUrl: "https://kaneo.test",
+ apiKey: "key",
+ });
+
+ await expect(client.listWorkspaces()).rejects.toThrow(
+ /rate limited \(HTTP 429\)/,
+ );
+ });
+
+ it("gives up after repeated 429s", async () => {
+ fetchMock.mockImplementation(async () => limited("1"));
+ const client = new KaneoClient({
+ baseUrl: "https://kaneo.test",
+ apiKey: "key",
+ });
+
+ const result = client.listWorkspaces();
+ const assertion = expect(result).rejects.toThrow(/rate limited/);
+ await vi.advanceTimersByTimeAsync(10_000);
+ await assertion;
+ expect(fetchMock).toHaveBeenCalledTimes(4);
+ });
+
+ it("keeps 401 meaning a bad key", async () => {
+ fetchMock.mockResolvedValueOnce(
+ new Response("Unauthorized", { status: 401 }),
+ );
+ const client = new KaneoClient({
+ baseUrl: "https://kaneo.test",
+ apiKey: "key",
+ });
+
+ await expect(client.listWorkspaces()).rejects.toThrow(
+ /check your Kaneo API key/,
+ );
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/planka-import/src/kaneo.ts b/packages/planka-import/src/kaneo.ts
index d5ca94fd0..33321382c 100644
--- a/packages/planka-import/src/kaneo.ts
+++ b/packages/planka-import/src/kaneo.ts
@@ -1,3 +1,5 @@
+import { formatWait, retryAfterMs } from "./retry-after.js";
+
export type KaneoWorkspace = { id: string; name: string; slug?: string };
export type KaneoProject = { id: string; name: string; slug: string };
export type KaneoColumn = { id: string; name: string; slug: string };
@@ -5,22 +7,16 @@ export type KaneoTask = { id: string; title: string; number: number };
export type KaneoLabel = { id: string; name: string; color: string };
export type KaneoMember = { id: string; name: string; email: string };
-const RATE_LIMIT_WINDOW_MS = 60_000;
-const REQUESTS_PER_WINDOW = 90;
-const RATE_LIMIT_SILENCE_BUFFER_MS = 2_000;
+// Kaneo denies a rate-limited key with 429 and a Retry-After that already
+// covers its silence window, so one wait is enough. Longer waits are usage
+// quotas (hours or days); failing beats an import that looks hung.
+const MAX_RATE_LIMIT_WAIT_MS = 5 * 60_000;
+const MAX_RATE_LIMIT_RETRIES = 3;
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
-function withResolvers(): { promise: Promise<void>; resolve: () => void } {
- let resolve!: () => void;
- const promise = new Promise<void>((r) => {
- resolve = r;
- });
- return { promise, resolve };
-}
-
export function normalizeBaseUrl(raw: string): string {
const trimmed = raw.trim().replace(/\/+$/, "");
try {
@@ -38,31 +34,16 @@ export function normalizeBaseUrl(raw: string): string {
export class KaneoClient {
readonly baseUrl: string;
private readonly apiKey: string;
- private static gate: Promise<void> = Promise.resolve();
- private static windowEndsAt = 0;
- private static sentInWindow = 0;
+ private readonly onRateLimit: (waitMs: number) => void;
- constructor(options: { baseUrl: string; apiKey: string }) {
+ constructor(options: {
+ baseUrl: string;
+ apiKey: string;
+ onRateLimit?: (waitMs: number) => void;
+ }) {
this.baseUrl = normalizeBaseUrl(options.baseUrl);
this.apiKey = options.apiKey;
- }
-
- private async acquireSlot(): Promise<void> {
- const previous = KaneoClient.gate;
- const release = withResolvers();
- KaneoClient.gate = release.promise;
- await previous;
- if (Date.now() >= KaneoClient.windowEndsAt) {
- KaneoClient.sentInWindow = 0;
- } else if (KaneoClient.sentInWindow >= REQUESTS_PER_WINDOW) {
- const wait = KaneoClient.windowEndsAt - Date.now();
- if (wait > 0) await sleep(wait);
- KaneoClient.sentInWindow = 0;
- }
- KaneoClient.sentInWindow++;
- KaneoClient.windowEndsAt =
- Date.now() + RATE_LIMIT_WINDOW_MS + RATE_LIMIT_SILENCE_BUFFER_MS;
- release.resolve();
+ this.onRateLimit = options.onRateLimit ?? (() => {});
}
listWorkspaces(): Promise<KaneoWorkspace[]> {
@@ -174,7 +155,27 @@ export class KaneoClient {
}
private async request<T>(path: string, init?: RequestInit): Promise<T> {
- await this.acquireSlot();
+ for (let attempt = 0; ; attempt++) {
+ const res = await this.send(path, init);
+ if (res.status !== 429) return this.parse<T>(path, res);
+ await res.body?.cancel();
+ const waitMs = retryAfterMs(res.headers.get("Retry-After"));
+ if (waitMs === null || attempt >= MAX_RATE_LIMIT_RETRIES) {
+ throw new Error(
+ `Kaneo ${path}: rate limited (HTTP 429), Kaneo throttled this API key; run again later`,
+ );
+ }
+ if (waitMs > MAX_RATE_LIMIT_WAIT_MS) {
+ throw new Error(
+ `Kaneo ${path}: API key usage limit reached (HTTP 429); retry in about ${formatWait(waitMs)} or raise the key's limits`,
+ );
+ }
+ this.onRateLimit(waitMs);
+ await sleep(waitMs);
+ }
+ }
+
+ private async send(path: string, init?: RequestInit): Promise<Response> {
const headers = new Headers(init?.headers);
headers.set("Authorization", `Bearer ${this.apiKey}`);
headers.set("Accept", "application/json");
@@ -182,9 +183,8 @@ export class KaneoClient {
headers.set("Content-Type", "application/json");
}
- let res: Response;
try {
- res = await fetch(`${this.baseUrl}${path}`, {
+ return await fetch(`${this.baseUrl}${path}`, {
...init,
headers,
signal: AbortSignal.timeout(30_000),
@@ -193,7 +193,9 @@ export class KaneoClient {
const reason = error instanceof Error ? error.message : String(error);
throw new Error(`Kaneo ${path}: ${reason}`);
}
+ }
+ private async parse<T>(path: string, res: Response): Promise<T> {
const text = await res.text();
let body: unknown = null;
if (text) {
@@ -216,9 +218,6 @@ function describeError(body: unknown, status: number): string {
if (status === 401) {
return "unauthorized (HTTP 401), check your Kaneo API key";
}
- if (status === 429) {
- return "rate limited (HTTP 429), Kaneo throttled this API key; run again later";
- }
if (typeof body === "object" && body !== null) {
const record = body as Record<string, unknown>;
for (const key of ["message", "error"]) {
diff --git a/packages/planka-import/src/retry-after.test.ts b/packages/planka-import/src/retry-after.test.ts
new file mode 100644
index 000000000..84ff59a63
--- /dev/null
+++ b/packages/planka-import/src/retry-after.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vite-plus/test";
+import { formatWait, retryAfterMs } from "./retry-after.js";
+
+describe("retryAfterMs", () => {
+ it("reads delay seconds", () => {
+ expect(retryAfterMs("42")).toBe(42_000);
+ });
+
+ it("reads an HTTP date relative to now", () => {
+ const now = Date.parse("2026-01-01T00:00:00Z");
+ expect(retryAfterMs("Thu, 01 Jan 2026 00:00:30 GMT", now)).toBe(30_000);
+ });
+
+ it("returns null for a missing or unparseable header", () => {
+ expect(retryAfterMs(null)).toBeNull();
+ expect(retryAfterMs("soon")).toBeNull();
+ });
+});
+
+describe("formatWait", () => {
+ it("uses the coarsest readable unit", () => {
+ expect(formatWait(45_000)).toBe("45s");
+ expect(formatWait(10 * 60_000)).toBe("10 min");
+ expect(formatWait(20 * 3_600_000)).toBe("20 h");
+ });
+});
diff --git a/packages/planka-import/src/retry-after.ts b/packages/planka-import/src/retry-after.ts
new file mode 100644
index 000000000..966a10035
--- /dev/null
+++ b/packages/planka-import/src/retry-after.ts
@@ -0,0 +1,17 @@
+export function retryAfterMs(
+ header: string | null,
+ now = Date.now(),
+): number | null {
+ if (!header) return null;
+ const seconds = Number(header);
+ if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+ const date = Date.parse(header);
+ return Number.isNaN(date) ? null : Math.max(0, date - now);
+}
+
+export function formatWait(ms: number): string {
+ const seconds = Math.ceil(ms / 1000);
+ if (seconds < 120) return `${seconds}s`;
+ const minutes = Math.ceil(seconds / 60);
+ return minutes < 120 ? `${minutes} min` : `${Math.ceil(minutes / 60)} h`;
+}