Skip to content

Commit 60d8522

Browse files
fix(service-automation): a stored connector under a host plugin connector's name is skipped at start, as it is while the platform runs (#28755)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1X4gSF1mHqRhZEva62pbKFEW)_ Fixes #28713 Clause-②: yes (widening) — `@objectstack/core` adds one read-only public member, `dispatchesBootPhaseHooks()`, on `ObjectKernel` and `ObjectKernelBase` (so `LiteKernel`); no accepted value changes, nothing is narrowed. Metadata-protocol: none ## 维护者速读 - 改了什么:环境里保存的连接器(元数据门 / Studio 保存)若与宿主插件提供的连接器同名,平台启动时的处理与运行中完全一致:插件的连接器照常服务,保存的那条不服务并记录日志。保存的连接器改为在所有插件启动完成后再实例化(仍在服务器开始接收请求之前)。另在 `@objectstack/core` 的两种内核上加一个只读方法 `dispatchesBootPhaseHooks()`,让插件在自己的 `start()` 里知道启动阶段钩子是否会派发;不会派发(或宿主不回答)时,保存的连接器仍在自动化插件的 `start()` 中实例化,与原来一样,绝不落空。 - 为什么改:运行中已经判定"插件优先、保存条目跳过",启动时却在插件注册前就下了"名字空闲"的结论,两处判定不一致。这是可用性问题,不是数据问题;细节在席位处。 - 风险与回滚:优先级不变(插件仍优先,未改 ADR-0097 §4),宿主自己声明的连接器与已安装包的连接器启动行为不变,有对照测试钉住。core 只新增一个只读方法。回滚即还原本 PR。 - 先看:`packages/services/service-automation/src/plugin.ts`(`holdStoredEntries`、`kernelDispatchesBootPhaseHooks`、`kernel:bootstrapped` 那一轮的 `held` 判断)、`packages/core/src/kernel.ts` 与 `kernel-base.ts` 的新方法、`src/connector-materialization.test.ts` 新的 #28713 一节。 - 两分钟验证:`pnpm --filter @objectstack/service-automation exec vitest run src/connector-materialization.test.ts`,预期 108/108 通过(含 #28713 一节 6 例:插件同名跳过、空闲名在监听前就绪、宿主同名仍失败、三种不派发钩子的宿主仍在 start 中实例化)。 - 需要你做的:无,席位落地(core 新增公开成员,席位先跑契约复核)。 ## What changes - **A saved connector under a host plugin connector's name: the start agrees with the running platform.** While the platform runs, a provider-bound connector saved in the environment (through the metadata door or Studio) under the name of a connector a host plugin provides is not served beside the plugin's connector: the plugin's connector keeps the name, and the conflict is logged. The start now reaches the same verdict: the plugin's connector is served `ready` under that name, and the saved connector is skipped with the same log record naming it. Precedence is unchanged (the plugin's connector wins, as ADR-0097 §4 already has it on a running platform), so no §4 ruling is needed. - **When saved connectors materialize.** Connectors saved in the environment are now materialized once every plugin has started (the automation service's existing `kernel:bootstrapped` connector pass), instead of during the automation plugin's own start. They are still `ready` before the server accepts requests. Connectors the host's own stack declares, and an installed package's, still materialize during the automation plugin's start, with their fail-loud behavior unchanged, including on a name a plugin's connector also uses. - **A saved connector is never left unserved.** The deferral applies only on a kernel that says it dispatches its boot-phase hooks. `@objectstack/core` gains `dispatchesBootPhaseHooks()`, read-only: `ObjectKernel` answers `false` exactly when its `bootPhaseHooks` option is `false`; `LiteKernel` (and anything on `ObjectKernelBase`) answers `true`. On a kernel that answers `false`, or a host whose kernel does not expose the member, saved connectors materialize during the automation plugin's start, as before. - No save-door change: a connector under such a name is still accepted at save. Rows already at rest are covered by this change; a save-door refusal would be a separate narrowing. ## Tests - **Unit, `connector-materialization.test.ts`, new `#28713` describe (6 cases):** a saved entry under a name a plugin registers in its own `start()` (after the automation plugin's): the boot starts, the plugin's connector serves its own action, the saved entry is skipped with the §4 record; control: a saved entry under a free name is not yet registered when a later plugin starts and is registered by `kernel:listening`; control: the host's own entry under such a name still fails the boot; a real `ObjectKernel` with `bootPhaseHooks: false`, and a host whose kernel has no reader or answers `false`, keep saved entries in the start reconcile so they serve. - **Kernel pins:** `kernel.boot-phase-hooks.test.ts` reads `dispatchesBootPhaseHooks()` from a plugin's own `start()`: `false` under `bootPhaseHooks: false`, `true` for absent / `true` / `undefined`; `lite-kernel.test.ts` pins `true`. - **Restart dogfood, `stored-connector-package-ref-restart.dogfood.test.ts`:** the first start also saves an environment-wide connector under the showcase's `slack` plugin connector name; the second start over the same database starts, lists the plugin's `slack` connector `ready` with the plugin's actions (not the saved one's), and its start record names the saved entry; control: the saved inline connector is already `ready` on the first read after the start. <details><summary>Red on base, green on head, ablations</summary> - Red: production sources (`plugin.ts`, `kernel.ts`, `kernel-base.ts`) restored to base `1c5b1773`, rebuilt: unit `2 failed | 106 passed (108)` (the two new #28713 cases that measure behavior; the hookless-host cases pass on base, as base keeps every saved entry in the start reconcile); restart dogfood `8 failed | 1 passed (9)`. Tree restored, `git diff HEAD` empty. - Green on head: unit `108 passed (108)`; dogfood `stored-connector-package-ref-restart`, `stored-connector-package-ref`, `install-local-restart-connectors`: `3 passed (3)` files, `21 passed (21)` tests. - Ablation 1 (saved entries back into the start reconcile: the hold set to a constant false): marker present in both built files of `@objectstack/service-automation`; unit `2 failed | 106 passed`, restart dogfood `8 failed | 1 passed`. Restored: blob `9f3bdcad` == HEAD, marker absent after rebuild, tree clean. - Ablation 2 (the kernel reader forced to answer "dispatches"): unit `3 failed | 105 passed` (the three hookless-host cases). Restored: blob `9f3bdcad` == HEAD, marker absent after rebuild, tree clean. </details> <details><summary>Package suites and type checks</summary> - `pnpm --filter @objectstack/core --filter @objectstack/service-automation run typecheck`: exit 0 (both `check:test-typecheck` OK). - `pnpm --filter @objectstack/core test`: `129 passed` files, `2892 passed` tests. - `pnpm --filter @objectstack/service-automation test`: `251 passed` files, `3216 passed` tests. </details> ## Acceptance notes - **Measured, not observed (residue).** Saved connectors now become available a little later during the start (on the showcase, about a third of a second later), still before the server accepts requests. A showcase restart with an instrumented connector registry saw no connector call, effect read or pull before that point. Possible in principle and not observed: an automation that runs during the start itself (a record change made by the app's own start-up work, or a scheduled job whose first run falls inside the start) and calls a saved connector would find it not yet available. - A kernel that withholds its boot-phase hooks, or a host whose kernel does not say, keeps today's behavior for saved connectors: they are materialized during the automation plugin's start, so they are never left unserved; the conflict this card fixes is not fixed on such a host. - No save-door refusal for such a name (a narrowing, and it would not cover rows already at rest); it is with the seat as a possible follow-up. ## Verification Every local reading above is on head `525f355c`. Derived gate families (`node scripts/pm/dispatch-gates.mjs --commands`, reconciled with `--ran`): 67 derived, 66 run with exit 0, 1 not measured (`check:dual-build-cjs-loads`, exit 3: its prerequisite, every package's `dist/`, is not met in this checkout). The changeset, ADR-0087, empty-changeset and closing-keyword gates were also run against this body: exit 0. The repo-wide lint, `test:repo` and the full farm are CI's. Overlap: open PR #28693 also edits `service-automation/src/plugin.ts`; `git merge-tree` of its head with this one is clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FEkQ5oNHddQQdvMrpeQxiJ --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5oNHddQQdvMrpeQxiJ)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent d08b859 commit 60d8522

