sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Auth/ Lock.ts

import * as Clock from "effect/Clock";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schedule from "effect/Schedule";
import * as Semaphore from "effect/Semaphore";
import { rootDir } from "./Paths.ts";

const semaphores = new Map<string, Semaphore.Semaphore>();

// Keep STALE well above REFRESH — a saturated machine can starve the
// heartbeat fiber for seconds.
const STALE = Duration.seconds(30);
const REFRESH = Duration.seconds(10);
const RETRY_INTERVAL = Duration.millis(50);
const DEFAULT_TIMEOUT = Duration.minutes(2);
// How often to remind the user that a lock wait / locked operation is still
// outstanding. Long enough that healthy runs never print it.
const STALL_INTERVAL = Duration.seconds(30);

class LockHeld extends Data.TaggedError("LockHeld") {}

class LockTimeout extends Data.TaggedError("LockTimeout")<{
  readonly lockPath: string;
  readonly timeout: Duration.Input;
  readonly message: string;
}> {}

/**
 * Make a lock key safe to use as a file name on every platform.
 *
 * Keys are derived from user-controlled values (profile names), which
 * have shown up in production containing shell placeholders like
 * `${ALCHEMY_PROFILE:-default}` — `:`/`{`/`

	
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
	.repos/alchemy-effect/packages/alchemy/src/Auth/Lock.ts at main · sailfork/t3code-github · Sailfork
	
		
are invalid in Windows * file names and mkdir fails with EINVAL. Collapse anything outside a * conservative allow-list to `_`. * * @internal exported for unit testing. */ export const sanitizeLockKey = (key: string): string => key.replace(/[^A-Za-z0-9._-]/g, "_"); /** * Take the cross-process lock. On success the ambient scope owns it: a * finalizer removes it and a forked heartbeat keeps its mtime fresh. */ const acquireFileLock = Effect.fn(function* (lockPath: string, timeout: Duration.Input) { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; const ownerPath = path.join(lockPath, "owner"); const owner = yield* Effect.sync(() => crypto.randomUUID()); yield* fs.makeDirectory(path.dirname(lockPath), { recursive: true }); // Reap a lock whose crashed holder stopped refreshing its mtime. const reapStale = Effect.gen(function* () { const info = yield* fs.stat(lockPath); const now = yield* Clock.currentTimeMillis; const isStale = Option.exists( info.mtime, (mtime) => mtime.getTime() < now - Duration.toMillis(STALE), ); if (isStale) { yield* fs.remove(lockPath, { recursive: true, force: true }); } }).pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.void)); // A non-recursive mkdir is the atomic test-and-set; the owner marker lets // release and refresh verify the lock wasn't reaped and re-taken. yield* Effect.acquireRelease( fs .makeDirectory(lockPath) .pipe( Effect.andThen( fs .writeFileString(ownerPath, owner) .pipe( Effect.onError(() => fs.remove(lockPath, { recursive: true, force: true }).pipe(Effect.ignore), ), ), ), ), () => fs.readFileString(ownerPath).pipe( Effect.filterOrFail((current) => current === owner), Effect.andThen(fs.remove(lockPath, { recursive: true, force: true })), Effect.ignore, ), ).pipe( Effect.catchReason("PlatformError", "AlreadyExists", () => reapStale.pipe(Effect.andThen(Effect.fail(new LockHeld()))), ), Effect.retry({ while: (error) => error._tag === "LockHeld", schedule: Schedule.spaced(RETRY_INTERVAL).pipe(Schedule.upTo({ duration: timeout })), }), Effect.catchTag("LockHeld", () => Effect.die( new LockTimeout({ lockPath, timeout, message: `Timed out waiting for the alchemy auth lock '${lockPath}' — another alchemy ` + `process has held it for over ${Duration.toSeconds(timeout)}s. If no other ` + `alchemy process is running, delete the lock directory and retry.`, }), ), ), ); yield* fs.readFileString(ownerPath).pipe( Effect.filterOrFail((current) => current === owner), Effect.andThen(Clock.currentTimeMillis.pipe(Effect.map((now) => new Date(now)))), // NB: utimes interprets a bare number as *seconds* since epoch. Effect.flatMap((now) => fs.utimes(lockPath, now, now)), Effect.repeat(Schedule.spaced(REFRESH)), Effect.catch(() => Effect.logWarning( `auth lock compromised (continuing): '${lockPath}' is no longer owned by this process`, ), ), // Acquisition returns while this fiber refreshes until the lock scope ends. Effect.forkScoped, ); }); type Phase = { current: "waiting" | "held" }; /** * Periodic "I am not dead, I am stuck here" notice, forked for the lifetime * of a {@link withLock} call. * Logged as a warning: the console logger shows it above the noise floor * (telemetry merges with it rather than replacing it), and JSON output and * the run log carry it too. */ const stallNotice = (lockPath: string, label: string, phase: Phase, interval: Duration.Input) => Effect.gen(function* () { const start = yield* Clock.currentTimeMillis; const notice = Effect.gen(function* () { // Report real elapsed time, not an accumulated interval count — the // notice cadence and the reported wait must not drift apart. const now = yield* Clock.currentTimeMillis; const seconds = Math.round((now - start) / 1000); yield* Effect.logWarning( phase.current === "waiting" ? `alchemy: ${seconds}s waiting for the auth lock '${lockPath}' (${label}). ` + `Another alchemy process holds it; if none is running, delete that directory.` : `alchemy: ${label} has been running for ${seconds}s while holding the auth lock ` + `'${lockPath}'. Re-run with --log-level debug for detail.`, ); }); // `Effect.schedule` (unlike `Effect.repeat`) consults the schedule // before the first run, and `Schedule.fixed`'s first recurrence comes // after one full interval — so notices fire at interval, 2*interval, … // on true wall-clock boundaries. yield* Effect.schedule(notice, Schedule.fixed(interval)); }); /** * Serialise execution of `effect` for the same `key`, both within this * process (a semaphore) and across processes on the same machine (an atomic * lock directory whose mtime is refreshed while held so another process can * recover it after a crash). * * Failure to create or acquire the lock is fatal. Authentication writes its * profile state beneath the same root, so continuing without a writable lock * cannot produce a valid deployment and would permit concurrent corruption. */ export const withLock = <A, E, R>( key: string, effect: Effect.Effect<A, E, R>, options?: { readonly timeout?: Duration.Input; /** * Human-readable name of the work being serialised, used in the debug * log lines and the stall notice. Defaults to `key`. */ readonly label?: string; /** * Print a periodic notice to stderr while this lock is being waited on * or held (see {@link stallNotice}). Pass `false` for flows that * legitimately block on the user — a browser OAuth round-trip, an * `aws sso login` child process — where a repeating notice would be * both wrong and destructive to the prompt on screen. * * @default true */ readonly watchdog?: boolean; /** * Interval between stall notices. * * @internal exposed so tests need not wait 30 real seconds. */ readonly stallInterval?: Duration.Input; }, ) => { const safeKey = sanitizeLockKey(key); const label = options?.label ?? key; let semaphore = semaphores.get(safeKey); if (semaphore === undefined) { semaphore = Semaphore.makeUnsafe(1); semaphores.set(safeKey, semaphore); } return semaphore.withPermit( Effect.gen(function* () { const path = yield* Path.Path; const lockPath = path.join(rootDir(), "lock", `${safeKey}.lock`); const phase: Phase = { current: "waiting" }; if (options?.watchdog !== false) { yield* Effect.forkScoped( stallNotice(lockPath, label, phase, options?.stallInterval ?? STALL_INTERVAL), ); } yield* Effect.logDebug(`auth lock: acquiring '${lockPath}' for ${label}`); yield* acquireFileLock(lockPath, options?.timeout ?? DEFAULT_TIMEOUT).pipe(Effect.orDie); phase.current = "held"; yield* Effect.logDebug(`auth lock: acquired '${lockPath}' for ${label}`); return yield* effect.pipe( Effect.onExit(() => Effect.logDebug(`auth lock: releasing '${lockPath}' for ${label}`)), ); }).pipe(Effect.scoped), ); }; /** * Serialize an operation with every credential mutation for a profile. The * lock key is shared by every credential operation for the profile, * including profile-wide rename and delete operations. */ export const withProfileCredentialsLock = <A, E, R>( profileName: string, effect: Effect.Effect<A, E, R>, ) => withLock(`profile-credentials-${profileName}`, effect);
.repos/alchemy-effect/packages/alchemy/src/Auth/Lock.ts at main · sailfork/t3code-github · Sailfork
are invalid in Windows\n * file names and mkdir fails with EINVAL. Collapse anything outside a\n * conservative allow-list to `_`.\n *\n * @internal exported for unit testing.\n */\nexport const sanitizeLockKey = (key: string): string => key.replace(/[^A-Za-z0-9._-]/g, \"_\");\n\n/**\n * Take the cross-process lock. On success the ambient scope owns it: a\n * finalizer removes it and a forked heartbeat keeps its mtime fresh.\n */\nconst acquireFileLock = Effect.fn(function* (lockPath: string, timeout: Duration.Input) {\n const fs = yield* FileSystem.FileSystem;\n const path = yield* Path.Path;\n const ownerPath = path.join(lockPath, \"owner\");\n const owner = yield* Effect.sync(() => crypto.randomUUID());\n\n yield* fs.makeDirectory(path.dirname(lockPath), { recursive: true });\n\n // Reap a lock whose crashed holder stopped refreshing its mtime.\n const reapStale = Effect.gen(function* () {\n const info = yield* fs.stat(lockPath);\n const now = yield* Clock.currentTimeMillis;\n const isStale = Option.exists(\n info.mtime,\n (mtime) => mtime.getTime() \u003c now - Duration.toMillis(STALE),\n );\n if (isStale) {\n yield* fs.remove(lockPath, { recursive: true, force: true });\n }\n }).pipe(Effect.catchReason(\"PlatformError\", \"NotFound\", () => Effect.void));\n\n // A non-recursive mkdir is the atomic test-and-set; the owner marker lets\n // release and refresh verify the lock wasn't reaped and re-taken.\n yield* Effect.acquireRelease(\n fs\n .makeDirectory(lockPath)\n .pipe(\n Effect.andThen(\n fs\n .writeFileString(ownerPath, owner)\n .pipe(\n Effect.onError(() =>\n fs.remove(lockPath, { recursive: true, force: true }).pipe(Effect.ignore),\n ),\n ),\n ),\n ),\n () =>\n fs.readFileString(ownerPath).pipe(\n Effect.filterOrFail((current) => current === owner),\n Effect.andThen(fs.remove(lockPath, { recursive: true, force: true })),\n Effect.ignore,\n ),\n ).pipe(\n Effect.catchReason(\"PlatformError\", \"AlreadyExists\", () =>\n reapStale.pipe(Effect.andThen(Effect.fail(new LockHeld()))),\n ),\n Effect.retry({\n while: (error) => error._tag === \"LockHeld\",\n schedule: Schedule.spaced(RETRY_INTERVAL).pipe(Schedule.upTo({ duration: timeout })),\n }),\n Effect.catchTag(\"LockHeld\", () =>\n Effect.die(\n new LockTimeout({\n lockPath,\n timeout,\n message:\n `Timed out waiting for the alchemy auth lock '${lockPath}' — another alchemy ` +\n `process has held it for over ${Duration.toSeconds(timeout)}s. If no other ` +\n `alchemy process is running, delete the lock directory and retry.`,\n }),\n ),\n ),\n );\n\n yield* fs.readFileString(ownerPath).pipe(\n Effect.filterOrFail((current) => current === owner),\n Effect.andThen(Clock.currentTimeMillis.pipe(Effect.map((now) => new Date(now)))),\n // NB: utimes interprets a bare number as *seconds* since epoch.\n Effect.flatMap((now) => fs.utimes(lockPath, now, now)),\n Effect.repeat(Schedule.spaced(REFRESH)),\n Effect.catch(() =>\n Effect.logWarning(\n `auth lock compromised (continuing): '${lockPath}' is no longer owned by this process`,\n ),\n ),\n // Acquisition returns while this fiber refreshes until the lock scope ends.\n Effect.forkScoped,\n );\n});\n\ntype Phase = { current: \"waiting\" | \"held\" };\n\n/**\n * Periodic \"I am not dead, I am stuck here\" notice, forked for the lifetime\n * of a {@link withLock} call.\n * Logged as a warning: the console logger shows it above the noise floor\n * (telemetry merges with it rather than replacing it), and JSON output and\n * the run log carry it too.\n */\nconst stallNotice = (lockPath: string, label: string, phase: Phase, interval: Duration.Input) =>\n Effect.gen(function* () {\n const start = yield* Clock.currentTimeMillis;\n const notice = Effect.gen(function* () {\n // Report real elapsed time, not an accumulated interval count — the\n // notice cadence and the reported wait must not drift apart.\n const now = yield* Clock.currentTimeMillis;\n const seconds = Math.round((now - start) / 1000);\n yield* Effect.logWarning(\n phase.current === \"waiting\"\n ? `alchemy: ${seconds}s waiting for the auth lock '${lockPath}' (${label}). ` +\n `Another alchemy process holds it; if none is running, delete that directory.`\n : `alchemy: ${label} has been running for ${seconds}s while holding the auth lock ` +\n `'${lockPath}'. Re-run with --log-level debug for detail.`,\n );\n });\n // `Effect.schedule` (unlike `Effect.repeat`) consults the schedule\n // before the first run, and `Schedule.fixed`'s first recurrence comes\n // after one full interval — so notices fire at interval, 2*interval, …\n // on true wall-clock boundaries.\n yield* Effect.schedule(notice, Schedule.fixed(interval));\n });\n\n/**\n * Serialise execution of `effect` for the same `key`, both within this\n * process (a semaphore) and across processes on the same machine (an atomic\n * lock directory whose mtime is refreshed while held so another process can\n * recover it after a crash).\n *\n * Failure to create or acquire the lock is fatal. Authentication writes its\n * profile state beneath the same root, so continuing without a writable lock\n * cannot produce a valid deployment and would permit concurrent corruption.\n */\nexport const withLock = \u003cA, E, R>(\n key: string,\n effect: Effect.Effect\u003cA, E, R>,\n options?: {\n readonly timeout?: Duration.Input;\n /**\n * Human-readable name of the work being serialised, used in the debug\n * log lines and the stall notice. Defaults to `key`.\n */\n readonly label?: string;\n /**\n * Print a periodic notice to stderr while this lock is being waited on\n * or held (see {@link stallNotice}). Pass `false` for flows that\n * legitimately block on the user — a browser OAuth round-trip, an\n * `aws sso login` child process — where a repeating notice would be\n * both wrong and destructive to the prompt on screen.\n *\n * @default true\n */\n readonly watchdog?: boolean;\n /**\n * Interval between stall notices.\n *\n * @internal exposed so tests need not wait 30 real seconds.\n */\n readonly stallInterval?: Duration.Input;\n },\n) => {\n const safeKey = sanitizeLockKey(key);\n const label = options?.label ?? key;\n let semaphore = semaphores.get(safeKey);\n if (semaphore === undefined) {\n semaphore = Semaphore.makeUnsafe(1);\n semaphores.set(safeKey, semaphore);\n }\n return semaphore.withPermit(\n Effect.gen(function* () {\n const path = yield* Path.Path;\n const lockPath = path.join(rootDir(), \"lock\", `${safeKey}.lock`);\n const phase: Phase = { current: \"waiting\" };\n if (options?.watchdog !== false) {\n yield* Effect.forkScoped(\n stallNotice(lockPath, label, phase, options?.stallInterval ?? STALL_INTERVAL),\n );\n }\n yield* Effect.logDebug(`auth lock: acquiring '${lockPath}' for ${label}`);\n yield* acquireFileLock(lockPath, options?.timeout ?? DEFAULT_TIMEOUT).pipe(Effect.orDie);\n phase.current = \"held\";\n yield* Effect.logDebug(`auth lock: acquired '${lockPath}' for ${label}`);\n return yield* effect.pipe(\n Effect.onExit(() => Effect.logDebug(`auth lock: releasing '${lockPath}' for ${label}`)),\n );\n }).pipe(Effect.scoped),\n );\n};\n\n/**\n * Serialize an operation with every credential mutation for a profile. The\n * lock key is shared by every credential operation for the profile,\n * including profile-wide rename and delete operations.\n */\nexport const withProfileCredentialsLock = \u003cA, E, R>(\n profileName: string,\n effect: Effect.Effect\u003cA, E, R>,\n) => withLock(`profile-credentials-${profileName}`, effect);\n","preview":null,"history":null,"version":"c1e85df021465796ed6db8c24ee0cf5c540a14b5"},"/_session?shell=1":null}