⚡ 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(integrations): persist pending outbound intents before provider writes
Tin84e7a5501160
diff --cc apps/api/src/plugins/github/services/link-manager.tsindex 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 updateExternalLinparams: 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.tsindex f91395916,000000000..54b85e971mode 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.tsindex 9457d9315,000000000..1c4a8f1aamode 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.tsindex 416c4d0b1,000000000..c2455792emode 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.tsindex 81c411f6c,000000000..5f54b0a3emode 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.tsindex 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.tsindex 000000000,000000000..73c754818new 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);++});