8 files changed

Lines changed: 331 additions & 7 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
"@objectstack/service-automation": patch
3+
"@objectstack/core": patch
4+
---
5+
6+
fix(service-automation): a stored connector under a host plugin connector's name is skipped at start, as it is while the platform runs
7+
8+
Clause-②: yes (widening) — `@objectstack/core` adds one read-only public member, `dispatchesBootPhaseHooks()`, on `ObjectKernel` and `ObjectKernelBase` (so `LiteKernel`); no accepted value changes.
9+
10+
Metadata-protocol: none
11+
12+
- **Now.** A provider-bound connector saved in the environment (through the metadata door or Studio) under the name of a connector that a plugin on the host provides is treated at start exactly as it is while the platform runs: the plugin's connector is served under that name, and the saved connector is not served, with the same log record naming it. Connectors saved in the environment are now materialized once every plugin has started, still before the server accepts requests.
13+
- **Unchanged.** A connector the host's own stack declares, and an installed package's, keep their start behavior, including when their name collides with a plugin's connector.
14+
- **`@objectstack/core`.** `ObjectKernel.dispatchesBootPhaseHooks()` answers whether `bootstrap()` dispatches `kernel:ready`, `kernel:bootstrapped` and `kernel:listening` once every plugin has started (`false` exactly when the `bootPhaseHooks` option is `false`); `LiteKernel` always answers `true`. A plugin that leaves part of its start to one of those hooks reads it during its own `start()`. On a kernel that does not dispatch them, or a host that does not say, saved connectors are materialized during the automation plugin's own start, as before.

