Open History to see the last commit
1import {
2 FILESYSTEM_METADATA_BATCH_LIMIT,
3 type EnvironmentId,
4 type FilesystemEntryMetadata,
5 type ProjectEntry,
6 type ScopedThreadRef,
7 type ThreadId,
8 WS_METHODS,
9} from "@t3tools/contracts";
10import { normalizeProjectPathForComparison, resolveWorkspaceFilePath } from "@t3tools/shared/path";
11import * as Clock from "effect/Clock";
12import * as Effect from "effect/Effect";
13import * as Exit from "effect/Exit";
14import * as Option from "effect/Option";
15import * as Request from "effect/Request";
16import * as RequestResolver from "effect/RequestResolver";
17import * as SubscriptionRef from "effect/SubscriptionRef";
18import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
19
20import * as EnvironmentSupervisor from "../connection/supervisor.ts";
21import type { EnvironmentRegistry } from "../connection/registry.ts";
22import {
23 request,
24 type EnvironmentRpcFailure,
25 EnvironmentRpcUnavailableError,
26} from "../rpc/client.ts";
27import type { RpcSession } from "../rpc/session.ts";
28import { createEnvironmentQueryAtomFamily } from "./runtime.ts";
29
30const METADATA_STALE_TIME_MS = 60_000;
31const METADATA_CACHE_LIMIT = 1024;
32
33interface CachedMetadata {
34 value: FilesystemEntryMetadata | null;
35 expires: number;
36}
37
38type RetainedMetadata = Map<string, CachedMetadata>;
39
40interface FileMetadataInput {
41 path: string;
42 threadId?: ThreadId;
43}
44
45class FileMetadataRequest extends Request.Class<
46 {
47 path: string;
48 session: RpcSession;
49 supervisor: EnvironmentSupervisor.EnvironmentSupervisor["Service"];
50 retained?: RetainedMetadata;
51 },
52 FilesystemEntryMetadata | null,
53 EnvironmentRpcFailure<typeof WS_METHODS.filesystemGetMetadata> | EnvironmentRpcUnavailableError
54> {}
55
56export function createFileMetadataAtoms<R, E>(
57 runtime: Atom.AtomRuntime<EnvironmentRegistry | R, E>,
58) {
59 const cache = new WeakMap<RpcSession, Map<string, CachedMetadata>>();
60 const invalidationVersions = new WeakMap<RpcSession, number>();
61 const inFlight = new WeakMap<RpcSession, Map<string, Set<{ valid: boolean }>>>();
62 const retainedThreads = new Map<
63 string,
64 { readers: number; sessions: WeakMap<RpcSession, RetainedMetadata> }
65 >();
66 const threadKey = (ref: ScopedThreadRef) => JSON.stringify([ref.environmentId, ref.threadId]);
67 const retainThreadFamily = Atom.family((key: string) =>
68 Atom.make((get) => {
69 let retained = retainedThreads.get(key);
70 if (!retained) {
71 retained = { readers: 0, sessions: new WeakMap() };
72 retainedThreads.set(key, retained);
73 }
74 retained.readers++;
75 get.addFinalizer(() => {
76 if (--retained.readers === 0) retainedThreads.delete(key);
77 });
78 }).pipe(Atom.setIdleTTL(0), Atom.withLabel(`file-metadata-thread:${key}`)),
79 );
80 const revisions = Atom.family((key: string) =>
81 Atom.make(0).pipe(Atom.withLabel(`file-metadata-revision:${key}`)),
82 );
83 const revision = (environmentId: EnvironmentId, path: string) =>
84 revisions(JSON.stringify([environmentId, normalizeProjectPathForComparison(path)]));
85 const knownEntry = (session: RpcSession, path: string, now: number) => {
86 const key = normalizeProjectPathForComparison(path);
87 const cached = cache.get(session)?.get(key);
88 return cached && cached.expires > now ? cached : undefined;
89 };
90 const remember = (
91 session: RpcSession,
92 path: string,
93 value: FilesystemEntryMetadata | null,
94 now: number,
95 partial = false,
96 ) => {
97 let entries = cache.get(session);
98 if (!entries) {
99 entries = new Map();
100 cache.set(session, entries);
101 }
102 const key = normalizeProjectPathForComparison(path);
103 entries.delete(key);
104 const entry = { value, expires: now + METADATA_STALE_TIME_MS };
105 entries.set(key, entry);
106 for (const thread of retainedThreads.values()) {
107 const retained = thread.sessions.get(session);
108 const previous = retained?.get(key);
109 if (retained && previous)
110 retained.set(key, {
111 ...entry,
112 value:
113 partial && value && previous.value?.kind === value.kind
114 ? { ...previous.value, ...value }
115 : value,
116 });
117 }
118 if (entries.size > METADATA_CACHE_LIMIT) {
119 const oldest = entries.keys().next().value;
120 if (oldest !== undefined) entries.delete(oldest);
121 }
122 };
123 const resolver = RequestResolver.makeWith<FileMetadataRequest>({
124 batchKey: (entry) => entry.request.session,
125 delay: Effect.yieldNow,
126 collectWhile: (entries) => entries.size < FILESYSTEM_METADATA_BATCH_LIMIT,
127 runAll: Effect.fnUntraced(function* (entries) {
128 const session = entries[0].request.session;
129 let pending = [...entries];
130 while (pending.length > 0) {
131 const paths = [...new Set(pending.map((entry) => entry.request.path))];
132 let requests = inFlight.get(session);
133 if (!requests) {
134 requests = new Map();
135 inFlight.set(session, requests);
136 }
137 const tokens = new Map(paths.map((path) => [path, { valid: true }]));
138 for (const [path, token] of tokens) {
139 let active = requests.get(path);
140 if (!active) requests.set(path, (active = new Set()));
141 active.add(token);
142 }
143 const activeRequests = requests;
144 pending = yield* Effect.gen(function* () {
145 const result = yield* request(WS_METHODS.filesystemGetMetadata, { paths }).pipe(
146 Effect.provideService(
147 EnvironmentSupervisor.EnvironmentSupervisor,
148 entries[0].request.supervisor,
149 ),
150 );
151 const now = yield* Clock.currentTimeMillis;
152 const byPath = new Map(paths.map((path, index) => [path, result.entries[index] ?? null]));
153 const retry: typeof pending = [];
154 for (const entry of pending) {
155 // Retry only paths invalidated during this request. Never retain the
156 // old response or complete a waiting chip with pre-write metadata.
157 if (!tokens.get(entry.request.path)!.valid) {
158 retry.push(entry);
159 continue;
160 }
161 const value = byPath.get(entry.request.path) ?? null;
162 remember(session, entry.request.path, value, now);
163 entry.request.retained?.set(entry.request.path, {
164 value,
165 expires: now + METADATA_STALE_TIME_MS,
166 });
167 entry.completeUnsafe(Exit.succeed(value));
168 }
169 return retry;
170 }).pipe(
171 Effect.ensuring(
172 Effect.sync(() => {
173 for (const [path, token] of tokens) {
174 const active = activeRequests.get(path);
175 active?.delete(token);
176 if (active?.size === 0) activeRequests.delete(path);
177 }
178 }),
179 ),
180 );
181 }
182 }),
183 });
184
185 const metadataFamily = createEnvironmentQueryAtomFamily(runtime, {
186 label: "environment-data:filesystem:metadata",
187 staleTimeMs: METADATA_STALE_TIME_MS,
188 idleTtlMs: METADATA_STALE_TIME_MS,
189 execute: Effect.fnUntraced(function* (input: FileMetadataInput) {
190 const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
191 const session = yield* SubscriptionRef.get(supervisor.session);
192 if (session._tag === "None") return null;
193 const thread = input.threadId
194 ? retainedThreads.get(
195 threadKey({ environmentId: supervisor.target.environmentId, threadId: input.threadId }),
196 )
197 : undefined;
198 let retained = thread?.sessions.get(session.value);
199 if (thread && !retained) {
200 retained = new Map();
201 thread.sessions.set(session.value, retained);
202 }
203 const retainedEntry = retained?.get(input.path);
204 const now = yield* Clock.currentTimeMillis;
205 // Agents mention paths before creating them, so misses must still expire within a thread.
206 if (retainedEntry && (retainedEntry.value !== null || retainedEntry.expires > now))
207 return retainedEntry.value;
208 const cached = knownEntry(session.value, input.path, now);
209 if (cached) {
210 retained?.set(input.path, cached);
211 return cached.value;
212 }
213 return yield* Effect.request(
214 new FileMetadataRequest({
215 path: input.path,
216 session: session.value,
217 supervisor,
218 ...(retained ? { retained } : {}),
219 }),
220 resolver,
221 );
222 }),
223 refreshTrigger: ({
224 environmentId,
225 input,
226 }: {
227 environmentId: EnvironmentId;
228 input: FileMetadataInput;
229 }) => revision(environmentId, input.path),
230 });
231 const refreshMissing = Atom.family((query: ReturnType<typeof metadataFamily>) => {
232 const retry = query.pipe(Atom.withRefresh(METADATA_STALE_TIME_MS), Atom.setIdleTTL(0));
233 return Atom.transform(
234 query,
235 (get) => {
236 const result = get(query);
237 return Option.exists(AsyncResult.value(result), (value) => value === null)
238 ? get(retry)
239 : result;
240 },
241 { initialValueTarget: query },
242 ).pipe(Atom.setIdleTTL(0));
243 });
244 const metadata = (target: {
245 environmentId: EnvironmentId;
246 input: { path: string; threadId?: ThreadId };
247 }) =>
248 refreshMissing(
249 metadataFamily({
250 ...target,
251 input: { ...target.input, path: normalizeProjectPathForComparison(target.input.path) },
252 }),
253 );
254
255 const rememberEntries = Effect.fnUntraced(function* (
256 cwd: string,
257 entries: ReadonlyArray<ProjectEntry>,
258 isCurrent?: (session: RpcSession) => boolean,
259 ) {
260 const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
261 const session = yield* SubscriptionRef.get(supervisor.session);
262 if (session._tag === "None") return;
263 const now = yield* Clock.currentTimeMillis;
264 if (isCurrent && !isCurrent(session.value)) return;
265 for (const entry of entries) {
266 const path = resolveWorkspaceFilePath(entry.path, cwd);
267 const previous = knownEntry(session.value, path, now);
268 if (previous?.value?.kind === entry.kind) continue;
269 remember(session.value, path, { kind: entry.kind }, now, true);
270 }
271 });
272
273 const invalidate = Effect.fnUntraced(function* (path: string) {
274 const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
275 const session = yield* SubscriptionRef.get(supervisor.session);
276 if (session._tag === "Some") {
277 invalidationVersions.set(session.value, (invalidationVersions.get(session.value) ?? 0) + 1);
278 const key = normalizeProjectPathForComparison(path);
279 for (const token of inFlight.get(session.value)?.get(key) ?? []) token.valid = false;
280 cache.get(session.value)?.delete(key);
281 for (const thread of retainedThreads.values())
282 thread.sessions.get(session.value)?.delete(normalizeProjectPathForComparison(path));
283 }
284 });
285
286 const rememberFile = Effect.fnUntraced(function* (
287 cwd: string,
288 file: { relativePath: string; byteLength: number },
289 isCurrent?: (session: RpcSession) => boolean,
290 ) {
291 const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
292 const session = yield* SubscriptionRef.get(supervisor.session);
293 if (session._tag === "None") return;
294 const path = resolveWorkspaceFilePath(file.relativePath, cwd);
295 const now = yield* Clock.currentTimeMillis;
296 if (isCurrent && !isCurrent(session.value)) return;
297 const previous = knownEntry(session.value, path, now)?.value;
298 remember(
299 session.value,
300 path,
301 {
302 ...previous,
303 kind: "file",
304 byteLength: file.byteLength,
305 },
306 now,
307 true,
308 );
309 });
310
311 const seedAfterRead =
312 /* Metadata seeding runs on every file read and is covered by the read operation. */
313 Effect.fnUntraced(function* <A, ReadError, ReadServices>(
314 read: Effect.Effect<A, ReadError, ReadServices>,
315 seed: (
316 result: A,
317 isCurrent: (session: RpcSession) => boolean,
318 ) => Effect.Effect<void, never, EnvironmentSupervisor.EnvironmentSupervisor>,
319 ) {
320 const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
321 const session = yield* SubscriptionRef.get(supervisor.session);
322 const version = session._tag === "Some" ? (invalidationVersions.get(session.value) ?? 0) : 0;
323 const result = yield* read;
324 // Seeding is optional. Any intervening invalidation or reconnect makes
325 // the old response unsuitable for the current metadata cache.
326 yield* seed(
327 result,
328 (current) =>
329 session._tag === "Some" &&
330 current === session.value &&
331 (invalidationVersions.get(current) ?? 0) === version,
332 );
333 return result;
334 });
335
336 const refreshPath = (
337 environmentId: EnvironmentId,
338 path: string,
339 registry: AtomRegistry.AtomRegistry,
340 ) => {
341 const signal = revision(environmentId, path);
342 registry.set(signal, registry.get(signal) + 1);
343 };
344
345 return {
346 metadata,
347 retainThread: (ref: ScopedThreadRef) => retainThreadFamily(threadKey(ref)),
348 rememberEntries,
349 rememberFile,
350 seedAfterRead,
351 invalidate,
352 refreshPath,
353 };
354}