@voltro/testing 0.80.0 → 0.82.0

package/THIRD-PARTY-NOTICES.md

@@ -4551,7 +4551,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## undici@8.10.0
+## undici@8.11.2
 
 License: MIT
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { AnonymousPolicy } from '@voltro/protocol';
 import { AppContext } from '@voltro/runtime';
 import { AuthStrategy } from '@voltro/protocol';
 import { changeDelete } from '@voltro/database';
@@ -27,6 +28,7 @@ import { RpcInterceptor } from '@voltro/protocol';
 import { RpcKind } from '@voltro/protocol';
 import { Schema } from 'effect';
 import { Scope } from 'effect';
+import { ServiceApi } from '@voltro/protocol';
 import { Subject } from '@voltro/protocol';
 import { SubscribeContext } from '@voltro/runtime';
 import { SyncLogger } from '@voltro/logger';
@@ -223,6 +225,17 @@ export declare const fixtureRow: (table: TableLike, overrides?: Row) => Row;
  */
 export declare const frozenTime: (at: Date | number | string | MockClock) => Effect.Effect<MockClock, never, Scope.Scope>;
 
+declare type HandlerFor<D> = D extends {
+    readonly input: infer I;
+    readonly output: infer O;
+} ? (input: I extends {
+    readonly Type: infer T;
+} ? T : never) => Promise<O extends {
+    readonly Type: infer T;
+} ? T : never> | (O extends {
+    readonly Type: infer T;
+} ? T : never) : never;
+
 /**
  * What `invoke` resolves to for a handler returning `Result`: an `Effect`'s
  * SUCCESS value, an awaited `Promise`, or the value itself.
@@ -287,6 +300,10 @@ export declare const invoke: <D extends Pick<ProcedureDescriptor, "input">, Resu
 /** Can we open a TCP connection to `host:port` within `timeoutMs`? */
 export declare const isTcpReachable: (target: ReachableTarget) => Promise<boolean>;
 
+export declare const makeServiceApiMock: <P>(descriptors: Readonly<Record<string, MockDescriptor>>, handlers: ServiceApiMockHandlers<P>, options?: {
+    readonly name?: string;
+}) => ServiceApiMock<P>;
+
 /**
  * A `SubscribeContext` typed as the real one.
  *
@@ -352,15 +369,30 @@ export declare interface MakeTestAppOptions {
      * itself the behaviour most worth testing, and the one `invoke` cannot reach.
      */
     readonly strategies?: ReadonlyArray<AuthStrategy>;
-    /** Refuse an anonymous caller that carries no tenant (`Unauthenticated`).
-     *  Passed straight to `composeAuthStrategies`. */
-    readonly anonymousTenantRequired?: boolean;
+    /** What an unauthenticated caller is — the app's `auth.anonymous`
+     *  (`'refuse' | 'no-tenant' | 'header' | { tenantId }`), passed straight to
+     *  `composeAuthStrategies`. Default: the `voltro dev` convenience — the
+     *  `x-tenant` header's tenant, else `acme` — so a test sees what the dev
+     *  server would; pass the app's own decision to see what serve would. */
+    readonly anonymous?: AnonymousPolicy;
     /** HTTP idempotency binding — the same `{ store, header, ttlMs }` the serve
      *  path builds from `app.config.ts`'s `idempotency` field. */
     readonly idempotency?: RestServeBindings['idempotency'];
     /** The api's `publicApi:` config — the REST profile the projections speak,
      *  the same object `app.config.ts` declares. Absent → `'rpc'`. */
     readonly publicApiProfile?: PublicApiProfileConfig;
+    /**
+     * The api's `security` settings that decide the caller's address — the same
+     * fields `app.config.ts` declares. `ctx.remoteAddr` is resolved from a
+     * request's `remoteAddr` and headers through them, by the function the
+     * server's listener calls, so a forwarding header is believed here exactly
+     * when it would be in production. `VOLTRO_TRUSTED_PROXIES` applies as it does
+     * there. Absent → no proxy is trusted.
+     */
+    readonly security?: {
+        readonly trustedProxies?: ReadonlyArray<string>;
+        readonly clientAddressHeader?: string;
+    };
 }
 
 export declare const makeTestContext: <RowFilterCtx = unknown>(options?: MakeTestContextOptions<RowFilterCtx>) => TestContext;
