From a5460dbe41a2fc114fbca629e9c5ca2e9f94b17d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 26 Oct 2026 17:52:30 +0800 Subject: [PATCH] fix(forge): preserve refresh requests during active polling --- docs/subsystems/forge.md | 4 +-- docs/subsystems/forge.zh.md | 4 +-- packages/experimental/forge/README.i18n.yaml | 4 +-- packages/experimental/forge/README.md | 2 +- packages/experimental/forge/README.zh.md | 2 +- packages/experimental/forge/src/index.ts | 13 +++++---- .../experimental/forge/tests/watch.spec.ts | 29 +++++++++++++++++-- .../extensions/tool-cordis/src/api-catalog.ts | 2 +- 8 files changed, 42 insertions(+), 18 deletions(-) diff --git a/docs/subsystems/forge.md b/docs/subsystems/forge.md index 36394cf999..5bfd4b09d9 100644 --- a/docs/subsystems/forge.md +++ b/docs/subsystems/forge.md @@ -699,8 +699,8 @@ watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void /** * Poll a watched change request at once, including after a terminal state. - * A fetch already in flight for its forge serves the request; an unwatched - * change request is unchanged. + * A fetch already in flight is followed immediately by another fetch; an + * unwatched change request is unchanged. * @param ref - change request to poll. */ refresh(ref: ChangeRequestRef): void diff --git a/docs/subsystems/forge.zh.md b/docs/subsystems/forge.zh.md index 4d36a7a551..a21212cae8 100644 --- a/docs/subsystems/forge.zh.md +++ b/docs/subsystems/forge.zh.md @@ -699,8 +699,8 @@ watch(ref: ChangeRequestRef, listener: ChangeRequestListener): () => void /** * Poll a watched change request at once, including after a terminal state. - * A fetch already in flight for its forge serves the request; an unwatched - * change request is unchanged. + * A fetch already in flight is followed immediately by another fetch; an + * unwatched change request is unchanged. * @param ref - change request to poll. */ refresh(ref: ChangeRequestRef): void diff --git a/packages/experimental/forge/README.i18n.yaml b/packages/experimental/forge/README.i18n.yaml index 74bbc2a3a3..a2726e977d 100644 --- a/packages/experimental/forge/README.i18n.yaml +++ b/packages/experimental/forge/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 2f8a621b991260a1 /deepseek-ai-dsh-experimental-forge/use-this-package: - en: 396c0c1d508fa12a - zh: 136efa3ad502420c + en: a92423ce03ea1b83 + zh: f90d8784b715996e /deepseek-ai-dsh-experimental-forge/understand-the-implementation: en: e193cb547c47069b zh: faa517522402ea41 diff --git a/packages/experimental/forge/README.md b/packages/experimental/forge/README.md index c5d4cc0a01..a7e25803f3 100644 --- a/packages/experimental/forge/README.md +++ b/packages/experimental/forge/README.md @@ -38,7 +38,7 @@ Mount the registry with at least one provider package, such as the GitHub provid `diff(ref, signal)` reads the change request's unified patch as the host computes it, with `a/` and `b/` path prefixes, and `fileText(ref, commit, path, signal)` reads one file of its repository at a commit. Both delegate to the provider of the reference's forge, throw when none is registered, and resolve to the text or to a `ForgeFailure`, which is `too-large` when the host or the provider refuses an answer over its size limit. `fileUrl(ref, commit, path)` returns the web page of that file at that commit. -`ctx.forge.watch(ref, listener)` is also an effect. The first watcher of a change request polls it at once; `latest(ref)` returns the most recent result. Each forge has at most one fetch in flight, and that fetch includes every due change request of the forge. An open change request is polled every `activeIntervalMs` while checks are pending or mergeability is unknown, and every `idleIntervalMs` otherwise. Closed and merged change requests are not polled again. `refresh(ref)` polls a watched change request at once, including after a terminal state; a fetch already in flight for its forge serves the request. A failed read repeats after `activeIntervalMs` doubled for each consecutive failure, up to `maxBackoffMs`. A fetch that exceeds `fetchTimeoutMs` settles as an `unavailable` failure whose message names `FORGE_FETCH_TIMEOUT`. Unregistering a provider settles its watched change requests as `unavailable`. Polling stops when the last watcher leaves. The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge) lists the defaults. +`ctx.forge.watch(ref, listener)` is also an effect. The first watcher of a change request polls it at once; `latest(ref)` returns the most recent result. Each forge has at most one fetch in flight, and that fetch includes every due change request of the forge. An open change request is polled every `activeIntervalMs` while checks are pending or mergeability is unknown, and every `idleIntervalMs` otherwise. Closed and merged change requests are not polled again. `refresh(ref)` polls a watched change request at once, including after a terminal state; if a fetch is already in flight for its forge, another fetch starts immediately after it settles. A failed read repeats after `activeIntervalMs` doubled for each consecutive failure, up to `maxBackoffMs`. A fetch that exceeds `fetchTimeoutMs` settles as an `unavailable` failure whose message names `FORGE_FETCH_TIMEOUT`. Unregistering a provider settles its watched change requests as `unavailable`. Polling stops when the last watcher leaves. The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge) lists the defaults. ----- diff --git a/packages/experimental/forge/README.zh.md b/packages/experimental/forge/README.zh.md index 1115048c81..101d584990 100644 --- a/packages/experimental/forge/README.zh.md +++ b/packages/experimental/forge/README.zh.md @@ -38,7 +38,7 @@ kind: "package-reference" `diff(ref, signal)` 读取托管平台计算出的变更请求统一补丁,路径带 `a/` 与 `b/` 前缀;`fileText(ref, commit, path, signal)` 读取其仓库中某个提交下的一个文件。两者都委托给引用所属 forge 的提供方,没有注册提供方时抛错,resolve 为文本或 `ForgeFailure`;托管平台或提供方因结果超过其大小上限而拒绝时,失败为 `too-large`。`fileUrl(ref, commit, path)` 返回该文件在该提交下的网页地址。 -`ctx.forge.watch(ref, listener)` 同样是 effect。变更请求的第一个监听方会立即触发轮询;`latest(ref)` 返回最近一次结果。每个 forge 同时最多只有一次读取在进行,这次读取包含该 forge 所有到期的变更请求。打开状态的变更请求在检查未完成或可合并性未知时每 `activeIntervalMs` 轮询一次,否则每 `idleIntervalMs` 轮询一次。已关闭和已合并的变更请求不再轮询。`refresh(ref)` 立即轮询一个被监听的变更请求,已结束的也包括在内;该 forge 已有读取在进行时,由这次读取满足请求。读取失败后,重试间隔为 `activeIntervalMs` 按连续失败次数翻倍,最长 `maxBackoffMs`。读取超过 `fetchTimeoutMs` 时,以消息中包含 `FORGE_FETCH_TIMEOUT` 的 `unavailable` 失败结束。注销提供方会让其被监听的变更请求以 `unavailable` 结束。最后一个监听方离开后轮询停止。默认值见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge)。 +`ctx.forge.watch(ref, listener)` 同样是 effect。变更请求的第一个监听方会立即触发轮询;`latest(ref)` 返回最近一次结果。每个 forge 同时最多只有一次读取在进行,这次读取包含该 forge 所有到期的变更请求。打开状态的变更请求在检查未完成或可合并性未知时每 `activeIntervalMs` 轮询一次,否则每 `idleIntervalMs` 轮询一次。已关闭和已合并的变更请求不再轮询。`refresh(ref)` 立即轮询一个被监听的变更请求,已结束的也包括在内;该 forge 已有读取在进行时,等待其结束后立即再读一次。读取失败后,重试间隔为 `activeIntervalMs` 按连续失败次数翻倍,最长 `maxBackoffMs`。读取超过 `fetchTimeoutMs` 时,以消息中包含 `FORGE_FETCH_TIMEOUT` 的 `unavailable` 失败结束。注销提供方会让其被监听的变更请求以 `unavailable` 结束。最后一个监听方离开后轮询停止。默认值见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge)。 ----- diff --git a/packages/experimental/forge/src/index.ts b/packages/experimental/forge/src/index.ts index becc2d5cb9..5597e6947e 100644 --- a/packages/experimental/forge/src/index.ts +++ b/packages/experimental/forge/src/index.ts @@ -94,7 +94,7 @@ export class ForgeService extends Service { return () => { this.providers.delete(provider.forge) for (const watch of this.watches.values()) { - if (watch.ref.repository.forge === provider.forge) this.settle(watch, this.missing(provider.forge)) + if (watch.ref.repository.forge === provider.forge) this.settle(watch, this.missing(provider.forge), undefined) } this.schedule() } @@ -258,8 +258,8 @@ export class ForgeService extends Service { /** * Poll a watched change request at once, including after a terminal state. - * A fetch already in flight for its forge serves the request; an unwatched - * change request is unchanged. + * A fetch already in flight is followed immediately by another fetch; an + * unwatched change request is unchanged. * @param ref - change request to poll. */ refresh(ref: ChangeRequestRef): void { @@ -342,12 +342,12 @@ export class ForgeService extends Service { for (const watch of batch) { if (this.watches.get(watch.key) !== watch) continue const result = failure ?? results?.get(watch.key) ?? { code: 'unavailable', message: `provider returned no result for ${watch.key}` } - this.settle(watch, result) + this.settle(watch, result, watch.dueAt) } this.schedule() } - private settle(watch: Watch, result: ChangeRequestSnapshot | ForgeFailure): void { + private settle(watch: Watch, result: ChangeRequestSnapshot | ForgeFailure, refreshAt: number | undefined): void { const fetchedAt = Date.now() let update: ChangeRequestUpdate if ('code' in result) { @@ -359,7 +359,8 @@ export class ForgeService extends Service { } watch.latest = update const delay = nextPollDelay(result, watch.failures, this.config) - watch.dueAt = delay === undefined ? undefined : fetchedAt + delay + // A refresh requested after this fetch started needs a subsequent fetch, even for a terminal result. + watch.dueAt = refreshAt ?? (delay === undefined ? undefined : fetchedAt + delay) for (const listener of [...watch.listeners]) { try { listener(update) diff --git a/packages/experimental/forge/tests/watch.spec.ts b/packages/experimental/forge/tests/watch.spec.ts index b65923d36e..483af11956 100644 --- a/packages/experimental/forge/tests/watch.spec.ts +++ b/packages/experimental/forge/tests/watch.spec.ts @@ -220,7 +220,7 @@ describe('forge watch', () => { expect(provider.fetches).toHaveLength(3) }) - it('lets a fetch already in flight serve a refresh', async () => { + it('coalesces refreshes during a fetch into one immediate subsequent fetch', async () => { const provider = new FakeProvider() const release = held(provider, target => snapshot(target)) const context = await setup(provider) @@ -228,6 +228,7 @@ describe('forge watch', () => { await vi.advanceTimersByTimeAsync(0) expect(provider.fetches).toHaveLength(1) + context.forge.refresh(ref(1)) context.forge.refresh(ref(1)) await vi.advanceTimersByTimeAsync(0) expect(provider.fetches).toHaveLength(1) @@ -235,8 +236,30 @@ describe('forge watch', () => { await vi.advanceTimersByTimeAsync(0) expect(updates).toHaveLength(1) - await vi.advanceTimersByTimeAsync(4_999) - expect(provider.fetches).toHaveLength(1) + expect(provider.fetches).toHaveLength(2) + release() + await vi.advanceTimersByTimeAsync(0) + expect(updates).toHaveLength(2) + expect(provider.fetches).toHaveLength(2) + }) + + it.each(['ready', 'merge'] as const)('fetches again after %s when an older poll is still pending', async (action) => { + const provider = new FakeProvider() + const release = held(provider, target => snapshot(target, { draft: true })) + const context = await setup(provider) + const { updates } = collect(context) + await vi.advanceTimersByTimeAsync(0) + + const signal = new AbortController().signal + if (action === 'ready') await context.forge.markReady(ref(1), signal) + else await context.forge.merge(ref(1), { method: 'merge', headSha: 'a'.repeat(40) }, signal) + provider.fetchImpl = undefined + provider.results.set(key, snapshot(ref(1), { draft: false, state: action === 'merge' ? 'merged' : 'open' })) + release() + await vi.advanceTimersByTimeAsync(0) + + expect(provider.fetches).toHaveLength(2) + expect(updates.at(-1)).toMatchObject({ snapshot: { draft: false, state: action === 'merge' ? 'merged' : 'open' } }) }) it('keeps notifying other listeners when one listener throws', async () => { diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 6723b36506..045e9ea1bb 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1306,7 +1306,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'refresh(ref: ChangeRequestRef): void', - description: 'Poll a watched change request at once, including after a terminal state. A fetch already in flight for its forge serves the request; an unwatched change request is unchanged.', + description: 'Poll a watched change request at once, including after a terminal state. A fetch already in flight is followed immediately by another fetch; an unwatched change request is unchanged.', parameters: [{ name: 'ref', description: 'change request to poll.' }], }, {