@salesforce/graphiti 10.10.3 → 10.11.0

package/src/lib/__tests__/prime-schema.spec.ts

@@ -7,7 +7,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { buildSchema } from "graphql";
 import { describe, expect, it } from "vitest";
+import { makeObjectInfo } from "../../__tests__/helpers/object-info.js";
 
 describe("lib/prime-schema", () => {
 	it("atomic-write: temp file is renamed to final path, no .tmp left behind", async () => {
@@ -27,6 +29,23 @@ describe("lib/prime-schema", () => {
 		fs.rmSync(tmpRoot, { recursive: true, force: true });
 	});
 
+	it("atomic-write: atomicWriteText renames into place with no .tmp left behind", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-text-"));
+		const finalPath = path.join(tmpRoot, "schema.graphql");
+
+		const { atomicWriteText } = await import("../fs-utils.js");
+
+		atomicWriteText(finalPath, "type Query { a: Int }");
+
+		expect(fs.existsSync(finalPath)).toBe(true);
+		expect(fs.readFileSync(finalPath, "utf-8")).toBe("type Query { a: Int }");
+
+		const leftovers = fs.readdirSync(tmpRoot).filter((f) => f.includes(".tmp"));
+		expect(leftovers).toEqual([]);
+
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
 	it("atomic-write: parallel calls in the same process do not collide", async () => {
 		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-parallel-"));
 		const finalPath = path.join(tmpRoot, "p.json");
@@ -231,6 +250,328 @@ describe("lib/prime-schema", () => {
 		}
 	});
 
+	// ── forceRefresh (W-22845606) ──────────────────────────────────────────────
+
+	const INSTANCE_URL = "https://example.my.salesforce.com";
+
+	async function schemaFilePath(tmpRoot: string): Promise<string> {
+		const { schemaCacheKeyForInstanceUrl } = await import("../introspect.js");
+		return path.join(tmpRoot, "schemas", `${schemaCacheKeyForInstanceUrl(INSTANCE_URL)}.json`);
+	}
+
+	async function writeSchemaFile(tmpRoot: string): Promise<string> {
+		const { atomicWriteJson } = await import("../fs-utils.js");
+		const fp = await schemaFilePath(tmpRoot);
+		atomicWriteJson(fp, {
+			data: { __schema: { types: [] } },
+			__graphiti: {
+				instanceUrl: INSTANCE_URL,
+				alias: "test-org",
+				cachedAt: new Date().toISOString(),
+			},
+		});
+		return fp;
+	}
+
+	// Build stub PrimeDeps whose downloadSchema increments a counter, optionally
+	// throws (per the `throwOn` map), and otherwise writes the cache file.
+	function makeStubDeps(
+		tmpRoot: string,
+		opts: { throwOn?: Record<number, unknown>; delayMs?: number } = {},
+	) {
+		let calls = 0;
+		const deps = {
+			getOrgAuth: async () => ({
+				alias: "test-org",
+				instanceUrl: INSTANCE_URL,
+				accessToken: "fake-token",
+				username: "user@example.com",
+				orgId: "00Dxx0000000000",
+			}),
+			downloadSchema: async () => {
+				calls++;
+				const toThrow = opts.throwOn?.[calls];
+				if (toThrow) throw toThrow;
+				if (opts.delayMs) await new Promise((r) => setTimeout(r, opts.delayMs));
+				await writeSchemaFile(tmpRoot);
+				const { schemaCacheKeyForInstanceUrl } = await import("../introspect.js");
+				return {
+					cacheKey: schemaCacheKeyForInstanceUrl(INSTANCE_URL),
+					instanceUrl: INSTANCE_URL,
+					typeCount: 0,
+					downloadedAt: new Date().toISOString(),
+					filePath: await schemaFilePath(tmpRoot),
+				};
+			},
+		};
+		return { deps, calls: () => calls };
+	}
+
+	it("withSchemaLock: honors a custom skipIf predicate", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-skipif-"));
+		const finalPath = path.join(tmpRoot, "s.json");
+		try {
+			const { withSchemaLock } = await import("../prime-schema.js");
+
+			let ran = false;
+			const skipResult = await withSchemaLock(finalPath, async () => (ran = true), {
+				skipIf: () => true,
+			});
+			expect(ran).toBe(false);
+			expect(skipResult).toBeUndefined();
+
+			await withSchemaLock(finalPath, async () => (ran = true), { skipIf: () => false });
+			expect(ran).toBe(true);
+		} finally {
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: forceRefresh re-downloads even though the file exists", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const { deps, calls } = makeStubDeps(tmpRoot);
+
+			const first = await primeSchemaWithLock("test-org", deps);
+			expect(first.cached).toBe(false);
+			expect(first.refreshed).toBe(false);
+			expect(calls()).toBe(1);
+
+			// Without forceRefresh, a second call is a pure cache hit.
+			const hit = await primeSchemaWithLock("test-org", deps);
+			expect(hit.cached).toBe(true);
+			expect(hit.refreshed).toBe(false);
+			expect(calls()).toBe(1);
+
+			// With forceRefresh, it re-downloads despite the existing file.
+			const refreshed = await primeSchemaWithLock("test-org", deps, { forceRefresh: true });
+			expect(refreshed.refreshed).toBe(true);
+			expect(refreshed.cached).toBe(false);
+			expect(calls()).toBe(2);
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: forceRefresh evicts the in-memory parsed-schema cache (cache #2)", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-schemacache-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const { primeSchemaCache, getSchema } = await import("../walker.js");
+
+			// Seed the in-memory parsed-schema cache under the instance URL key.
+			const sentinel = buildSchema("type Query { sentinel: Int }");
+			primeSchemaCache(INSTANCE_URL, sentinel);
+			expect(getSchema(INSTANCE_URL)).toBe(sentinel);
+
+			// A forced refresh must route clearSchemaCacheByUrl with the resolved
+			// instance URL, evicting the sentinel. After eviction, getSchema misses
+			// the cache and rebuilds from the freshly-written introspection on disk
+			// — so it returns a NEW schema object, never the seeded sentinel.
+			await primeSchemaWithLock("test-org", makeStubDeps(tmpRoot).deps, { forceRefresh: true });
+			expect(getSchema(INSTANCE_URL)).not.toBe(sentinel);
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: forceRefresh clears the ObjectInfo cache on success", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-oi-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const { setCachedObjectInfo, getCachedObjectInfo } = await import("../object-info.js");
+			const { deps } = makeStubDeps(tmpRoot);
+
+			await primeSchemaWithLock("test-org", deps); // prime first
+			setCachedObjectInfo("test-org", "Account", makeObjectInfo());
+			expect(getCachedObjectInfo("test-org", "Account")).not.toBeNull();
+
+			await primeSchemaWithLock("test-org", deps, { forceRefresh: true });
+			expect(getCachedObjectInfo("test-org", "Account")).toBeNull();
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: concurrent forceRefresh coalesces into a single download", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-coalesce-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+
+			// Pre-existing cache, backdated so the new download's mtime is strictly newer.
+			const fp = await writeSchemaFile(tmpRoot);
+			const past = new Date(Date.now() - 5_000);
+			fs.utimesSync(fp, past, past);
+
+			const { deps, calls } = makeStubDeps(tmpRoot, { delayMs: 200 });
+
+			const results = await Promise.all([
+				primeSchemaWithLock("test-org", deps, { forceRefresh: true }),
+				primeSchemaWithLock("test-org", deps, { forceRefresh: true }),
+			]);
+
+			// This test owns the *single-introspection* guarantee. That the coalesced
+			// (loser) caller still clears ITS OWN stale caches is proven separately by
+			// the R4 test below — here both callers share one alias, so a cache
+			// assertion couldn't distinguish the loser's clear from the winner's.
+			expect(calls()).toBe(1); // single introspection
+			const refreshedCount = results.filter((r) => r.refreshed).length;
+			expect(refreshedCount).toBe(1); // exactly one performed the refresh
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: sequential forceRefresh each re-download", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-seq-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const { deps, calls } = makeStubDeps(tmpRoot);
+
+			await primeSchemaWithLock("test-org", deps); // 1
+			await primeSchemaWithLock("test-org", deps, { forceRefresh: true }); // 2
+			await primeSchemaWithLock("test-org", deps, { forceRefresh: true }); // 3
+			expect(calls()).toBe(3);
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: a failed forceRefresh keeps the old caches and throws SchemaRefreshError", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-fail-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock, SchemaRefreshError } = await import("../prime-schema.js");
+
+			const fp = await writeSchemaFile(tmpRoot);
+			const originalContent = fs.readFileSync(fp, "utf-8");
+			const past = new Date(Date.now() - 5_000);
+			fs.utimesSync(fp, past, past);
+
+			// downloadSchema throws after the connection layer exhausts its
+			// timeout/retry. A forced refresh must keep every cache intact and
+			// surface a staleness-aware SchemaRefreshError.
+			const { deps, calls } = makeStubDeps(tmpRoot, {
+				throwOn: { 1: new Error("introspection failed") },
+			});
+
+			const err = await primeSchemaWithLock("test-org", deps, { forceRefresh: true }).catch(
+				(e) => e,
+			);
+			expect(err).toBeInstanceOf(SchemaRefreshError);
+			expect(err.staleSince).toBeTruthy(); // surviving cache age anchor
+			expect(err.instanceUrl).toBe(INSTANCE_URL);
+			expect(calls()).toBe(1); // primeSchemaWithLock calls downloadSchema once
+			expect(fs.readFileSync(fp, "utf-8")).toBe(originalContent); // old cache intact
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: a failed refresh with NO prior cache has no staleSince", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-nocache-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock, SchemaRefreshError } = await import("../prime-schema.js");
+
+			const { deps } = makeStubDeps(tmpRoot, {
+				throwOn: { 1: new Error("introspection failed") },
+			});
+
+			const err = await primeSchemaWithLock("test-org", deps, { forceRefresh: true }).catch(
+				(e) => e,
+			);
+			expect(err).toBeInstanceOf(SchemaRefreshError);
+			expect(err.staleSince).toBeUndefined();
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("primeSchemaWithLock: a coalesced refresh clears its OWN stale caches (R4, isolated from the winner)", async () => {
+		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-refresh-r4-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+		try {
+			const { primeSchemaWithLock } = await import("../prime-schema.js");
+			const { setCachedObjectInfo, getCachedObjectInfo } = await import("../object-info.js");
+
+			// Pre-existing cache, backdated so the winner's download is strictly newer.
+			const fp = await writeSchemaFile(tmpRoot);
+			const past = new Date(Date.now() - 5_000);
+			fs.utimesSync(fp, past, past);
+
+			// Two distinct aliases for the SAME org (instanceUrl). Seed ObjectInfo
+			// ONLY under the loser's alias: the winner's clearObjectInfoCache(winner)
+			// can never touch "loser:Account", so if it ends up null it was the
+			// loser's post-lock R4 block that cleared it — not the winner's success path.
+			setCachedObjectInfo("loser", "Account", makeObjectInfo());
+
+			let winnerDownloading = false;
+			const winnerDeps = {
+				getOrgAuth: async () => ({
+					alias: "winner",
+					instanceUrl: INSTANCE_URL,
+					accessToken: "t",
+					username: "u@e.com",
+					orgId: "00D",
+				}),
+				downloadSchema: async () => {
+					winnerDownloading = true;
+					await new Promise((r) => setTimeout(r, 200));
+					await writeSchemaFile(tmpRoot);
+					const { schemaCacheKeyForInstanceUrl } = await import("../introspect.js");
+					return {
+						cacheKey: schemaCacheKeyForInstanceUrl(INSTANCE_URL),
+						instanceUrl: INSTANCE_URL,
+						typeCount: 0,
+						downloadedAt: new Date().toISOString(),
+						filePath: fp,
+					};
+				},
+			};
+			let loserDownloads = 0;
+			const loserDeps = {
+				getOrgAuth: async () => ({
+					alias: "loser",
+					instanceUrl: INSTANCE_URL,
+					accessToken: "t",
+					username: "u@e.com",
+					orgId: "00D",
+				}),
+				downloadSchema: async () => {
+					loserDownloads++;
+					throw new Error("loser must coalesce, not download");
+				},
+			};
+
+			const winner = primeSchemaWithLock("winner", winnerDeps, { forceRefresh: true });
+			while (!winnerDownloading) await new Promise((r) => setTimeout(r, 5));
+			const loser = primeSchemaWithLock("loser", loserDeps, { forceRefresh: true });
+
+			const [, loserResult] = await Promise.all([winner, loser]);
+			expect(loserResult.refreshed).toBe(false); // coalesced
+			expect(loserResult.cached).toBe(true);
+			expect(loserDownloads).toBe(0); // never downloaded
+			expect(getCachedObjectInfo("loser", "Account")).toBeNull(); // cleared by R4, not the winner
+		} finally {
+			delete process.env.GRAPHITI_HOME;
+			fs.rmSync(tmpRoot, { recursive: true, force: true });
+		}
+	});
+
 	it("primeSchemaWithLock: awaits an async getOrgAuth and returns its instanceUrl", async () => {
 		const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-prime-async-"));
 		process.env.GRAPHITI_HOME = tmpRoot;

package/src/lib/__tests__/walker.spec.ts

@@ -22,6 +22,7 @@ import { createSession } from "../session.js";
 import { validateQuery } from "../validator.js";
 import {
 	clearSchemaCache,
+	clearSchemaCacheByUrl,
 	filterDataCloudFields,
 	type FieldInfo,
 	getSchema,
@@ -70,6 +71,18 @@ describe("walker", () => {
 			expect(() => selectLeafInSession(session2, "id")).not.toThrow();
 		});
 
+		it("clearSchemaCacheByUrl drops the URL-keyed entry", () => {
+			const instanceUrl = "https://refresh-test.my.salesforce.com";
+			primeSchemaCache(instanceUrl, TEST_SCHEMA);
+			// Cached: getSchema by URL returns the primed schema without touching disk.
+			expect(getSchema(instanceUrl)).toBe(TEST_SCHEMA);
+
+			clearSchemaCacheByUrl(instanceUrl);
+			// Evicted: the next read misses the in-memory cache and falls back to
+			// disk, which fails because no introspection file exists for this URL.
+			expect(() => getSchema(instanceUrl)).toThrow();
+		});
+
 		it("getSchema returns a primed schema by instance URL", () => {
 			const url = "https://example.my.salesforce.com";
 			clearSchemaCache();

package/src/lib/fs-utils.ts

@@ -23,16 +23,16 @@ export function graphitiHome(): string {
 }
 
 /**
- * Write JSON to `finalPath` atomically. Writes to a sibling
+ * Write `text` to `finalPath` atomically. Writes to a sibling
  * `<base>.tmp.<pid>.<timestamp>.<rand>` file, then renames over the final
  * path. Concurrent readers see either the old contents or the fully-written
  * new contents — never a partial. The temp file is unlinked if the rename
  * fails, so failure paths do not leak partial files.
  */
-export function atomicWriteJson(finalPath: string, payload: unknown): void {
+export function atomicWriteText(finalPath: string, text: string): void {
 	fs.mkdirSync(path.dirname(finalPath), { recursive: true });
 	const tmp = `${finalPath}.tmp.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString("hex")}`;
-	fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), "utf-8");
+	fs.writeFileSync(tmp, text, "utf-8");
 	try {
 		fs.renameSync(tmp, finalPath);
 	} catch (e) {
@@ -44,3 +44,8 @@ export function atomicWriteJson(finalPath: string, payload: unknown): void {
 		throw e;
 	}
 }
+
+/** Write JSON to `finalPath` atomically (pretty-printed). See {@link atomicWriteText}. */
+export function atomicWriteJson(finalPath: string, payload: unknown): void {
+	atomicWriteText(finalPath, JSON.stringify(payload, null, 2));
+}

package/src/lib/introspect.ts

@@ -24,6 +24,26 @@ async function getConnection(auth: OrgAuth): Promise<Connection> {
 	return org.getConnection();
 }
 
+// Per-request options for the introspection POST (W-22845606). `@salesforce/core`
+// passes these straight through to jsforce:
+//  - `timeout` bounds EACH attempt (jsforce defaults to 30 min) so a wedged gateway
+//    can't hang the schema-lock holder indefinitely. A single attempt (5 min) aborts
+//    before prime-schema's 7-min STALE_LOCK_MS, so the holder normally releases the
+//    lock before any waiter reclaims it. A timeout *plus* the retry below can run
+//    ~2x the timeout and exceed STALE_LOCK_MS — a waiter may then reclaim mid-retry
+//    and run a second introspection: benign, it degrades to the redundant-download
+//    case coalescing already tolerates (atomic writes keep the cache correct). A
+//    strict bound would require timeout × (maxRetries + 1) < STALE_LOCK_MS.
+//  - jsforce does NOT retry POST by default, so we opt this idempotent introspection
+//    read into one retry on transient HTTP/network failures (with jsforce's built-in
+//    exponential backoff). Network errnos (ECONNRESET/ETIMEDOUT/…) are covered by
+//    jsforce's default `errorCodes`.
+const INTROSPECTION_TIMEOUT_MS = 5 * 60_000;
+const INTROSPECTION_REQUEST_OPTIONS = {
+	timeout: INTROSPECTION_TIMEOUT_MS,
+	retry: { methods: ["POST"], maxRetries: 1, statusCodes: [420, 429, 500, 502, 503, 504] },
+};
+
 /** Resolves the directory holding cached introspection JSON files. */
 export function schemaDir(): string {
 	return path.join(graphitiHome(), "schemas");
@@ -243,12 +263,15 @@ export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
 	const connection = await getConnection(auth);
 	const url = `${auth.instanceUrl}/services/data/v${connection.getApiVersion()}/graphql`;
 
-	const rawResult = (await connection.request({
-		method: "POST",
-		url,
-		body: JSON.stringify({ query: INTROSPECTION_QUERY }),
-		headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
-	})) as any;
+	const rawResult = (await connection.request(
+		{
+			method: "POST",
+			url,
+			body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+			headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
+		},
+		INTROSPECTION_REQUEST_OPTIONS,
+	)) as any;
 
 	if (rawResult?.errors?.length) {
 		const messages = (rawResult.errors as any[])