@@ -369,6 +401,13 @@ export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
     /** The acting subject. Default: anonymous, no tenant. Read it back at
      *  `ctx.request.subject` (the same place a live handler reads it). */
     readonly subject?: Subject;
+    /**
+     * `ctx.apis` — the apps this handler calls. Pass a fake per binding, usually
+     * `makeServiceApiMock<ServiceProcedures>({ … })` from `@voltro/testing`, which
+     * decodes every input and output against the callee's real schemas. Absent →
+     * the empty object, as for an app with no `apis:`.
+     */
+    readonly apis?: AppContext['apis'];
     /** Optional connection fixture, or the actual RuntimeContext.connection from
      * a listener test. Shared by transaction/subject re-scopes, never invented by
      * the harness; omitting it models an internal invocation. */
@@ -517,7 +556,7 @@ export declare interface MakeWorkflowRunnerOptions {
     readonly workflows?: ReadonlyArray<WorkflowEntry>;
 }
 
-export declare const markRestInvocation: (ctx: TestContext, publicApi: PublicApiSpec) => void;
+export declare const markRestInvocation: (ctx: TestContext, publicApi: PublicApiSpec, remoteAddr?: string) => void;
 
 /** Minimal AI mock surface. The full `mockAi({...})` helper is owned by
  *  the AI package (plan 05); typed here as an optional injected interface
@@ -560,6 +599,12 @@ export declare class MockClock {
     uninstall(): void;
 }
 
+declare interface MockDescriptor {
+    readonly kind: string;
+    readonly input: unknown;
+    readonly output: unknown;
+}
+
 export declare class MockLLM {
     private readonly queue;
     readonly calls: MockLLMCall[];
@@ -600,10 +645,16 @@ export declare class MockWebhooks {
      *  testable. */
     emit<P>(event: string | {
         readonly id?: string;
+        readonly name?: string;
         readonly event?: string;
     }, payload: P): Promise<{
         readonly delivered: number;
     }>;
+    /** Mirrors `WebhooksServiceShape.listTargets`. No targets are subscribed
+     *  here, so a handler that reads them — a status page, a health check — gets
+     *  the empty list the real service gives an app that has none, instead of
+     *  throwing because the recorder lacked the method. */
+    listTargets(_event?: string, _scope?: Readonly<Record<string, unknown>>): Promise<ReadonlyArray<never>>;
     /** Every payload emitted for one event, oldest first. */
     payloadsFor(event: string): ReadonlyArray<unknown>;
     /** The most recent emission of an event, or undefined. */
