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(integrations): persist pending outbound intents before provider writes

Tin84e7a5501160
diff --cc apps/api/src/plugins/github/services/link-manager.ts
index 58f536de5,c62f3b860..ba33474ba
--- a/apps/api/src/plugins/github/services/link-manager.ts
+++ b/apps/api/src/plugins/github/services/link-manager.ts
@@@ -24,11 -21,6 +24,14 @@@ export type CreateExternalLinkParams =
};
export type UpdateExternalLinkParams = {
+ outbound?: {
+ field: "title" | "description" | "state";
+ value: string;
+ updatedAt?: string;
++ intentId?: string;
++ pending?: boolean;
++ cancelled?: boolean;
+ };
title?: string | null;
url?: string;
metadata?: Record<string, unknown>;
@@@ -124,32 -116,6 +127,37 @@@ export async function updateExternalLin
params: UpdateExternalLinkParams,
database: DbOrTx = db,
) {
+ if (params.outbound || params.metadata) {
+ await database.transaction(async (tx) => {
+ const link = await lockExternalLink(id, tx);
+ if (!link) return;
+ const metadata = parseLinkMetadata<
+ Record<string, unknown> & { lastSync?: Record<string, SyncStamp> }
+ >(link.metadata, { externalLinkId: id, source: "sync_update" });
+ const merged = mergeSyncMetadata(metadata, params.metadata ?? {});
+ if (params.outbound) {
- const { field, value, updatedAt } = params.outbound;
++ const { field, value, updatedAt, ...intent } = params.outbound;
+ merged.lastSync = {
+ ...merged.lastSync,
- [field]: outboundStamp(merged.lastSync?.[field], value, updatedAt),
++ [field]: outboundStamp(
++ merged.lastSync?.[field],
++ value,
++ updatedAt,
++ intent,
++ ),
+ };
+ }
+ await tx
+ .update(externalLinkTable)
+ .set({
+ ...(params.title !== undefined ? { title: params.title } : {}),
+ ...(params.url !== undefined ? { url: params.url } : {}),
+ metadata: JSON.stringify(merged),
+ })
+ .where(eq(externalLinkTable.id, id));
+ });
+ return;
+ }
const updateData: Record<string, unknown> = {};
if (params.title !== undefined) {
diff --cc apps/api/src/plugins/github/services/sync-latest-task-value.ts
index f91395916,000000000..54b85e971
mode 100644,000000..100644
--- a/apps/api/src/plugins/github/services/sync-latest-task-value.ts
+++ b/apps/api/src/plugins/github/services/sync-latest-task-value.ts
@@@ -1,48 -1,0 +1,62 @@@
++import { randomUUID } from "node:crypto";
+import db from "../../../database";
+import { linkedTaskScope } from "./integration-task-scope";
+import { findExternalLinksByTask, updateExternalLink } from "./link-manager";
+
+// Provider requests may complete out of order across API instances. Every late
+// completion repairs the provider using the current, still-linked task value.
+export async function syncLatestTaskValue(
+ taskId: string,
+ projectId: string,
+ link: { id: string; integrationId: string | null },
+ field: "title" | "description" | "state",
+ initialValue: string,
+ write: (value: string) => Promise<string | undefined>,
+) {
+ let value = initialValue;
+ for (;;) {
- const updatedAt = await write(value);
++ const intentId = randomUUID();
++ // Webhooks may arrive before PATCH returns, including from another instance.
++ await updateExternalLink(link.id, {
++ outbound: { field, value, intentId, pending: true },
++ });
++ let updatedAt: string | undefined;
++ try {
++ updatedAt = await write(value);
++ } catch (error) {
++ await updateExternalLink(link.id, {
++ outbound: { field, value, intentId, pending: false, cancelled: true },
++ }).catch(() => {});
++ throw error;
++ }
+ await updateExternalLink(link.id, {
+ ...(field === "title" ? { title: value } : {}),
- outbound: { field, value, updatedAt },
++ outbound: { field, value, updatedAt, intentId, pending: false },
+ ...(field === "state"
+ ? { metadata: { state: value, lastOutboundStateSyncAt: Date.now() } }
+ : {}),
+ });
+ const task = await db.query.taskTable.findFirst({
+ where: linkedTaskScope(taskId, projectId),
+ columns: { title: true, description: true, status: true },
+ });
+ if (!task) return;
+ const current =
+ field === "state"
+ ? task.status === "done"
+ ? "closed"
+ : "open"
+ : field === "title"
+ ? task.title
+ : task.description || "";
+ if (current === value) return;
+ const stillLinked = (await findExternalLinksByTask(taskId)).some(
+ (currentLink) =>
+ currentLink.id === link.id &&
+ currentLink.integrationId === link.integrationId &&
+ currentLink.resourceType === "issue",
+ );
+ if (!stillLinked) return;
+ value = current;
+ }
+}
diff --cc apps/api/src/plugins/github/utils/inbound-echo.ts
index 9457d9315,000000000..1c4a8f1aa
mode 100644,000000..100644
--- a/apps/api/src/plugins/github/utils/inbound-echo.ts
+++ b/apps/api/src/plugins/github/utils/inbound-echo.ts
@@@ -1,27 -1,0 +1,32 @@@
- import { isOutboundEcho, type SyncStamp } from "./sync-echo";
++import {
++ isOutboundEcho,
++ isPendingOutboundEcho,
++ type SyncStamp,
++} from "./sync-echo";
+class ConfirmationRequired extends Error {}
+
+export function inboundEcho(
+ stamp: SyncStamp | undefined,
+ value: string,
+ updatedAt?: string,
+ providerValue?: string,
+) {
++ if (isPendingOutboundEcho(stamp, value)) return true;
+ if (!isOutboundEcho(stamp, value, updatedAt)) return false;
+ if (stamp?.value === value) return true;
+ if (providerValue === undefined) throw new ConfirmationRequired();
+ return providerValue !== value;
+}
+
+// Release the guarded transaction before an ambiguous echo needs provider I/O.
+export async function withEchoConfirmation<Provider, Result>(
+ read: () => Promise<Provider>,
+ apply: (current?: Provider) => Promise<Result>,
+): Promise<Result> {
+ try {
+ return await apply();
+ } catch (error) {
+ if (!(error instanceof ConfirmationRequired)) throw error;
+ return apply(await read());
+ }
+}
diff --cc apps/api/src/plugins/github/utils/merge-sync-metadata.ts
index 416c4d0b1,000000000..c2455792e
mode 100644,000000..100644
--- a/apps/api/src/plugins/github/utils/merge-sync-metadata.ts
+++ b/apps/api/src/plugins/github/utils/merge-sync-metadata.ts
@@@ -1,51 -1,0 +1,65 @@@
- import type { SyncStamp } from "./sync-echo";
++import {
++ boundOutboundHistory,
++ type OutboundEntry,
++ type SyncStamp,
++} from "./sync-echo";
+type SyncMetadata = Record<string, unknown> & {
+ lastSync?: Record<string, SyncStamp>;
+};
+
+const historyOf = (stamp: SyncStamp | undefined) =>
+ Array.isArray(stamp?.outbound)
+ ? stamp.outbound.filter(
+ (entry) =>
+ typeof entry?.hash === "string" &&
+ typeof entry?.timestamp === "string",
+ )
+ : [];
+
+export function mergeSyncMetadata(
+ current: SyncMetadata,
+ incoming: SyncMetadata,
+): SyncMetadata {
+ const lastSync = { ...current.lastSync, ...incoming.lastSync };
+ for (const [field, stamp] of Object.entries(lastSync)) {
+ const history = [
+ ...historyOf(current.lastSync?.[field]),
+ ...historyOf(incoming.lastSync?.[field]),
+ ];
+ const prior = current.lastSync?.[field];
+ const priorTime = Date.parse(prior?.timestamp ?? "");
+ const incomingTime = Date.parse(stamp?.timestamp ?? "");
+ const latest =
+ Number.isFinite(priorTime) &&
+ (!Number.isFinite(incomingTime) || priorTime > incomingTime)
+ ? prior
+ : stamp;
+ lastSync[field] = latest ?? stamp;
+ if (history.length)
+ lastSync[field] = {
+ ...latest,
- outbound: [
- ...new Map(
- history.map((entry) => [JSON.stringify(entry), entry]),
- ).values(),
- ]
- .sort((a, b) => a.timestamp.localeCompare(b.timestamp))
- .slice(-32),
++ outbound: boundOutboundHistory([
++ ...history
++ .reduce((entries, entry) => {
++ const key = entry.intentId ?? JSON.stringify(entry);
++ const prior = entries.get(key);
++ if (
++ !prior ||
++ entry.timestamp > prior.timestamp ||
++ (entry.timestamp === prior.timestamp &&
++ prior.pending &&
++ !entry.pending)
++ )
++ entries.set(key, entry);
++ return entries;
++ }, new Map<string, OutboundEntry>())
++ .values(),
++ ]),
+ };
+ }
+ return {
+ ...current,
+ ...incoming,
+ ...(Object.keys(lastSync).length ? { lastSync } : {}),
+ };
+}
diff --cc apps/api/src/plugins/github/utils/sync-echo.ts
index 81c411f6c,000000000..5f54b0a3e
mode 100644,000000..100644
--- a/apps/api/src/plugins/github/utils/sync-echo.ts
+++ b/apps/api/src/plugins/github/utils/sync-echo.ts
@@@ -1,69 -1,0 +1,114 @@@
+import { createHash } from "node:crypto";
+
++export type OutboundIntent = {
++ intentId?: string;
++ pending?: boolean;
++ cancelled?: boolean;
++};
++export type OutboundEntry = OutboundIntent & {
++ hash: string;
++ timestamp: string;
++ updatedAt?: string;
++};
+export type SyncStamp = {
+ timestamp?: string;
+ source?: string;
+ value?: string;
- outbound?: Array<{ hash: string; timestamp: string; updatedAt?: string }>;
++ outbound?: OutboundEntry[];
+};
+
+const hash = (value: string) =>
+ createHash("sha256").update(value).digest("hex");
+
+export function outboundStamp(
+ previous: SyncStamp | undefined,
+ value: string,
+ updatedAt?: string,
++ intent: OutboundIntent = {},
+): SyncStamp {
+ const timestamp = new Date().toISOString();
- const outbound = [...(previous?.outbound ?? [])];
++ const outbound = (previous?.outbound ?? []).filter(
++ (entry) => !intent.intentId || entry.intentId !== intent.intentId,
++ );
+ // Older installations have only the last value, without a provider timestamp.
+ if (
+ previous?.source === "kaneo" &&
+ !previous.outbound?.length &&
+ previous.value !== undefined &&
+ previous.timestamp
+ )
+ outbound.push({
+ hash: hash(previous.value),
+ timestamp: previous.timestamp,
+ });
- outbound.push({ hash: hash(value), timestamp, updatedAt });
- return { timestamp, source: "kaneo", value, outbound: outbound.slice(-32) };
++ outbound.push({ hash: hash(value), timestamp, updatedAt, ...intent });
++ const bounded = boundOutboundHistory(outbound);
++ if (intent.pending || intent.cancelled)
++ return { ...previous, outbound: bounded };
++ return { timestamp, source: "kaneo", value, outbound: bounded };
++}
++
++export function boundOutboundHistory(entries: OutboundEntry[]) {
++ // Keep active intents until they settle; completed history stays bounded.
++ const recent = entries
++ .filter(
++ (entry) =>
++ !entry.pending || Date.now() - Date.parse(entry.timestamp) < 300_000,
++ )
++ .sort((left, right) => left.timestamp.localeCompare(right.timestamp));
++ const completed = recent.filter((entry) => !entry.pending).slice(-32);
++ return [...completed, ...recent.filter((entry) => entry.pending)].sort(
++ (left, right) => left.timestamp.localeCompare(right.timestamp),
++ );
++}
++
++export function isPendingOutboundEcho(
++ stamp: SyncStamp | undefined,
++ value: string,
++) {
++ return (stamp?.outbound ?? []).some(
++ (entry) =>
++ entry.pending &&
++ !entry.cancelled &&
++ entry.hash === hash(value) &&
++ Date.now() - Date.parse(entry.timestamp) < 300_000,
++ );
+}
+
+export function isOutboundEcho(
+ stamp: SyncStamp | undefined,
+ value: string,
+ updatedAt?: string,
+): boolean {
+ if (!stamp) return false;
+ const entries = stamp.outbound ?? [];
+ const valueHash = hash(value);
+ if (
+ entries.some(
+ (entry) =>
++ !entry.cancelled &&
+ entry.hash === valueHash &&
+ (entry.updatedAt && updatedAt
+ ? entry.updatedAt === updatedAt
+ : Date.now() - Date.parse(entry.timestamp) < 300_000),
+ )
+ )
+ return true;
+ // Preserve compatibility with stamps written before outbound history existed.
+ return (
+ entries.length === 0 && stamp.source === "kaneo" && stamp.value === value
+ );
+}
+
+/** Provider timestamps can collide; historical values need current-provider confirmation. */
+export async function confirmedOutboundEcho(
+ stamp: SyncStamp | undefined,
+ value: string,
+ updatedAt: string | undefined,
+ readCurrent: () => Promise<string>,
+) {
++ if (isPendingOutboundEcho(stamp, value)) return true;
+ if (!isOutboundEcho(stamp, value, updatedAt)) return false;
+ if (stamp?.value === value) return true;
+ return (await readCurrent()) !== value;
+}
diff --cc tests/api-integration/integration-task-ownership.test.ts
index 493f647b7,0ce685d84..600385772
--- a/tests/api-integration/integration-task-ownership.test.ts
+++ b/tests/api-integration/integration-task-ownership.test.ts
@@@ -23,8 -23,8 +23,9 @@@ import
} from "./helpers/fixtures";
const m = vi.hoisted(() => ({
+ publish: vi.fn(async (_type: string, _data: unknown) => undefined),
listIssues: vi.fn(),
+ getIssue: vi.fn(),
listIssueComments: vi.fn(async () => []),
listIssueNotes: vi.fn(async () => []),
listPulls: vi.fn(async () => []),
diff --cc tests/api/plugins/github/outbound-intent.test.ts
index 000000000,000000000..73c754818
new file mode 100644
--- /dev/null
+++ b/tests/api/plugins/github/outbound-intent.test.ts
@@@ -1,0 -1,0 +1,141 @@@
++import { beforeEach, expect, it, vi } from "vite-plus/test";
++import { syncLatestTaskValue } from "../../../../apps/api/src/plugins/github/services/sync-latest-task-value";
++import { inboundEcho } from "../../../../apps/api/src/plugins/github/utils/inbound-echo";
++import { mergeSyncMetadata } from "../../../../apps/api/src/plugins/github/utils/merge-sync-metadata";
++import {
++ isPendingOutboundEcho,
++ outboundStamp,
++ type OutboundIntent,
++ type SyncStamp,
++} from "../../../../apps/api/src/plugins/github/utils/sync-echo";
++const m = vi.hoisted(() => ({
++ current: { title: "", description: "", status: "" },
++ stamps: {} as Record<string, SyncStamp>,
++ save: vi.fn(),
++}));
++vi.mock("../../../../apps/api/src/database", () => ({
++ default: { query: { taskTable: { findFirst: async () => m.current } } },
++}));
++vi.mock(
++ "../../../../apps/api/src/plugins/github/services/link-manager",
++ () => ({
++ findExternalLinksByTask: async () => [
++ { id: "link", integrationId: "integration", resourceType: "issue" },
++ ],
++ updateExternalLink: m.save,
++ }),
++);
++const link = { id: "link", integrationId: "integration" };
++beforeEach(() => {
++ m.stamps = {};
++ m.save.mockReset().mockImplementation(
++ async (
++ _id: string,
++ {
++ outbound,
++ }: {
++ outbound: OutboundIntent & {
++ field: string;
++ value: string;
++ updatedAt?: string;
++ };
++ },
++ ) => {
++ m.stamps[outbound.field] = outboundStamp(
++ m.stamps[outbound.field],
++ outbound.value,
++ outbound.updatedAt,
++ outbound,
++ );
++ },
++ );
++});
++function deferred() {
++ let resolve!: () => void;
++ const promise = new Promise<void>((done) => {
++ resolve = done;
++ });
++ return { promise, resolve };
++}
++it.each(["title", "description", "state"] as const)(
++ "preserves the newest %s when an old webhook arrives before its PATCH response",
++ async (field) => {
++ const a = field === "state" ? "closed" : "A";
++ const b = field === "state" ? "open" : "B";
++ m.current = { title: a, description: a, status: "done" };
++ const started = deferred();
++ const release = deferred();
++ let first = true;
++ let remote = a;
++ const write = async (value: string) => {
++ if (first) {
++ first = false;
++ started.resolve();
++ await release.promise;
++ }
++ remote = value;
++ // Exercise the same predicate used by the guarded inbound handlers while
++ // the provider has applied the write and has not returned its response.
++ if (!inboundEcho(m.stamps[field], value, `${value}-stamp`, remote)) {
++ if (field === "state")
++ m.current.status = value === "closed" ? "done" : "to-do";
++ else m.current[field] = value;
++ }
++ return `${value}-stamp`;
++ };
++ const older = syncLatestTaskValue("task", "project", link, field, a, write);
++ await started.promise;
++ m.current = { title: b, description: b, status: "to-do" };
++ await syncLatestTaskValue("task", "project", link, field, b, write);
++ release.resolve();
++ await older;
++ expect(remote).toBe(b);
++ expect(field === "state" ? m.current.status : m.current[field]).toBe(
++ field === "state" ? "to-do" : b,
++ );
++ expect(m.stamps[field].outbound?.some((entry) => entry.pending)).toBe(
++ false,
++ );
++ expect(inboundEcho(m.stamps[field], a, "legitimate-later-stamp", a)).toBe(
++ false,
++ );
++ },
++);
++it("clears failed intents so a later legitimate provider edit is accepted", async () => {
++ await expect(
++ syncLatestTaskValue("task", "project", link, "title", "A", async () => {
++ throw new Error("provider failed");
++ }),
++ ).rejects.toThrow("provider failed");
++ expect(isPendingOutboundEcho(m.stamps.title, "A")).toBe(false);
++ expect(inboundEcho(m.stamps.title, "A", "later", "A")).toBe(false);
++});
++it("does not resurrect a settled intent from stale metadata", () => {
++ const pending = outboundStamp(undefined, "A", undefined, {
++ intentId: "a",
++ pending: true,
++ });
++ const completed = outboundStamp(pending, "A", "stamp", {
++ intentId: "a",
++ pending: false,
++ });
++ const merged = mergeSyncMetadata(
++ { lastSync: { title: completed } },
++ { lastSync: { title: pending } },
++ );
++ expect(merged.lastSync?.title.outbound).toHaveLength(1);
++ expect(isPendingOutboundEcho(merged.lastSync?.title, "A")).toBe(false);
++});
++it("keeps an active intent while bounding completed rapid-write history", () => {
++ let stamp = outboundStamp(undefined, "A", undefined, {
++ intentId: "a",
++ pending: true,
++ });
++ for (let index = 0; index < 50; index++)
++ stamp = outboundStamp(stamp, `B${index}`, `stamp-${index}`, {
++ intentId: `b${index}`,
++ pending: false,
++ });
++ expect(stamp.outbound?.filter((entry) => !entry.pending)).toHaveLength(32);
++ expect(isPendingOutboundEcho(stamp, "A")).toBe(true);
++});