cabloy 5.1.221 → 5.1.222

package/vona/src/suite-vendor/a-vona/modules/a-executor/src/bean/bean.executor.ts

@@ -1,12 +1,27 @@
-import type { FunctionAsync, VonaContext } from 'vona';
+import type { ExistingReadyCapability, FunctionAsync, VonaContext } from 'vona';
+import type { ServiceDb } from 'vona-module-a-orm';
 import type { IApiPathRecordMethodMap } from 'vona-module-a-web';
 
 import { isNil } from '@cabloy/utils';
-import { BeanBase, captureRequestBoundary } from 'vona';
+import {
+  BeanBase,
+  captureRequestBoundary,
+  isExistingReadyContext,
+  pinExistingReadyContext,
+  resolveExistingReadyCapability,
+} from 'vona';
 import { Bean } from 'vona-module-a-bean';
-import { ServiceTransactionAsyncLocalStorage } from 'vona-module-a-orm';
+import {
+  ServiceDatabaseAsyncLocalStorage,
+  ServiceTransactionAsyncLocalStorage,
+} from 'vona-module-a-orm';
 
-import type { INewCtxLifecycle, INewCtxOptions, IPerformActionOptions } from '../types/executor.ts';
+import type {
+  INewCtxLifecycle,
+  INewCtxOptions,
+  INewCtxReadyExistingOptions,
+  IPerformActionOptions,
+} from '../types/executor.ts';
 
 import { __delegateProperties } from '../lib/utils.ts';
 
