Skip to content

Commit 03ec6c6

Browse files
committed
Merge origin/main
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L6bhgVW2q9rsHS1vCrQ8Q9
2 parents 3f4401e + 380a107 commit 03ec6c6

7 files changed

Lines changed: 635 additions & 52 deletions

File tree

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
'@objectstack/runtime': patch
3+
'@objectstack/cloud-connection': patch
4+
---
5+
6+
fix(cloud-connection): an install-local install judges who holds a datasource name with one judge that reads the engine too and fails closed, and a restart's rehydrate no longer takes over a name another holder owns
7+
8+
Clause-②: yes (widening)
9+
The widening: `@objectstack/runtime` now exports `datasourceNameHolder` and the type `DatasourceNameHolding`, and `POST /api/v1/marketplace/install-local` gains a `503 SERVICE_UNAVAILABLE` answer.
10+
Metadata-protocol: none
11+
12+
Three edges `POST /api/v1/marketplace/install-local`'s datasource-name check left open, each measured on `main`:
13+
14+
- **A holder that cannot be read.** When the metadata registry's read of a declared datasource name threw, the check skipped it and the install went ahead (`200`). It now answers `503 SERVICE_UNAVAILABLE` with `details: { datasource, reading }` and writes nothing: a check that did not run is never taken for "no holder". Retry once that store answers.
15+
- **A datasource registered on the data engine only** (the legacy `onEnable` bridge, which leaves no metadata item) was not seen: the install answered `200` and reported that pool as the package's `already-registered`. It now holds its name, `409 RESOURCE_CONFLICT` like every other holder.
16+
- **A package installed before the check existed.** A restart's rehydrate replayed such a package's datasources over a datasource created in Setup under the same name: the Setup item was overwritten by the package's code registration, the name joined the code-defined set (the Setup row turned read-only), and the package's uninstall closed and evicted the Setup row's pool. The rehydrate now leaves a held name alone: it is not registered, recorded or connected for the package, one `error` line names it, its holder and the remedy, and the uninstall does not touch it. An uninstall also closes only the pools the package's own connect opened, never one it found already registered.
17+
18+
`@objectstack/runtime` exports `datasourceNameHolder`, the one judge both the install door and the rehydrate use: the host's `default`, a metadata item not stamped with the package (a Setup row, another package's), a name in the code-datasource set the package did not record, then a driver on the data engine.
19+
20+
**The remedy** for a package the rehydrate now reports: rename the package's datasource and install it again, or remove the datasource holding the name and restart.

‎content/docs/automation/connectors.mdx‎

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -470,8 +470,40 @@ What the publish door checks, each refusal located at its key under `auth`:
470470
- **`app-credential`** takes `vendor` (`feishu`, `dingtalk` or `wecom`), `appId`
471471
and a required `credentialRef`. An inline `appSecret` is refused by name.
472472

473-
**How the server serves them.** An `oauth2` instance is served through a
474-
**credential handle** the provider asks on every request: the access token is
473+
**How the server serves them.** Both kinds are served through a
474+
**credential handle** the provider asks on every request. The built-in `rest`
475+
and `openapi` providers ask it; a provider says it does by registering with
476+
`registerConnectorProvider(…, { credentialHandle: true })`. For an `openapi`
477+
instance the document's `security` decides only where the token is *not*
478+
sent: an operation whose effective `security` is `[]` is anonymous and never
479+
carries it, and a header or query parameter an `apiKey` scheme names is the
480+
platform's to fill, so it is left out of the action's input schema, as
481+
`Authorization` is.
482+
483+
An **`app-credential`** instance runs its vendor's exchange from the `appId`
484+
and the app secret its `credentialRef` names. The exchange is fixed per
485+
`vendor`, and nothing about it is authored:
486+
487+
| `vendor` | Token request | Where the token rides on a call |
488+
|:---|:---|:---|
489+
| `feishu` | `POST https://accounts.feishu.cn/oauth/v3/token` (`client_credentials`) | `Authorization: Bearer` |
490+
| `dingtalk` | `POST https://api.dingtalk.com/v1.0/oauth2/accessToken` | header `x-acs-dingtalk-access-token` |
491+
| `wecom` | `GET https://qyapi.weixin.qq.com/cgi-bin/gettoken` | query parameter `access_token` |
492+
493+
The token belongs to the app, so a run's organization selects nothing, and
494+
there is nothing to connect. It is kept in memory only, never stored (the app
495+
secret re-derives it at any time), and obtained afresh when it is within 30
496+
seconds of its expiry, or once when the upstream answers `401`. Concurrent
497+
requests share one exchange. WeCom can invalidate a token before it expires
498+
and says so inside an ordinary answer (`errcode` `40014` or `42001`) rather
499+
than with a `401`: such an answer obtains the token afresh once and repeats
500+
the call once, and a second such answer fails the call. No exchange follows a
501+
redirect. An exchange that gets no answer, a `429` or a `5xx` fails the
502+
dispatch `CONNECTOR_UPSTREAM_UNAVAILABLE`, retried on the existing backoff; a
503+
vendor that refuses the app id or secret fails it with `503`, naming the
504+
instance and at most the vendor's error code, never the vendor's text.
505+
506+
An **`oauth2`** instance's access token is
475507
obtained from `tokenUrl` (the client authenticating with HTTP Basic, or by
476508
`client_id` alone as a public client), cached in memory only, refreshed when
477509
it is within 30 seconds of its expiry, and refreshed once more, with one
@@ -527,10 +559,11 @@ a rotating refresh token is never spent twice.
527559
disconnect is a response to a leak.
528560

