⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
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.mdxindex 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.### Optionsdiff --git a/packages/planka-import/src/index.ts b/packages/planka-import/src/index.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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`;+}