@truenas/api-client 6.0.1 → 6.0.2

package/dist/testing/index.d.cts

@@ -0,0 +1,483 @@
+import * as rxjs from 'rxjs';
+import { Subscription, Observable } from 'rxjs';
+import { aE as TrueNasConnection, aF as TrueNasMessage, an as TrueNasErrorFrame, aG as TrueNasAuthenticator, d as ApiVersion, ak as TrueNasAuthMechanism, R as AuthResponse, S as AuthResponseType, a2 as Job, a5 as JobProgress, n as ApiDirectoryShape, V as CallMethod, ab as QueryMethod, X as CallResponse, W as CallParams, a9 as QueryEntity, a3 as JobMethod, a6 as JobResult, a0 as EventName, a1 as EventUnion, aj as SupportedApiVersion, T as TrueNasApiClient, aH as DerivedDirectory, am as TrueNasErrorData } from '../truenas-auth-mechanism.enum-DikfjVxa.cjs';
+import 'rxjs/webSocket';
+
+/** How a fake connection is set up. Every field has a usable default. */
+interface FakeConnectionOptions {
+    /** Reported as the appliance's uuid; only ever used for log correlation. */
+    uuid?: string;
+    /** The path the real connection would have opened a socket on. */
+    websocketPath?: string;
+    /**
+     * Whether the connection starts in the opened state. Defaults to `true`, as
+     * it does through `createFakeClient`: a closed connection queues sends
+     * instead of writing them, which is rarely what a spec building one directly
+     * is after.
+     */
+    opened?: boolean;
+    /**
+     * Whether a frame nothing is scripted to answer fails instead of hanging.
+     * Defaults to `false`.
+     *
+     * Off by default because the two ways to answer cannot be told apart at
+     * `send` time. A spec that scripts everything with `mock` has registered its
+     * answers before the frame goes out; a spec that drives frames by hand calls
+     * `reply` *after* it — so refusing an unregistered method would break every
+     * hand-driven spec, 24 of them in this repo's own suite. Strictness is the
+     * spec's claim that it scripted everything, which only the spec can make.
+     */
+    strict?: boolean;
+}
+/**
+ * A `TrueNasConnection` that never opens a socket, and that a test drives by
+ * hand.
+ *
+ * A real subclass, so the real `TrueNasApi` and clients run on it without an
+ * `as unknown as` cast. `send` matches the real one: it queues while closed,
+ * writes on open, and drops frames whose caller unsubscribed. The rest is
+ * inherited and inert, except the base 20-second ping timer, which never sends
+ * but lives until `close()`.
+ */
+declare class FakeConnection extends TrueNasConnection {
+    private readonly incoming;
+    private readonly frames;
+    /** Frames handed to `send` while closed, waiting for the socket. */
+    private readonly queued;
+    private readonly autoReplies;
+    /** Set by `close()`. Latched, because the real connection cannot come back. */
+    private terminated;
+    /** See {@link FakeConnectionOptions.strict}. Assigned in the constructor. */
+    private readonly strict;
+    /**
+     * The canonical streams, re-pointed at what this class actually drives.
+     *
+     * The base derives all three from `connection$`, which on a disabled
+     * connection reports one state and then nothing: `{ state: 'closed' }`. So
+     * they describe the connection that never connects, not the one the test is
+     * driving — `messages$` stayed silent while `receive` delivered, `opened$`
+     * stayed `[false]` through every simulated open, and `closed$` reported a
+     * connection that had never been up. `messages()` is a shim over `messages$`;
+     * leaving them disagreeing puts the divergence in the members a consumer is
+     * most likely to reach for.
+     */
+    messages$: rxjs.Observable<TrueNasMessage>;
+    opened$: rxjs.Observable<boolean>;
+    closed$: rxjs.Observable<undefined>;
+    constructor(options?: FakeConnectionOptions);
+    /** Every frame handed to `send`, in order. */
+    get sent(): readonly TrueNasMessage[];
+    /**
+     * Records the frame, or queues it until the connection opens.
+     *
+     * The real `send` queues on `ws$` until a socket exists and returns the
+     * subscription holding that queue open; a caller who gives up unsubscribes
+     * it and the frame never goes out. Both halves are reproduced, because
+     * "records everything regardless of `opened`" is precisely the divergence
+     * the hand-rolled double had — it forwarded straight through — and moving it
+     * in here would have been the same bug in a better-looking place.
+     */
+    send(message: TrueNasMessage): Subscription;
+    /**
+     * Answer any frame for `method` as soon as it is written.
+     *
+     * The narrow ancestor of `mockCall`: enough to let a collaborator that talks
+     * to the appliance — the authenticator, for one — run its real code against
+     * a scripted answer rather than be replaced by a fake of itself.
+     *
+     * One answer per method, last registration wins. The one it replaced is
+     * returned so a caller that needs to share the method can chain to it rather
+     * than take it over silently.
+     */
+    autoReply(method: string, answer: (frame: TrueNasMessage) => void): ((frame: TrueNasMessage) => void) | undefined;
+    private write;
+    /** Deliver a message as if middleware had sent it. */
+    receive(message: TrueNasMessage): void;
+    /**
+     * Answer the most recent frame carrying `method`, by its id.
+     *
+     * Ids are what correlate a reply to a request, and a test that had to read
+     * them itself would be asserting on the id generator. Most recent rather
+     * than first: a spec that calls the same method twice is asking about the
+     * second one.
+     */
+    reply(method: string, result: unknown): void;
+    /**
+     * As {@link reply}, with a JSON-RPC error instead of a result.
+     *
+     * Typed as the frame `/api/<version>` sends and nothing else: `code` and
+     * `message` outside, the TrueNAS payload under `data`. The legacy
+     * `/websocket` shape — those payload fields at the top level — is not
+     * accepted, so a spec cannot script an error this client can never receive.
+     * It was accepted until now only because the parameter was the loose
+     * `ApiError` union, which admits both.
+     *
+     * The cast is gone with it: the frame's own type says this is what an error
+     * looks like.
+     */
+    replyError(method: string, error: TrueNasErrorFrame): void;
+    /**
+     * Raise `opened` and flush whatever was queued, as the socket opening would.
+     *
+     * The queue drains after `opened` goes true, which is the order the real
+     * connection produces: `send` is waiting on `ws$`, and `ws$` emits because a
+     * socket arrived.
+     */
+    simulateOpen(): void;
+    /**
+     * Lower `opened` and fire `closed`, as a socket closing would.
+     *
+     * Named for what it simulates rather than overriding `close()`, which on the
+     * real connection means "stop, and do not retry" — a different verb that
+     * callers already use for teardown.
+     */
+    simulateClose(): void;
+    /**
+     * Terminal, as on the real connection: the streams end and nothing more is
+     * written.
+     *
+     * `simulateClose` is the socket dropping — recoverable, and the client will
+     * try again. This is the caller giving up on the connection for good, so the
+     * message stream completes and `send` has nowhere to put a frame.
+     */
+    close(): void;
+    private idOf;
+}
+
+/** One recorded login attempt. */
+interface RecordedLogin {
+    mechanism: TrueNasAuthMechanism;
+    /** The username, token or key the caller passed, whichever the mechanism takes. */
+    credential: string;
+}
+/**
+ * A `TrueNasAuthenticator` that records its logins and answers them without a
+ * socket.
+ *
+ * Every override records the attempt and then calls the real method, so the
+ * real code sends the frame, stores credentials and interprets the response.
+ * `succeedNextLogin` / `failNextLogin` only script the connection's reply — a
+ * fake that decided success itself would disagree with the real client on
+ * what an answer means.
+ */
+declare class FakeAuthenticator extends TrueNasAuthenticator {
+    private readonly fakeConnection;
+    private readonly attempts;
+    /** Armed by the scripting methods; consumed by the next login that is made. */
+    private armed;
+    /**
+     * Answers waiting for their frames, oldest first.
+     *
+     * Bound when the login is *made*, not when the reply goes out. Reading an
+     * armed answer at reply time meant a second login armed in the meantime
+     * answered the first — two logins in flight is exactly what testing
+     * supersession looks like, so scripting both is the ordinary case, and it
+     * produced the same wrong verdict this class was rewritten to stop
+     * producing.
+     */
+    private readonly pending;
+    constructor(fakeConnection: FakeConnection, version?: ApiVersion);
+    /**
+     * Every login attempt, in order.
+     *
+     * Including the ones the base class makes itself: the auto-relogin runs
+     * through these same methods, and nothing here distinguishes it from a
+     * caller's login. A spec counting logins across a reconnect should expect
+     * that one.
+     */
+    get logins(): readonly RecordedLogin[];
+    /** The next login is answered with this response. Defaults to a success. */
+    succeedNextLogin(response?: Partial<AuthResponse>): void;
+    /**
+     * The next login is answered with a rejection.
+     *
+     * A `response_type` rather than an `Error`, so what the caller sees is
+     * whatever the real authenticator makes of it — the `AuthError` codes
+     * included, which a hand-thrown `Error` could not produce.
+     */
+    failNextLogin(responseType?: AuthResponseType): void;
+    /**
+     * Records the attempt and binds its answer, in that order, before the real
+     * method puts a frame on the wire.
+     */
+    private record;
+    private success;
+    loginWithUserPass(username: string, password: string): Observable<AuthResponse>;
+    loginWithToken(token: string): Observable<AuthResponse>;
+    loginWithApiKey(credentials: {
+        username: string;
+        key: string;
+    }): Observable<AuthResponse>;
+    loginWithOtp(code: string): Observable<AuthResponse>;
+}
+
+/**
+ * Overrides for {@link fakeJob}. `progress` is partial one level down, so a
+ * fixture naming a percent need not name the description beside it. Named so
+ * a consumer can write a helper that takes one, as the other builders are.
+ */
+interface FakeJobOverrides<R = unknown> extends Partial<Omit<Job<R>, 'progress'>> {
+    progress?: Partial<JobProgress>;
+}
+/**
+ * A complete `Job`, so a scripted one is the shape a caller actually reads —
+ * a partial fixture cast into place leaves `progress` undefined and breaks
+ * `job.progress.percent`.
+ *
+ * Defaults are what middleware sends for a job not yet started, including
+ * `result: null`. `satisfies` (not a cast) makes a regeneration that adds a
+ * required field fail here.
+ */
+declare function fakeJob<R = unknown>(overrides?: FakeJobOverrides<R>): Job<R>;
+
+/**
+ * Scripted answers, typed by the directory the client is typed against.
+ *
+ * Every one of these registers an *answer to a frame*, not a replacement for a
+ * verb. The client's own `dispatch`, job correlation and subscription
+ * bookkeeping run exactly as they do against an appliance; what changes is only
+ * what comes back. That is what makes a spec written against this a test of the
+ * client rather than a test of the double.
+ */
+interface MockAnswers<D extends ApiDirectoryShape> {
+    /**
+     * Answer `method` with `response`, or with whatever the function makes of
+     * the params it was called with.
+     *
+     * Query methods are excluded, and the exclusion is the point rather than a
+     * restriction: they live in the call directory, so `mock.call('user.query',
+     * 3)` is well-typed — a query method's response is the five-way union the
+     * server may return, and a number is one arm — and then answers all three
+     * query verbs from that one value. `mock.query` is where a collection is
+     * scripted, from rows that feed the three of them consistently.
+     */
+    call<M extends Exclude<CallMethod<D>, QueryMethod<D['call']> & string>>(method: M, response: CallResponse<D, M> | ((params: CallParams<D, M>) => CallResponse<D, M>)): void;
+    /**
+     * Answer a query method from one set of rows.
+     *
+     * `filters`, `select`, `order_by`, `limit` and `offset` are not applied: the
+     * rows given are the rows answered. The frame still carries whatever the
+     * caller sent, so a spec asserting on `sent` sees the real request — what is
+     * not modelled is middleware's evaluation of it.
+     *
+     * Feeds all three verbs, because on the wire they are one method
+     * distinguished by its options: `queryOne` sends `get: true` and gets the
+     * first row, `queryCount` sends `count: true` and gets the row count, and
+     * `query` gets the rows. Scripting them separately would let a spec disagree
+     * with itself about what the collection holds.
+     */
+    query<M extends QueryMethod<D['call']> & string>(method: M, rows: QueryEntity<D['call'], M>[]): void;
+    /**
+     * Answer a job method with the updates it should report, in order. Nothing
+     * is synthesised: a sequence with no terminal state never completes.
+     *
+     * Each update is completed by {@link fakeJob} from its defaults, not from the
+     * previous update — progress does not carry and success is not forced to
+     * 100. `arguments` is not filled in from the starting call either, since a
+     * job reached through `trackJob` has no such call.
+     *
+     * Returns the job's id (the first update may set it), for `trackJob`.
+     */
+    job<M extends JobMethod<D>>(method: M, updates: JobUpdate<JobResult<D, M>> | JobUpdate<JobResult<D, M>>[]): number;
+    /** Push a change to every subscriber of `events(event)`. */
+    emit<E extends EventName<D>>(event: E, change: EventUnion<D, E>): void;
+}
+/**
+ * One scripted job update. An alias rather than a second statement of the
+ * shape: `job` completes each update through {@link fakeJob}, so the two
+ * cannot usefully differ.
+ */
+type JobUpdate<R> = FakeJobOverrides<R>;
+
+/** A real client whose collaborators are the fakes, so a test can drive them. */
+type FakeTrueNasClient<D extends ApiDirectoryShape> = TrueNasApiClient<D> & {
+    readonly connection: FakeConnection;
+    readonly authenticator: FakeAuthenticator;
+    /** Scripted answers, typed by this client's directory. */
+    readonly mock: MockAnswers<D>;
+};
+/** How a fake client is set up. Every field has a usable default. */
+interface FakeClientOptions<V extends SupportedApiVersion> {
+    /** Selects both the client class and the directory the result is typed against. */
+    version?: V;
+    /**
+     * Whether the client starts authenticated. Defaults to `true`.
+     *
+     * Not because delivery depends on it — `events()` and the job stream filter
+     * the message, not the auth state, so a `receive` arrives either way — but
+     * because the client only *sends* its `core.subscribe` frames once
+     * `authenticated$` is true. A fake that starts unauthenticated has an empty
+     * `sent` where a real one would have registered its subscriptions, and a
+     * spec asserting on the wire sees a client that never subscribed.
+     */
+    authenticated?: boolean;
+    /** Whether the connection starts opened. Defaults to `true`. */
+    opened?: boolean;
+    /**
+     * Whether a call nothing is scripted to answer fails with
+     * {@link UnmockedCallError} instead of hanging. Defaults to `false`.
+     *
+     * A spec that scripts every call with `mock` can turn this on and find out
+     * which one it missed, by name, instead of watching a promise never settle.
+     * A spec that answers frames by hand with `connection.reply` cannot: the
+     * answer is registered after the frame goes out, and there is no way to tell
+     * that apart from a frame nobody will ever answer. See
+     * {@link FakeConnectionOptions.strict}.
+     */
+    strict?: boolean;
+}
+/**
+ * A real `TrueNasApiClient` with no socket or version discovery: only the
+ * connection and authenticator are fakes, so the real dispatch runs.
+ *
+ * ```typescript
+ * const client = createFakeClient({ version: 'v27.0.0' });
+ * client.mock.call('system.info', { hostname: 'truenas.local' });
+ * client.api.call('system.info').subscribe(info => …);
+ *
+ * // Instead of `mock.call`, a spec can answer the sent frame by hand:
+ * client.connection.reply('system.info', { hostname: 'truenas.local' });
+ * ```
+ */
+declare function createFakeClient<V extends SupportedApiVersion = SupportedApiVersion>(options?: FakeClientOptions<V>): FakeTrueNasClient<DerivedDirectory<V>>;
+
+/**
+ * Thrown when a strict fake connection is handed a frame nothing will answer.
+ *
+ * Named rather than a bare `Error` so a consumer's global guard can tell "the
+ * spec forgot a mock" from a failure the code under test produced.
+ *
+ * It cannot travel as an error *frame* — `dispatch` reduces any frame's error
+ * to `new Error(getApiErrorMessage(…))` — so it is thrown from `send`. A
+ * `TrueNasApi` verb dispatches inside a `defer` and so fails its observable;
+ * the authenticator sends from its own body and throws at the call site, which
+ * in practice is `logout` and `newApiKey` — the two `FakeAuthenticator` does
+ * not auto-reply.
+ */
+declare class UnmockedCallError extends Error {
+    readonly method: string;
+    readonly params: unknown;
+    constructor(method: string, params: unknown);
+}
+
+/**
+ * What this needs of a client, which is less than a client.
+ *
+ * Written structurally rather than as `FakeTrueNasClient<D>` so the directory
+ * type does not have to be named at the call site, and so a spec holding a
+ * client narrowed to its own version still passes one.
+ */
+interface SpyableClient {
+    readonly api: object;
+    readonly connection: object;
+    readonly authenticator: object;
+}
+/**
+ * A test runner's spy factory: `vi.fn` or `jest.fn`.
+ *
+ * Taken as an argument rather than imported, because this package does not
+ * depend on a runner and must not start.
+ *
+ * **One requirement the type cannot express: the returned function must invoke
+ * the implementation with its own `this`.** `vi.fn` and `jest.fn` do; an arrow
+ * does not, so `(impl) => vi.fn((...args) => impl(...args))` type-checks and
+ * hands every verb `undefined`. `withSpies` detects that and says so.
+ */
+type SpyFactory = <A extends unknown[], R>(implementation: (...args: A) => R) => (...args: A) => R;
+/**
+ * Wrap a fake client's verbs in the caller's spies, in place.
+ *
+ * ```typescript
+ * const client = withSpies(createFakeClient({ version: 'v27.0.0' }), vi.fn);
+ * expect(client.api.call).toHaveBeenCalledWith('system.info');
+ * ```
+ *
+ * Behaviour is preserved: each spy wraps the real method, which the runner
+ * invokes with the `this` of the call, so a spied call still dispatches and
+ * still answers from whatever `mock` scripted. Nothing is bound — see
+ * `spyOnMethods`. The client is mutated and returned rather than proxied,
+ * because a proxy would not be the object its own collaborators hold.
+ */
+declare function withSpies<C extends SpyableClient>(client: C, spy: SpyFactory): C;
+
+/**
+ * Flat overrides for a nested frame: say what varies, get the real shape.
+ *
+ * Picked field by field rather than `Partial<TrueNasErrorData>`, which would
+ * inherit that type's `[key: string]: unknown` — legitimate on the payload,
+ * since middleware adds `py_exception` there, and fatal on an overrides bag,
+ * because it turns off excess-property checking. `fakeApiError({ resaon: … })`
+ * typechecked, put `resaon` in the payload and left `reason` at its default.
+ */
+interface FakeApiErrorOverrides extends Partial<Pick<TrueNasErrorData, 'error' | 'errname' | 'reason' | 'extra' | 'trace'>> {
+    /** JSON-RPC code. Defaults to `-32001`, middleware's "method call error". */
+    code?: number;
+    /** JSON-RPC message. Defaults to `'Method call error'`, which is what `rpc.py` sends. */
+    message?: string;
+}
+/**
+ * The error a method call fails with on `/api/<version>`.
+ *
+ * The versioned endpoint wraps the TrueNAS payload in a JSON-RPC error —
+ * `{code: -32001, message: 'Method call error', data: {…}}` — and that nesting
+ * is the part worth a builder. The flat `{error, errname, extra, reason}` is
+ * `/websocket`'s, a route this client never opens; `getApiErrorMessage` reads
+ * either, so only a consumer branching on `error.code` or `error.data.errname`
+ * finds out. Verified at middleware `4303dc8`, `ws_handler/rpc.py:81-124`.
+ *
+ * `error` and `errname` are the caller's to keep consistent; middleware
+ * derives one from the other. `trace` defaults to one whose `class` and `repr`
+ * agree with `reason`; pass `null` only for the job-event payload.
+ */
+declare function fakeApiError(overrides?: FakeApiErrorOverrides): TrueNasErrorFrame;
+
+/**
+ * Overrides for {@link fakeApiVersion}: the fields the parser would have
+ * derived, for the versions it will not produce.
+ */
+type FakeApiVersionOverrides = Partial<ApiVersion>;
+/**
+ * A parsed `ApiVersion`, built by the parser the client itself uses.
+ *
+ * Going through `parseApiVersion` is the point: the year/minor/patch split and
+ * the websocket path are its rules, and writing them out here would be a
+ * second statement free to drift. It returns `ApiVersion | null`, so this
+ * throws on a string that does not parse rather than handing back a `null` a
+ * spec then carries a non-null assertion for.
+ *
+ * `overrides` is for versions the parser will not produce — a compatibility
+ * spec may want a year this package does not support — and is visible at the
+ * call site rather than smuggled in through a string.
+ */
+declare function fakeApiVersion(version?: SupportedApiVersion | (string & {}), overrides?: FakeApiVersionOverrides): ApiVersion;
+
+type UserInfo = NonNullable<AuthResponse['user_info']>;
+/**
+ * Overrides for {@link fakeAuthResponse}.
+ *
+ * `user_info` is partial one level down, like `fakeJob`'s `progress`: a spec
+ * that wants a different username should not have to restate twenty-odd fields
+ * around it. The structures below it — `privilege`, `group`, `attributes` —
+ * are replaced whole when given, because a partial `privilege` is a shape that
+ * cannot reach a consumer and merging it would invent one.
+ */
+interface FakeAuthResponseOverrides extends Partial<Omit<AuthResponse, 'user_info'>> {
+    user_info?: Partial<UserInfo>;
+}
+/**
+ * A complete `AuthResponse`, so a scripted login is the shape a caller reads.
+ *
+ * The envelope follows `response_type`: `auth.login_ex` is a discriminated
+ * union and each arm carries only its own fields, so `AUTH_ERR` comes back as
+ * `{ response_type }` rather than a success wearing a failure's label.
+ *
+ * | `response_type` | fields |
+ * |---|---|
+ * | `SUCCESS` | `user_info`, `authenticator`, `reconnect_token` |
+ * | `OTP_REQUIRED` | `username` |
+ * | `REDIRECT` | `urls` |
+ * | `AUTH_ERR`, `EXPIRED` | none |
+ */
+declare function fakeAuthResponse(overrides?: FakeAuthResponseOverrides): AuthResponse;
+
+export { AuthResponseType, type FakeApiErrorOverrides, type FakeApiVersionOverrides, type FakeAuthResponseOverrides, FakeAuthenticator, type FakeClientOptions, FakeConnection, type FakeConnectionOptions, type FakeJobOverrides, type FakeTrueNasClient, type JobUpdate, type MockAnswers, type RecordedLogin, type SpyFactory, type SpyableClient, TrueNasErrorData, TrueNasErrorFrame, UnmockedCallError, createFakeClient, fakeApiError, fakeApiVersion, fakeAuthResponse, fakeJob, withSpies };