‎packages/core/src/kernel-base.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,22 @@ export abstract class ObjectKernelBase {
328328
return this.state;
329329
}
330330

331+
/**
332+
* Whether `bootstrap()` dispatches the boot-phase hooks — `kernel:ready`,
333+
* `kernel:bootstrapped` and `kernel:listening` — once every plugin's
334+
* `start()` has run. A kernel on this base always does, so this answers
335+
* `true`.
336+
*
337+
* Read-only. It is for a plugin that leaves part of its start to one of
338+
* those hooks and must know, during its own `start()`, that the hook will
339+
* come; where the answer is `false` (or a host does not say), it keeps
340+
* that work in `start()`. `ObjectKernel` answers from its
341+
* `bootPhaseHooks` option.
342+
*/
343+
dispatchesBootPhaseHooks(): boolean {
344+
return true;
345+
}
346+
331347
/**
332348
* Get all registered plugins
333349
*/

‎packages/core/src/kernel.boot-phase-hooks.test.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,23 @@ describe('ObjectKernel bootPhaseHooks', () => {
118118
});
119119

120120
describe('bootPhaseHooks: false', () => {
121+
it('dispatchesBootPhaseHooks() answers false, read by a plugin during its own start()', async () => {
122+
const { plugins } = composition();
123+
const read: unknown[] = [];
124+
const reader: Plugin = {
125+
name: 'test.reader',
126+
version: '1.0.0',
127+
init: async () => {},
128+
start: async (ctx) => { read.push(ctx.getKernel().dispatchesBootPhaseHooks()); },
129+
};
130+
const kernel = track(newKernel({ bootPhaseHooks: false }));
131+
132+
await boot(kernel, [...plugins, reader]);
133+
134+
expect(read).toEqual([false]);
135+
expect(kernel.dispatchesBootPhaseHooks()).toBe(false);
136+
});
137+
121138
it('keeps every definition registered in init() and start(), and the kernel runs', async () => {
122139
const { plugins } = composition();
123140
const kernel = track(newKernel({ bootPhaseHooks: false }));
@@ -221,6 +238,22 @@ describe('ObjectKernel bootPhaseHooks', () => {
221238
['true', { bootPhaseHooks: true }],
222239
['undefined', { bootPhaseHooks: undefined }],
223240
] as Array<[string, ObjectKernelConfig]>)('bootPhaseHooks %s (control)', (_label, extra) => {
241+
it('dispatchesBootPhaseHooks() answers true, read by a plugin during its own start()', async () => {
242+
const { plugins } = composition();
243+
const read: unknown[] = [];
244+
const reader: Plugin = {
245+
name: 'test.reader',
246+
version: '1.0.0',
247+
init: async () => {},
248+
start: async (ctx) => { read.push(ctx.getKernel().dispatchesBootPhaseHooks()); },
249+
};
250+
const kernel = track(newKernel(extra));
251+
252+
await boot(kernel, [...plugins, reader]);
253+
254+
expect(read).toEqual([true]);
255+
});
256+
224257
it('fires all three hooks in order and keeps every definition, the kernel:ready one included', async () => {
225258
const { plugins, spies, order } = composition();
226259
const kernel = track(newKernel(extra));

‎packages/core/src/kernel.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -891,6 +891,21 @@ export class ObjectKernel {
891891
return this.state;
892892
}
893893

894+
/**
895+
* Whether `bootstrap()` dispatches the boot-phase hooks — `kernel:ready`,
896+
* `kernel:bootstrapped` and `kernel:listening` — once every plugin's
897+
* `start()` has run: `false` exactly when {@link ObjectKernelConfig.bootPhaseHooks}
898+
* is `false`, `true` otherwise.
899+
*
900+
* Read-only; the option is fixed at construction. It is for a plugin that
901+
* leaves part of its start to one of those hooks and must know, during its
902+
* own `start()`, that the hook will come; where the answer is `false`, it
903+
* keeps that work in `start()`.
904+
*/
905+
dispatchesBootPhaseHooks(): boolean {
906+
return this.config.bootPhaseHooks !== false;
907+
}
908+
894909
// Private methods
895910

896911
private async initPluginWithTimeout(plugin: PluginMetadata): Promise<void> {

‎packages/core/src/lite-kernel.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,22 @@ describe('LiteKernel with Configurable Logger', () => {
271271
expect(order).toEqual(['kernel:ready', 'kernel:bootstrapped', 'kernel:listening']);
272272
});
273273

274+
it('dispatchesBootPhaseHooks() answers true, read by a plugin during its own start()', async () => {
275+
const read: unknown[] = [];
276+
const plugin: Plugin = {
277+
name: 'boot-phase-reader-plugin',
278+
init: async () => {},
279+
start: async (ctx) => { read.push(ctx.getKernel().dispatchesBootPhaseHooks()); },
280+
};
281+
282+
kernel.use(plugin);
283+
await kernel.bootstrap();
284+
await kernel.shutdown();
285+
286+
expect(read).toEqual([true]);
287+
expect(kernel.dispatchesBootPhaseHooks()).toBe(true);
288+
});
289+
274290
// #5170 — the LiteKernel half of the cross-kernel pin. This is the
275291
// behaviour the issue changed: the throw used to be caught inside
276292
// `triggerHook`, logged as `Hook handler failed: kernel:ready`, and the

‎packages/qa/dogfood/test/stored-connector-package-ref-restart.dogfood.test.ts‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,22 @@
2323
// environment-wide stdio `mcp` entry, and a control carrying its document
2424
// inline. [#28698] It also saves an environment-wide entry naming a provider
2525
// no installed plugin offers (accepted at save, skipped after boot: the shape
26-
// a row takes when the plugin that offered its provider is removed). The
27-
// second boot:
26+
// a row takes when the plugin that offered its provider is removed).
27+
// [#28713] And an environment-wide entry under the name of a connector a host
28+
// plugin registers (`slack`, ConnectorSlackPlugin): accepted at save, not
29+
// served beside the plugin's connector while the platform runs. The second
30+
// boot:
2831
//
2932
// 1. starts (no throw);
3033
// 2. does not list any refused entry, and its boot record names each entry
3134
// and its ref (or, for the unknown provider, the provider);
3235
// 3. lists the stored inline control `ready` with its operation (the rows
3336
// were hydrated, so the refusal above was read at boot, not skipped);
34-
// 4. lists the showcase's own file-ref and stdio entries `ready` (control).
37+
// 4. lists the showcase's own file-ref and stdio entries `ready` (control);
38+
// 5. [#28713] lists the plugin's `slack` connector `ready` with the plugin's
39+
// actions, not the stored entry's, and its boot record names the stored
40+
// entry; the stored inline control is already `ready` on the first read
41+
// after the start (it is served before the server answers).
3542
//
3643
// Boots fixture stacks of its own (a database file), so it stays out of
3744
// `SHARED_SHOWCASE`.
@@ -53,6 +60,8 @@ const AUTHORED_PACKAGE_ID = 'com.dogfood.storedrestart';
5360
const INLINE = 'srr_inline';
5461
/** [#28698] A stored entry whose provider no installed plugin offers. */
5562
const UNKNOWN_PROVIDER = 'srr_unknown_provider';
63+
/** [#28713] The name of the connector ConnectorSlackPlugin registers on the showcase. */
64+
const PLUGIN_NAME = 'slack';
5665
const HOST_FILE_ENTRY = 'showcase_status_openapi';
5766
const HOST_STDIO_ENTRY = 'showcase_mcp_tools';
5867

@@ -126,6 +135,7 @@ describe('dogfood: a stored connector entry refused its package-relative ref doe
126135
let before: Answer;
127136
let bootError: unknown;
128137
let after: Answer;
138+
let firstRead: Answer;
129139
let bootLines: string[] = [];
130140
let second: VerifyStack | undefined;
131141

@@ -154,6 +164,7 @@ describe('dogfood: a stored connector entry refused its package-relative ref doe
154164
...openapi(UNKNOWN_PROVIDER, DOCUMENT),
155165
provider: 'no_such_provider',
156166
}));
167+
saves[PLUGIN_NAME] = await json(await first.apiAs(token, 'PUT', `/meta/connector/${PLUGIN_NAME}`, openapi(PLUGIN_NAME, DOCUMENT)));
157168
saves[INLINE] = await json(await first.apiAs(token, 'PUT', `/meta/connector/${INLINE}`, openapi(INLINE, DOCUMENT)));
158169
before = await settle(first, token, [INLINE]);
159170
} finally {
@@ -168,6 +179,7 @@ describe('dogfood: a stored connector entry refused its package-relative ref doe
168179
return undefined;
169180
}
170181
const token = await second.signIn();
182+
firstRead = await json(await second.apiAs(token, 'GET', '/automation/connectors'));
171183
return settle(second, token, [INLINE, HOST_FILE_ENTRY, HOST_STDIO_ENTRY]);
172184
});
173185
bootLines = captured.lines;
@@ -186,6 +198,8 @@ describe('dogfood: a stored connector entry refused its package-relative ref doe
186198
expect(entryOf(before, INLINE)?.state, shown(before, INLINE)).toBe('ready');
187199
expect(entryOf(before, ENV_FILE), shown(before, ENV_FILE)).toBeUndefined();
188200
expect(entryOf(before, UNKNOWN_PROVIDER), shown(before, UNKNOWN_PROVIDER)).toBeUndefined();
201+
// [#28713] While the platform runs, the plugin's connector keeps the name.
202+
expect(entryOf(before, PLUGIN_NAME)?.actions?.map((a: any) => a.key), shown(before, PLUGIN_NAME)).not.toContain('GetThings');
189203
});
190204

191205
it('the second boot over the same database starts', () => {
@@ -210,6 +224,19 @@ describe('dogfood: a stored connector entry refused its package-relative ref doe
210224
expect(record).toContain('no provider factory is registered');
211225
});
212226

227+
it('[#28713] a stored entry under a host plugin connector\'s name: the plugin\'s connector lists ready after the restart, and the boot record names the stored entry', () => {
228+
const plugin = entryOf(after, PLUGIN_NAME);
229+
expect(plugin?.state, shown(after, PLUGIN_NAME)).toBe('ready');
230+
expect(plugin.actions.map((a: any) => a.key)).not.toContain('GetThings');
231+
expect(plugin.actions.length).toBeGreaterThan(0);
232+
const record = bootLines.find((l) => l.includes(`declarative provider-bound instance '${PLUGIN_NAME}' collides with a plugin-registered connector`));
233+
expect(record, `no boot record names '${PLUGIN_NAME}'`).toBeDefined();
234+
});
235+
236+
it('[#28713] control: the stored inline entry is already ready on the first read after the restart', () => {
237+
expect(entryOf(firstRead, INLINE)?.state, shown(firstRead, INLINE)).toBe('ready');
238+
});
239+
213240
it('controls: the stored inline entry, and the showcase\'s own file-ref and stdio entries, list ready after the restart', () => {
214241
expect(entryOf(after, INLINE)?.state, shown(after, INLINE)).toBe('ready');
215242
expect(entryOf(after, INLINE).actions.map((a: any) => a.key)).toEqual(['GetThings']);

0 commit comments

Comments
 (0)