@@ -702,9 +753,19 @@ export declare const reportEngineVersion: (label: string, probe: () => Promise<s
  */
 export declare const resetAfterCommit: (ctx: TestContext) => void;
 
-export declare const restInvocationOf: (ctx: TestContext) => {
+/** A context that is running ONE `publicApi`-projected request — `invoke`
+ *  reads it to put `surface: 'rest'` and the spec on the interceptor meta,
+ *  exactly as the serve pipeline does for a `/v1` call. Set by `makeTestApp`
+ *  on the per-request scoped context; never on the one a test holds. */
+export declare interface RestInvocation {
     readonly publicApi: PublicApiSpec;
-} | undefined;
+    /** The request's resolved address — the serve pipeline hands it to the
+     *  interceptors of a projected call (`projectedRequest`), so a per-address
+     *  limit reads it there and must read it here. */
+    readonly remoteAddr?: string | undefined;
+}
+
+export declare const restInvocationOf: (ctx: TestContext) => RestInvocation | undefined;
 
 export { Row }
 
@@ -752,6 +813,27 @@ export declare const runInStoreTransaction: <T>(ctx: TestContext, work: (txCtx:
  *  `storeForTenant` view). NOT the cross-tenant `system()` below. */
 export declare const serviceAccount: (id: string, options?: TestSubjectOptions) => Subject;
 
+export declare interface ServiceApiMock<P> {
+    /** Pass this as `makeTestContext({ apis: { <name>: mock.api } })`. */
+    readonly api: ServiceApi<P>;
+    /** Every call made, in order — optionally for one tag. */
+    readonly calls: (tag?: keyof P & string) => ReadonlyArray<ServiceApiMockCall>;
+    /** Push a new value to every open subscription of a query. */
+    readonly emit: (tag: keyof P & string, input: unknown, value: unknown) => void;
+}
+
+export declare interface ServiceApiMockCall {
+    readonly tag: string;
+    readonly input: unknown;
+    readonly idempotencyKey: string | undefined;
+}
+
+/** Per tag: what the fake callee answers. A tag with no handler answers
+ *  `ApiUnavailable` — the honest outcome of calling an app that is not there. */
+export declare type ServiceApiMockHandlers<P> = {
+    readonly [K in keyof P]?: HandlerFor<P[K]>;
+};
+
 /**
  * The handler service layer for this context — every registered plugin's
  * `services:` layer, then the app's own `layers:`, merged in that order.
@@ -774,6 +856,45 @@ export declare const serviceAccount: (id: string, options?: TestSubjectOptions)
  */
 export declare const serviceLayerFor: (ctx: TestContext) => Layer.Layer<never, never, never> | undefined;
 
+export declare interface StartedTestApp {
+    readonly name: string;
+    readonly port: number;
+    /** `http://127.0.0.1:<port>` — the app's HTTP origin. */
+    readonly url: string;
+    /** `ws://127.0.0.1:<port>/ws` — the socket a service client connects to. */
+    readonly wsUrl: string;
+    /** Everything the process printed so far. */
+    readonly log: () => string;
+    readonly stop: () => Promise<void>;
+}
+
+export declare interface StartedTestApps<Name extends string> {
+    readonly apps: Readonly<Record<Name, StartedTestApp>>;
+    /** The credential of an edge — what a test presents to call the callee AS the caller. */
+    readonly token: (caller: Name, callee: Name) => string;
+    /** Stops every app; safe to call twice. */
+    readonly stop: () => Promise<void>;
+}
+
+/**
+ * Boot the apps — every callee before its callers — wait until each answers
+ * `/internal/readiness`, and return their ports, logs and edge credentials. A
+ * process that exits or does not become ready in time stops every other one
+ * and rejects with its log.
+ */
+export declare const startTestApps: <Name extends string>(options: StartTestAppsOptions<Name>) => Promise<StartedTestApps<Name>>;
+
+export declare interface StartTestAppsOptions<Name extends string> {
+    readonly apps: Readonly<Record<Name, TestAppSpec>>;
+    readonly edges?: ReadonlyArray<TestAppEdge<Name>>;
+    /** `dev` (codegen, migrations, minted secrets — the default) or `serve`. */
+    readonly mode?: 'dev' | 'serve';
+    /** Path to `voltro.mjs`. Default: `@voltro/cli` as the first app resolves it. */
+    readonly cli?: string;
+    /** How long EACH app may take to answer `/internal/readiness`. Default 5 minutes. */
+    readonly bootTimeoutMs?: number;
+}
+
 /**
  * The CROSS-TENANT machine actor — cron, workflows, backfills. `tenantId` is
  * `null` by construction and the tenant read-scope mixin reads that as "every
@@ -811,6 +932,22 @@ export declare interface TestApp {
     readonly paths: ReadonlyArray<string>;
 }
 
+export declare interface TestAppEdge<Name extends string> {
+    /** The calling app (its `name`). */
+    readonly caller: Name;
+    /** The called app (its `name`). */
+    readonly callee: Name;
+    /** The caller's `apis:` key for the callee. */
+    readonly binding: string;
+}
+
+export declare interface TestAppSpec {
+    /** The app's directory (the one holding `app.config.ts`). */
+    readonly root: string;
+    /** Extra environment for this app — its `DB_URL`, feature flags, … */
+    readonly env?: Readonly<Record<string, string>>;
+}
+
 /** The test context IS an `AppContext` (store + request + cache), plus the
  *  deterministic doubles and the subject/tenant re-scopers. Because it
  *  extends `AppContext`, you can pass it straight into an executor typed
@@ -939,6 +1076,14 @@ export declare interface TestRequestOptions {
      *  `withHeaders`) headers. Names are lowercased, as the transport delivers
      *  them. */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * The address the connection comes from — the socket peer. With no trusted
+     * proxy declared (the default) it is `ctx.remoteAddr`; behind a declared
+     * proxy, `x-forwarded-for` from that peer decides, as on the server.
+     * Defaults to `127.0.0.1`. Two values are two clients, which is how a route
+     * test shows a per-address limit.
+     */
+    readonly remoteAddr?: string;
 }
 
 export declare interface TestResponse {