|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [ADR-0015 D7 × ADR-0130 D4] A connector instance a composed stack declares |
| 5 | + * only on its TOP LEVEL, beside package bodies that do not declare it — the |
| 6 | + * stack's residual — lends its credential at boot, the way one a body |
| 7 | + * declares does. |
| 8 | + * |
| 9 | + * ## The defect this pins |
| 10 | + * |
| 11 | + * `composeStacks([mixed, borrower], { manifest: 'preserve' })`, where `mixed` |
| 12 | + * is an input that carries `packages[]` AND a top-level connector instance no |
| 13 | + * body repeats, is accepted at build: the composed check finds the instance |
| 14 | + * and judges that it can lend. At boot the residual rule registered that |
| 15 | + * instance into the metadata service only, and the engine's `manifest` |
| 16 | + * service registered the residual's OBJECTS only, so the lender — which reads |
| 17 | + * the ObjectQL registry (`readDeclaredConnectorItems`) — did not see it, and |
| 18 | + * the datasource's borrow was refused as undeclared until a dev reload |
| 19 | + * carried the artifact in. Build and boot gave two answers. |
| 20 | + * |
| 21 | + * ## What each pin is for |
| 22 | + * |
| 23 | + * - the residual instance lends at boot, under the stack's own id, which is |
| 24 | + * the owner the residual rule names; |
| 25 | + * - the residual descriptor (no `provider`) is refused at boot as a |
| 26 | + * descriptor, not as undeclared: the lender sees it and judges it; |
| 27 | + * - CONTROL: an instance a package body declares lends, as it always did. |
| 28 | + * |
| 29 | + * The stack is booted through the `manifest` service, the way `AppPlugin` |
| 30 | + * hands a config boot's stack to it: `{ ...bundle.manifest, ...bundle }`. The |
| 31 | + * artifact door hands the engine the same stack. The values are obvious dummies. |
| 32 | + */ |
| 33 | +import { afterEach, describe, expect, it } from 'vitest'; |
| 34 | +import { ObjectKernel, type Plugin, type PluginContext } from '@objectstack/core'; |
| 35 | +import { ObjectQLPlugin, type ObjectQL } from '@objectstack/objectql'; |
| 36 | +import { SqlDriver } from '@objectstack/driver-sql'; |
| 37 | +import { composeStacks, defineStack } from '@objectstack/spec'; |
| 38 | +import { CONNECTOR_CREDENTIAL_SOURCE_SERVICE, type IConnectorCredentialSource } from '@objectstack/types'; |
| 39 | + |
| 40 | +import { AutomationServicePlugin } from './plugin.js'; |
| 41 | +import type { AutomationEngine } from './engine.js'; |
| 42 | + |
| 43 | +const REF = 'DUMMY_RESIDUAL_SAP_TOKEN'; |
| 44 | +const DUMMY_ENV_VALUE = 'dummy-residual-dddd-0004'; |
| 45 | + |
| 46 | +const MIXED_ID = 'com.acme.bundle'; |
| 47 | +const BODY_ID = 'com.acme.orders'; |
| 48 | + |
| 49 | +const pluginManifest = (id: string) => ({ |
| 50 | + id, |
| 51 | + namespace: id.split('.').pop(), |
| 52 | + version: '1.0.0', |
| 53 | + type: 'plugin', |
| 54 | + name: id.split('.').pop(), |
| 55 | +}); |
| 56 | + |
| 57 | +const instance = (over: Record<string, unknown> = {}) => ({ |
| 58 | + name: 'sap_s4', |
| 59 | + label: 'SAP S/4HANA', |
| 60 | + type: 'api', |
| 61 | + provider: 'fake', |
| 62 | + providerConfig: {}, |
| 63 | + auth: { type: 'bearer', credentialRef: REF }, |
| 64 | + ...over, |
| 65 | +}); |
| 66 | + |
| 67 | +const sapOrders = () => ({ |
| 68 | + name: 'sap_orders', |
| 69 | + driver: 'odata', |
| 70 | + config: { serviceUrl: 'https://sap.example.com/odata/v4/orders' }, |
| 71 | + schemaMode: 'external', |
| 72 | + external: { connector: 'sap_s4' }, |
| 73 | +}); |
| 74 | + |
| 75 | +/** The borrowing input, which declares no connector of its own. */ |
| 76 | +const looseBorrower = () => |
| 77 | + defineStack({ manifest: pluginManifest('com.acme.ds'), datasources: [sapOrders()] } as never, { strict: false }); |
| 78 | + |
| 79 | +/** |
| 80 | + * An input that carries `packages[]` and, on its top level only, `connectors` |
| 81 | + * — the mixed shape. `bodyConnectors` lands on the package body instead. |
| 82 | + */ |
| 83 | +const mixed = (topLevel: unknown[] | undefined, bodyConnectors?: unknown[]) => |
| 84 | + defineStack( |
| 85 | + { |
| 86 | + manifest: pluginManifest(MIXED_ID), |
| 87 | + ...(topLevel ? { connectors: topLevel } : {}), |
| 88 | + packages: [{ manifest: { ...pluginManifest(BODY_ID), ...(bodyConnectors ? { connectors: bodyConnectors } : {}) } }], |
| 89 | + } as never, |
| 90 | + { strict: false }, |
| 91 | + ); |
| 92 | + |
| 93 | +/** What `AppPlugin.init` hands the `manifest` service. */ |
| 94 | +const payload = (bundle: Record<string, unknown>) => ({ ...(bundle.manifest as object), ...bundle }); |
| 95 | + |
| 96 | +const kernels: ObjectKernel[] = []; |
| 97 | +const envKeys: string[] = []; |
| 98 | +afterEach(async () => { |
| 99 | + for (const k of kernels.splice(0)) await k.shutdown().catch(() => {}); |
| 100 | + for (const key of envKeys.splice(0)) delete process.env[key]; |
| 101 | +}); |
| 102 | + |
| 103 | +function setEnv(key: string, value: string): void { |
| 104 | + envKeys.push(key); |
| 105 | + process.env[key] = value; |
| 106 | +} |
| 107 | + |
| 108 | +/** Boot the engine and the automation plugin; register `stack` through the `manifest` service at init. */ |
| 109 | +async function boot(stack: Record<string, unknown>) { |
| 110 | + const kernel = new ObjectKernel({ logger: { level: 'fatal' }, gracefulShutdown: false }); |
| 111 | + kernels.push(kernel); |
| 112 | + const driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true }); |
| 113 | + await kernel.use({ |
| 114 | + name: 'test.driver.sqlite', |
| 115 | + type: 'standard', |
| 116 | + version: '1.0.0', |
| 117 | + async init(ctx: PluginContext) { |
| 118 | + ctx.registerService('driver.default', driver); |
| 119 | + }, |
| 120 | + } as Plugin); |
| 121 | + await kernel.use(new ObjectQLPlugin()); |
| 122 | + await kernel.use(new AutomationServicePlugin({ suspendedRunStore: 'memory', credentialResolver: () => undefined })); |
| 123 | + await kernel.use({ |
| 124 | + name: 'test.stack', |
| 125 | + type: 'standard', |
| 126 | + version: '1.0.0', |
| 127 | + dependencies: ['com.objectstack.engine.objectql', 'com.objectstack.service-automation'], |
| 128 | + async init(ctx: PluginContext) { |
| 129 | + ctx.getService<AutomationEngine>('automation').registerConnectorProvider('fake', (pctx: any) => ({ |
| 130 | + def: { name: pctx.name, label: pctx.label, type: 'api', actions: [{ key: 'request', label: 'Request' }] }, |
| 131 | + handlers: { request: async () => ({ status: 200, ok: true, body: {} }) }, |
| 132 | + })); |
| 133 | + await ctx.getService<{ register(m: unknown): Promise<void> }>('manifest').register(payload(stack)); |
| 134 | + }, |
| 135 | + } as Plugin); |
| 136 | + await kernel.bootstrap(); |
| 137 | + const ql = kernel.getService<ObjectQL>('objectql'); |
| 138 | + const source = kernel.getService<IConnectorCredentialSource>(CONNECTOR_CREDENTIAL_SOURCE_SERVICE); |
| 139 | + return { ql, source }; |
| 140 | +} |
| 141 | + |
| 142 | +const connectorOwners = (ql: ObjectQL): Array<[unknown, unknown]> => |
| 143 | + (ql.registry.listItems('connector') as Array<{ name?: unknown; _packageId?: unknown }>) |
| 144 | + .map((c) => [c.name, c._packageId]); |
| 145 | + |
| 146 | +describe('[ADR-0015 D7] a connector a mixed composed input declares only on its top level', () => { |
| 147 | + it('is accepted at build: the composed check judges that it can lend', () => { |
| 148 | + expect(() => composeStacks([mixed([instance()]), looseBorrower()] as never, { manifest: 'preserve' } as never)).not.toThrow(); |
| 149 | + }); |
| 150 | + |
| 151 | + it('lends its credential at boot, registered under the stack\'s own id', async () => { |
| 152 | + setEnv(REF, DUMMY_ENV_VALUE); |
| 153 | + const stack = composeStacks([mixed([instance()]), looseBorrower()] as never, { manifest: 'preserve' } as never) as Record<string, unknown>; |
| 154 | + const { ql, source } = await boot(stack); |
| 155 | + const ownerId = (stack.manifest as { id?: string }).id; |
| 156 | + const handle = await source.borrow('sap_s4'); |
| 157 | + expect(handle.connector).toBe('sap_s4'); |
| 158 | + await expect(handle.get()).resolves.toEqual({ auth: { type: 'bearer', token: DUMMY_ENV_VALUE } }); |
| 159 | + expect(connectorOwners(ql)).toEqual([['sap_s4', ownerId]]); |
| 160 | + }); |
| 161 | + |
| 162 | + it('is judged by the lender at boot when it cannot lend: a descriptor is refused as one, not as undeclared', async () => { |
| 163 | + // Hand-assembled: the composed check refuses a borrow of a descriptor. |
| 164 | + const descriptor = { name: 'sap_s4', label: 'SAP S/4HANA', type: 'api' }; |
| 165 | + const stack = composeStacks([mixed([descriptor]), defineStack({ manifest: pluginManifest('com.acme.ds') } as never)] as never, { |
| 166 | + manifest: 'preserve', |
| 167 | + } as never) as Record<string, unknown>; |
| 168 | + const { ql, source } = await boot(stack); |
| 169 | + const refused = await source.borrow('sap_s4').then(() => undefined, (err: unknown) => err as { status?: number; message?: string }); |
| 170 | + expect(refused?.status).toBe(422); |
| 171 | + expect(refused?.message).not.toContain('is not declared'); |
| 172 | + expect(refused?.message).toContain('declares no provider'); |
| 173 | + expect(connectorOwners(ql).map(([name]) => name)).toEqual(['sap_s4']); |
| 174 | + }); |
| 175 | + |
| 176 | + it('CONTROL: an instance a package body declares lends at boot, owned by that body', async () => { |
| 177 | + setEnv(REF, DUMMY_ENV_VALUE); |
| 178 | + const stack = composeStacks([mixed(undefined, [instance()]), looseBorrower()] as never, { manifest: 'preserve' } as never) as Record<string, unknown>; |
| 179 | + const { ql, source } = await boot(stack); |
| 180 | + expect(connectorOwners(ql)).toEqual([['sap_s4', BODY_ID]]); |
| 181 | + await expect((await source.borrow('sap_s4')).get()).resolves.toEqual({ auth: { type: 'bearer', token: DUMMY_ENV_VALUE } }); |
| 182 | + }); |
| 183 | +}); |
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
0 commit comments