@@ -16,12 +31,14 @@ export class BeanExecutor extends BeanBase {
     METHOD extends keyof IApiPathRecordMethodMap,
     PATH extends keyof IApiPathRecordMethodMap[METHOD],
   >(method: METHOD, path: PATH, options?: IPerformActionOptions): Promise<any> {
+    this._assertOrdinaryContext();
     // url
     const url = this.app.util.combineApiPath(path as any, '', true, true);
     return await this.scope.service.executor.performActionInner(method, url, options);
   }
 
   runInBackground(fn: FunctionAsync<void>) {
+    this._assertOrdinaryContext();
     return this.bean.database.switchDbIsolate(() => {
       return this.newCtx(fn);
     });
@@ -32,6 +49,7 @@ export class BeanExecutor extends BeanBase {
     options?: INewCtxOptions,
     lifecycle?: INewCtxLifecycle,
   ): Promise<RESULT> {
+    this._assertOrdinaryContext();
     options = Object.assign({}, options);
     // instanceName !== undefined means isolate
     options.instanceName =
@@ -48,6 +66,7 @@ export class BeanExecutor extends BeanBase {
     options?: INewCtxOptions,
     lifecycle?: INewCtxLifecycle,
   ): Promise<RESULT> {
+    this._assertOrdinaryContext();
     options = Object.assign({}, options);
     options.dbInfo = isNil(options.dbInfo) ? { level: 1 } : options.dbInfo;
     options.instanceName =
@@ -61,6 +80,7 @@ export class BeanExecutor extends BeanBase {
     options?: INewCtxOptions,
     lifecycle?: INewCtxLifecycle,
   ): Promise<RESULT> {
+    this._assertOrdinaryContext();
     return this._newCtxInnerStep1(
       () => {
         if (isNil(options?.dbInfo)) return this._newCtxInnerStep2(fn, options);
@@ -73,6 +93,106 @@ export class BeanExecutor extends BeanBase {
     );
   }
 
+  private _assertOrdinaryContext() {
+    if (isExistingReadyContext(this.ctx)) throw new Error('Existing-ready rebinding unavailable');
+  }
+
+  async newCtxReadyExisting<RESULT>(
+    capability: ExistingReadyCapability,
+    fn: FunctionAsync<RESULT>,
+    options?: INewCtxReadyExistingOptions,
+    lifecycle?: INewCtxLifecycle,
+  ): Promise<RESULT> {
+    this._assertOrdinaryContext();
+    const capture = captureRequestBoundary();
+    const owner = this.app.meta.completedReadiness;
+    const resolved = owner && resolveExistingReadyCapability(owner, capability, this.app);
+    if (!capture || capture.snapshot().portFault || !resolved)
+      throw new Error('Existing-ready unavailable');
+    const data = (value: object | undefined, allowed: readonly string[]) => {
+      const result: Record<string, any> = Object.create(null);
+      if (value === undefined) return result;
+      if (!value || typeof value !== 'object')
+        throw new Error('Existing-ready options unavailable');
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== null && proto !== Object.prototype)
+        throw new Error('Existing-ready options unavailable');
+      for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string' || !allowed.includes(key))
+          throw new Error('Existing-ready options unavailable');
+        const desc = Object.getOwnPropertyDescriptor(value, key)!;
+        if (!('value' in desc)) throw new Error('Existing-ready options unavailable');
+        result[key] = desc.value;
+      }
+      return result;
+    };
+    const selected = data(options, ['req', 'res', 'locale', 'tz']);
+    const hooks = data(lifecycle, ['initializeContext', 'onScopeOutcome']);
+    if (
+      (selected.locale !== undefined && typeof selected.locale !== 'string') ||
+      (selected.tz !== undefined && typeof selected.tz !== 'string') ||
+      (hooks.initializeContext !== undefined && typeof hooks.initializeContext !== 'function') ||
+      (hooks.onScopeOutcome !== undefined && typeof hooks.onScopeOutcome !== 'function')
+    ) {
+      throw new Error('Existing-ready options unavailable');
+    }
+    if (typeof fn !== 'function') throw new Error('Existing-ready unavailable');
+    let context: VonaContext;
+    try {
+      context = this.app.createAnonymousContext(selected.req, selected.res);
+    } catch (error) {
+      try {
+        const observed: unknown = hooks.onScopeOutcome?.('not_created');
+        if (observed && (typeof observed === 'object' || typeof observed === 'function')) {
+          const then = (observed as PromiseLike<unknown>).then;
+          if (typeof then === 'function') {
+            capture.reportFailure('observer_failed');
+            void new Promise<unknown>((resolve, reject) =>
+              then.call(observed, resolve, reject),
+            ).catch(() => {});
+          }
+        }
+      } catch {
+        capture.reportFailure('observer_failed');
+      }
+      throw error;
+    }
+    const execute = async () => {
+      if (!pinExistingReadyContext(owner, capability, this.app, context))
+        throw new Error('Existing-ready unavailable');
+      if (selected.locale !== undefined) context.locale = selected.locale;
+      if (selected.tz !== undefined) context.tz = selected.tz;
+      const initialized: unknown = hooks.initializeContext?.(context);
+      if (initialized && (typeof initialized === 'object' || typeof initialized === 'function')) {
+        const then = (initialized as PromiseLike<unknown>).then;
+        if (typeof then === 'function') {
+          await new Promise<unknown>((resolve, reject) =>
+            then.call(initialized, resolve, reject),
+          ).catch(() => undefined);
+          throw new Error('Context initializer must be synchronous');
+        }
+      }
+      if (
+        !resolveExistingReadyCapability(owner, capability, this.app) ||
+        capture.snapshot().portFault
+      ) {
+        throw new Error('Existing-ready unavailable');
+      }
+      const database = this.bean._getBean(ServiceDatabaseAsyncLocalStorage);
+      const transaction = this.bean._getBean(ServiceTransactionAsyncLocalStorage);
+      return database.dbStorage.run(resolved.handle as ServiceDb, () =>
+        transaction.run(async () => {
+          const result = await fn();
+          await context.commitsDone();
+          return result;
+        }, true),
+      );
+    };
+    return hooks.onScopeOutcome
+      ? this.app.ctxStorage.runObserved(context, execute, hooks.onScopeOutcome)
+      : this.app.ctxStorage.run(context, execute);
+  }
+
   private async _newCtxInnerStep1<RESULT>(
     fn: FunctionAsync<RESULT>,
     options: INewCtxOptions = {},

package/vona/src/suite-vendor/a-vona/modules/a-executor/src/types/executor.ts

@@ -22,6 +22,13 @@ export interface INewCtxOptions extends INewCtxBaseOptions {
   dbInfo?: Partial<IDbInfo>;
 }
 
+export interface INewCtxReadyExistingOptions {
+  req?: any;
+  res?: any;
+  locale?: keyof ILocaleRecord;
+  tz?: string;
+}
+
 export interface INewCtxLifecycle {
   initializeContext?: (ctx: VonaContext) => void;
   onScopeOutcome?: VonaScopeOutcomeObserver;

package/vona/src/suite-vendor/a-vona/modules/a-executor/test/readyExisting.test.ts

@@ -0,0 +1,423 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  beginCompletedInstance,
+  captureCompletedInstance,
+  createCompletedReadiness,
+  createRequestBoundary,
+  finishCompletedInstance,
+  pinExistingReadyContext,
+  runWithRequestBoundary,
+} from 'vona';
+import { app } from 'vona-mock';
+import {
+  ServiceDatabaseAsyncLocalStorage,
+  ServiceTransactionAsyncLocalStorage,
+} from 'vona-module-a-orm';
+
+import { BeanExecutor } from '../src/bean/bean.executor.ts';
+
+// Fixture-only internal access; use the canonical module shared by the public 'vona' imports.
+const completedReadinessUrl = new URL(
+  '../../../../../../packages-vona/vona-core/src/lib/core/completedReadiness.ts',
+  import.meta.url,
+);
+const {
+  beginCompletedApplication,
+  finishCompletedApplication,
+  getCompletedPublication,
+  issueExistingReadyCapability,
+  matchesCompletedRow,
+  provisionCompletedInstanceForTest,
+} = await import(completedReadinessUrl.href);
+const existingReadyAdmissionUrl = new URL(
+  '../../a-instance/src/lib/existingReadyAdmission.ts',
+  import.meta.url,
+);
+const { createExistingReadyAdmissionForTest } = await import(existingReadyAdmissionUrl.href);
+const admissionInternals = {
+  getCompletedPublication,
+  issueExistingReadyCapability,
+  matchesCompletedRow,
+};
+
+function fixture() {
+  const local = { meta: { completedReadiness: createCompletedReadiness({}) } };
+  const owner = createCompletedReadiness(local);
+  local.meta.completedReadiness = owner;
+  const registry = {},
+    route = {},
+    handle = {};
+  const row = Object.freeze({ id: 1, name: '', disabled: false, isolate: false, config: null });
+  let time = 0;
+  provisionCompletedInstanceForTest(owner, '', { registry, route, handle, isolate: false });
+  const started = beginCompletedApplication(owner);
+  const attempt = beginCompletedInstance(owner, '');
+  finishCompletedInstance(
+    owner,
+    '',
+    attempt,
+    captureCompletedInstance(owner, '', attempt, row, { marker: 'pinned' }),
+  );
+  finishCompletedApplication(owner, started, true);
+  const provider = createExistingReadyAdmissionForTest({
+    ...admissionInternals,
+    owner,
+    registry,
+    route,
+    read: () => ({ outcome: 'found', row }),
+    now: () => time,
+  });
+  return {
+    local,
+    owner,
+    handle,
+    provider,
+    expire: () => {
+      time = 1_000;
+    },
+  };
+}
+
+function localExecutor(local: object, current: object | undefined, create: () => never) {
+  const executor = Object.create(BeanExecutor.prototype) as BeanExecutor;
+  Object.defineProperties(executor, {
+    app: { value: { ...local, createAnonymousContext: create } },
+    ctx: { value: current },
+  });
+  return executor;
+}
+
+describe('ready-existing executor', { concurrency: false, timeout: 120_000 }, () => {
+  it(
+    'refuses forged, foreign, expired and conflicting options before context construction',
+    { timeout: 15_000 },
+    async () => {
+      const f = fixture();
+      let created = 0,
+        getters = 0;
+      // Use the exact app identity: the public entry must not adopt a foreign capability.
+      const executor = Object.create(BeanExecutor.prototype) as BeanExecutor;
+      Object.assign(f.local, {
+        createAnonymousContext() {
+          created++;
+          throw new Error('unexpected context');
+        },
+      });
+      Object.defineProperties(executor, { app: { value: f.local }, ctx: { value: undefined } });
+      await runWithRequestBoundary(createRequestBoundary(), async () => {
+        const result = await f.provider.admit('');
+        assert.equal(result.outcome, 'ready');
+        if (result.outcome !== 'ready') return;
+        await assert.rejects(executor.newCtxReadyExisting({} as never, async () => undefined));
+        await assert.rejects(
+          executor.newCtxReadyExisting({ ...result.capability } as never, async () => undefined),
+        );
+        for (const options of [
+          { instanceName: '' },
+          { dbInfo: {} },
+          { innerAccess: true },
+          { transaction: true },
+          { extraData: {} },
+          { authToken: 'synthetic' },
+        ]) {
+          await assert.rejects(
+            executor.newCtxReadyExisting(
+              result.capability,
+              async () => undefined,
+              options as never,
+            ),
+          );
+        }
+        const options = Object.defineProperty({}, 'locale', {
+          get() {
+            getters++;
+            return 'en-us';
+          },
+        });
+        await assert.rejects(
+          executor.newCtxReadyExisting(result.capability, async () => undefined, options),
+        );
+        const foreign = localExecutor(
+          { meta: { completedReadiness: createCompletedReadiness({}) } },
+          undefined,
+          () => {
+            created++;
+            throw new Error('unexpected context');
+          },
+        );
+        await assert.rejects(foreign.newCtxReadyExisting(result.capability, async () => undefined));
+        f.expire();
+        await assert.rejects(
+          executor.newCtxReadyExisting(result.capability, async () => undefined),
+        );
+      });
+      assert.equal(created, 0);
+      assert.equal(getters, 0);
+    },
+  );
+
+  it(
+    'pins before initializer and drains commit tails in the bound scope before disposal',
+    { timeout: 15_000 },
+    async () => {
+      // The managed runner owns its listener; executor scopes must leave it unchanged.
+      const server = app.server;
+      const registry = {},
+        route = {},
+        handle = {};
+      const row = { id: 1, name: '', disabled: false, isolate: false, config: null };
+      await app.bean.executor.mockCtx(async () => {
+        const database = app.bean._getBean(ServiceDatabaseAsyncLocalStorage);
+        const transaction = app.bean._getBean(ServiceTransactionAsyncLocalStorage);
+        const outer = transaction.transactionState;
+        const executor = Object.create(BeanExecutor.prototype) as BeanExecutor;
+        // A local app facade owns this test-only owner; actual context creation/ALS/disposal
+        // remain the runner-owned application's facilities. No singleton property is patched.
+        const facade = Object.create(app);
+        Object.defineProperty(facade, 'meta', { value: { ...app.meta } });
+        Object.defineProperties(executor, {
+          app: { value: facade },
+          ctx: { get: () => app.ctx },
+          bean: { get: () => app.bean },
+        });
+        // Capability app ownership is explicit; fixture publication uses the facade, not app.
+        const localOwner = createCompletedReadiness(facade);
+        facade.meta.completedReadiness = localOwner;
+        provisionCompletedInstanceForTest(localOwner, '', {
+          registry,
+          route,
+          handle,
+          isolate: false,
+        });
+        const appAttempt = beginCompletedApplication(localOwner),
+          localAttempt = beginCompletedInstance(localOwner, '');
+        finishCompletedInstance(
+          localOwner,
+          '',
+          localAttempt,
+          captureCompletedInstance(localOwner, '', localAttempt, row, { marker: 'pinned' }),
+        );
+        finishCompletedApplication(localOwner, appAttempt, true);
+        const localProvider = createExistingReadyAdmissionForTest({
+          ...admissionInternals,
+          owner: localOwner,
+          registry,
+          route,
+          read: () => ({ outcome: 'found', row }),
+          now: () => 0,
+        });
+        await runWithRequestBoundary(createRequestBoundary(), async () => {
+          const result = await localProvider.admit('');
+          assert.equal(result.outcome, 'ready');
+          if (result.outcome !== 'ready') return;
+          const events: string[] = [];
+          const returned = await executor.newCtxReadyExisting(
+            result.capability,
+            async () => {
+              events.push('callback');
+              const context = app.ctx;
+              const state = transaction.transactionState;
+              assert.equal((context.config as any).marker, 'pinned');
+              assert.equal(database.dbStorage.getStore(), handle);
+              assert.notEqual(state, outer);
+              assert.throws(() => {
+                context.instanceName = 'replacement' as never;
+              });
+              assert.throws(() => {
+                context.innerAccess = true;
+              });
+              context.commit(async () => {
+                events.push('commit');
+                assert.equal(app.ctx, context);
+                assert.equal(database.dbStorage.getStore(), handle);
+                assert.equal(transaction.transactionState, state);
+                await Promise.resolve();
+                context.commit(() => events.push('nested_commit'));
+                events.push('commit_done');
+              });
+              return 'result';
+            },
+            undefined,
+            {
+              initializeContext(ctx) {
+                events.push('initializer');
+                assert.equal((ctx.config as any).marker, 'pinned');
+                assert.equal(ctx.instanceName, '');
+                assert.equal(ctx.innerAccess, false);
+                assert.equal(transaction.transactionState, outer);
+              },
+              onScopeOutcome(outcome) {
+                events.push(outcome);
+              },
+            },
+          );
+          assert.equal(returned, 'result');
+          assert.deepEqual(events, [
+            'initializer',
+            'callback',
+            'commit',
+            'commit_done',
+            'nested_commit',
+            'disposed',
+          ]);
+          assert.equal(transaction.transactionState, outer);
+
+          for (const phase of ['callback', 'commit'] as const) {
+            events.length = 0;
+            const failure = new Error(`controlled_${phase}_failure`);
+            await assert.rejects(
+              executor.newCtxReadyExisting(
+                result.capability,
+                async () => {
+                  events.push('callback');
+                  app.ctx.commit(() => {
+                    events.push('commit');
+                    throw failure;
+                  });
+                  if (phase === 'callback') throw failure;
+                },
+                undefined,
+                { onScopeOutcome: outcome => events.push(outcome) },
+              ),
+              error => error === failure,
+            );
+            assert.deepEqual(
+              events,
+              phase === 'callback' ? ['callback', 'disposed'] : ['callback', 'commit', 'disposed'],
+            );
+            assert.equal(transaction.transactionState, outer);
+          }
+        });
+      });
+      assert.ok(app.server === server, 'executor scopes must preserve the runner-owned listener');
+    },
+  );
+
+  it(
+    'blocks every ordinary nested entry before database or getter work',
+    { timeout: 15_000 },
+    async () => {
+      const f = fixture();
+      await runWithRequestBoundary(createRequestBoundary(), async () => {
+        const result = await f.provider.admit('');
+        assert.equal(result.outcome, 'ready');
+        if (result.outcome !== 'ready') return;
+        const context = {};
+        assert.equal(pinExistingReadyContext(f.owner, result.capability, f.local, context), true);
+        let setups = 0;
+        const executor = localExecutor(f.local, context, () => {
+          setups++;
+          throw new Error('unexpected setup');
+        });
+        Object.defineProperty(executor, 'bean', {
+          get() {
+            setups++;
+            throw new Error('unexpected DB');
+          },
+        });
+        await assert.rejects(executor.newCtx(async () => undefined));
+        await assert.rejects(executor.newCtxIsolate(async () => undefined));
+        await assert.rejects(executor.mockCtx(async () => undefined));
+        await assert.rejects(executor.performAction('get' as never, '/' as never));
+        assert.throws(() => executor.runInBackground(async () => undefined));
+        assert.equal(setups, 0);
+      });
+
+      // Controlled failure port: real owned ALS/disposer logic, inert local app facade.
+      // The retained counter is custody proof, not a test-owned live application leak.
+      const failed = fixture();
+      let current: any;
+      let retained = 0,
+        callbacks = 0,
+        setups = 0;
+      const failure = new Error('controlled_dispose_failure');
+      const context = {
+        bean: {
+          async dispose() {
+            throw failure;
+          },
+        },
+      };
+      Object.assign(failed.local.meta, {
+        ctxCounter: {
+          increment() {
+            retained++;
+          },
+          decrement() {
+            retained--;
+          },
+        },
+      });
+      const local: any = failed.local;
+      const Storage = app.ctxStorage.constructor as new (
+        application: typeof app,
+      ) => typeof app.ctxStorage;
+      const storage = new Storage(local);
+      Object.defineProperty(local, 'currentContext', { get: () => storage.getStore() });
+      Object.assign(local, { ctxStorage: storage, createAnonymousContext: () => context });
+      const executor = Object.create(BeanExecutor.prototype) as BeanExecutor;
+      Object.defineProperties(executor, {
+        app: { value: local },
+        ctx: { get: () => current },
+        bean: {
+          get() {
+            setups++;
+            throw new Error('unexpected setup after initializer failure');
+          },
+        },
+      });
+      const events: string[] = [];
+      await runWithRequestBoundary(createRequestBoundary(), async () => {
+        const admitted = await failed.provider.admit('');
+        assert.equal(admitted.outcome, 'ready');
+        if (admitted.outcome !== 'ready') return;
+        await assert.rejects(
+          executor.newCtxReadyExisting(
+            admitted.capability,
+            async () => {
+              callbacks++;
+            },
+            undefined,
+            {
+              initializeContext(ctx) {
+                current = ctx;
+                assert.equal((ctx.config as any).marker, 'pinned');
+                assert.equal(ctx.innerAccess, false);
+                throw new Error('controlled_initializer_failure');
+              },
+              onScopeOutcome(outcome) {
+                events.push(outcome);
+              },
+            },
+          ),
+          error => error === failure,
+        );
+      });
+      assert.deepEqual(events, ['dispose_failed']);
+      assert.equal(retained, 1);
+      assert.equal(callbacks, 0);
+      assert.equal(setups, 0);
+    },
+  );
+
+  it(
+    'retains ordinary mock context behavior and actual healthy disposal',
+    { timeout: 15_000 },
+    async () => {
+      const outcomes: string[] = [];
+      let called = false;
+      await app.bean.executor.mockCtx(
+        async () => {
+          called = true;
+          assert.ok(app.ctx.instance);
+          assert.notEqual(app.ctx.innerAccess, false);
+        },
+        undefined,
+        { onScopeOutcome: outcome => outcomes.push(outcome) },
+      );
+      assert.equal(called, true);
+      assert.deepEqual(outcomes, ['disposed']);
+    },
+  );
+});