529561
What is not served yet is held **degraded** with a reason that names it, and
530-
never called without its credential: `app-credential` (its vendor exchanges
531-
are not run yet), an `oauth2` instance on a provider that does not yet ask the
532-
credential handle (the built-in `rest`, `openapi` and `mcp` providers do not
533-
yet), an `mcp` instance that left its endpoints to discovery, and an `oauth2`
562+
never called without its credential: an `oauth2` or `app-credential`
563+
instance on a provider that does not ask the credential handle (the built-in
564+
`mcp` provider does not yet, nor does a plugin's provider registered without
565+
`{ credentialHandle: true }`), an `mcp` instance that left its endpoints to
566+
discovery, and an `oauth2`
534567
instance whose `tokenUrl` or `authorizationUrl` is not `https://` (plain
535568
`http://` is accepted only to `localhost`, a `127.0.0.0/8` address or
536569
`[::1]` — not a `*.localhost` name, which the system resolver sends to DNS —
@@ -663,7 +696,7 @@ retry):
663696
|:---|:---|
664697
| `provider` names no installed factory | **Hard boot error** naming the entry, the provider, and the plugin that supplies it — add the executor to `plugins:` |
665698
| Invalid `providerConfig` (missing `baseUrl` / `spec` / `transport`, wrong shape) | **Hard boot error** from the provider factory |
666-
| `auth` is a grant-bearing kind (`oauth2`, `app-credential`) this server does not serve yet (`app-credential`; `oauth2` on a provider that does not ask the credential handle) | **Not fatal**: the instance registers **degraded**, naming the kind, and the upstream is never called without its credential; a datasource borrowing it is refused with `422` |
699+
| `auth` is a grant-bearing kind (`oauth2`, `app-credential`) on a provider that does not ask the credential handle (the built-in `mcp` provider, for now) | **Not fatal**: the instance registers **degraded**, naming the kind, and the upstream is never called without its credential; a datasource borrowing it is refused with `422` |
667700
| An `authorization_code` instance nobody connected, or whose grant the vendor refused | **Not fatal**: the instance registers **degraded**, "not connected" or "reconnect required" — connect it (`POST …/connectors/:name/connection`), and it materializes without a restart |
668701
| The token endpoint is unreachable or answers `5xx` / `429` | **Not fatal**: the dispatch fails `CONNECTOR_UPSTREAM_UNAVAILABLE` and is retried on the existing backoff; the connection stays connected |
669702
| `auth` is `signed` on a provider that does not say it applies the request signer | **Hard boot error** naming the instance, the scheme and the provider: its calls would go out unsigned — declare it through `rest` or `openapi` |
Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#28143] Step 2a of `POST /api/v1/marketplace/install-local` — a package
5+
* declaring a datasource name another holder owns is refused before any write
6+
* — judges with the runtime's ONE judge (`datasourceNameHolder`), and so:
7+
*
8+
* - a holder the metadata registry cannot be read for is `503
9+
* SERVICE_UNAVAILABLE`, never taken for "no holder": the install does not
10+
* proceed past an outage;
11+
* - a datasource registered on the data engine only (the legacy `onEnable`
12+
* bridge, with no metadata item) holds its name: `409 RESOURCE_CONFLICT`,
13+
* where the door used to install and answer that pool `already-registered`.
14+
*
15+
* Each refusal leaves the runtime as it found it: no ledger entry, nothing
16+
* registered. The end-to-end refusals (the boot's datasource, the host's
17+
* `default`) are pinned by `install-local-declared-datasources.dogfood.test.ts`.
18+
*/
19+
20+
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
21+
import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
22+
import { join } from 'node:path';
23+
import { tmpdir } from 'node:os';
24+
// The install and its 2a judge reach `@objectstack/runtime` through a lazy
25+
// `import()`; its first load is paid here, at module top — never inside a
26+
// clocked `it` (`scripts/check-test-source-alias.mjs`).
27+
import '@objectstack/runtime';
28+
import { MarketplaceInstallLocalPlugin } from './marketplace-install-local-plugin.js';
29+
import { installerAuthService, withInstallerGrants } from './install-local-principal.fixtures.js';
30+
31+
type Handler = (c: any) => Promise<any>;
32+
33+
const ROUTE = 'POST /api/v1/marketplace/install-local';
34+
const DS = 'qah_store';
35+
36+
function makeRawApp() {
37+
const routes = new Map<string, Handler>();
38+
return {
39+
routes,
40+
get: (p: string, h: Handler) => routes.set(`GET ${p}`, h),
41+
post: (p: string, h: Handler) => routes.set(`POST ${p}`, h),
42+
delete: (p: string, h: Handler) => routes.set(`DELETE ${p}`, h),
43+
};
44+
}
45+
46+
/** A kernel whose metadata registry and data engine the case shapes. */
47+
function makeCtx(rawApp: any, opts: { metadataFault?: boolean; engineDrivers?: string[] }) {
48+
const hooks = new Map<string, any>();
49+
const registered: any[] = [];
50+
const drivers = new Set(opts.engineDrivers ?? []);
51+
const services: Record<string, any> = {
52+
manifest: { register: (m: any) => registered.push({ manifest: m }) },
53+
auth: installerAuthService(),
54+
objectql: withInstallerGrants({
55+
syncSchemas: async () => undefined,
56+
registry: { getAllPackages: () => registered },
57+
getDriverByName: (name: string) => (drivers.has(name) ? { name } : undefined),
58+
}),
59+
metadata: {
60+
get: async () => {
61+
if (opts.metadataFault) throw new Error('metadata loader unavailable');
62+
return undefined;
63+
},
64+
},
65+
};
66+
return {
67+
registered,
68+
ctx: {
69+
hook: (e: string, h: any) => hooks.set(e, h),
70+
getService: (name: string) => {
71+
if (name === 'http-server') return { getRawApp: () => rawApp };
72+
const svc = services[name];
73+
if (svc === undefined) throw new Error(`no ${name}`);
74+
return svc;
75+
},
76+
registerService: (name: string, svc: unknown) => { services[name] = svc; },
77+
logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
78+
},
79+
fire: async () => { await hooks.get('kernel:ready')?.(); },
80+
};
81+
}
82+
83+
function makeC(body: any) {
84+
const json = vi.fn((payload: any, status?: number) => ({ payload, status: status ?? 200 }));
85+
return { req: { url: 'http://localhost:3000/x', raw: new Request('http://localhost:3000/x'), json: async () => body, param: () => undefined }, json };
86+
}
87+
88+
const BODY = {
89+
manifest: {
90+
id: 'com.example.qah',
91+
version: '1.0.0',
92+
datasources: [{ name: DS, label: 'QA store', driver: 'sqlite', config: { filename: ':memory:' } }],
93+
objects: [],
94+
},
95+
};
96+
97+
let dir: string;
98+
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'mil-ds-holder-')); });
99+
afterEach(() => { rmSync(dir, { recursive: true, force: true }); vi.restoreAllMocks(); });
100+
101+
async function install(opts: { metadataFault?: boolean; engineDrivers?: string[] }) {
102+
const rawApp = makeRawApp();
103+
const k = makeCtx(rawApp, opts);
104+
const plugin = new MarketplaceInstallLocalPlugin({ controlPlaneUrl: 'off', storageDir: dir });
105+
await plugin.start(k.ctx as any);
106+
await k.fire();
107+
const res = await rawApp.routes.get(ROUTE)!(makeC(BODY));
108+
// The plugin registers its own Installed Apps UI manifest at start; only
109+
// the package's registration is this case's.
110+
const registered = k.registered.map((r) => r.manifest.id).filter((id) => id === 'com.example.qah');
111+
return { res, registered, ledger: readdirSync(dir) };
112+
}
113+
114+
describe('install-local 2a — who holds a declared datasource name', () => {
115+
it('a holder that cannot be read refuses 503, and nothing is written', async () => {
116+
const { res, registered, ledger } = await install({ metadataFault: true });
117+
expect(res.status).toBe(503);
118+
expect(res.payload?.error?.code).toBe('SERVICE_UNAVAILABLE');
119+
expect(res.payload?.error?.details).toEqual({ datasource: DS, reading: 'the metadata registry' });
120+
expect(registered).toEqual([]);
121+
expect(ledger).toEqual([]);
122+
});
123+
124+
it('a datasource registered on the engine only holds its name: 409, and nothing is written', async () => {
125+
const { res, registered, ledger } = await install({ engineDrivers: [DS] });
126+
expect(res.status).toBe(409);
127+
expect(res.payload?.error?.code).toBe('RESOURCE_CONFLICT');
128+
expect(res.payload?.error?.details).toEqual({ datasource: DS });
129+
expect(registered).toEqual([]);
130+
expect(ledger).toEqual([]);
131+
});
132+
133+
it('CONTROL: a name nobody holds installs', async () => {
134+
const { res, registered } = await install({ engineDrivers: ['someone_else'] });
135+
expect(res.status, JSON.stringify(res.payload)).toBe(200);
136+
expect(res.payload?.success).toBe(true);
137+
expect(registered).toEqual(['com.example.qah']);
138+
});
139+
});

0 commit comments

Comments
 (0)