@milaboratories/pl-client 2.4.10

package/src/core/ll_client.ts

@@ -0,0 +1,228 @@
+import { PlatformClient } from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api.client';
+import {
+  ChannelCredentials,
+  InterceptingCall,
+  Interceptor,
+  status as GrpcStatus
+} from '@grpc/grpc-js';
+import {
+  AuthInformation,
+  AuthOps,
+  plAddressToConfig,
+  PlClientConfig,
+  PlConnectionStatus,
+  PlConnectionStatusListener
+} from './config';
+import { GrpcOptions, GrpcTransport } from '@protobuf-ts/grpc-transport';
+import { LLPlTransaction } from './ll_transaction';
+import { parsePlJwt } from '../util/pl';
+import { Agent, Dispatcher, ProxyAgent } from 'undici';
+import { inferAuthRefreshTime } from './auth';
+
+export interface PlCallOps {
+  timeout?: number;
+  abortSignal?: AbortSignal;
+}
+
+/** Abstract out low level networking and authorization details */
+export class LLPlClient {
+  public readonly conf: PlClientConfig;
+
+  /** Initial authorization information */
+  private authInformation?: AuthInformation;
+  /** Will be executed by the client when it is required */
+  private readonly onAuthUpdate?: (newInfo: AuthInformation) => void;
+  /** Will be executed if auth-related error happens during normal client operation */
+  private readonly onAuthError?: () => void;
+  /** Will be executed by the client when it is required */
+  private readonly onAuthRefreshProblem?: (error: unknown) => void;
+  /** Threshold after which auth info refresh is required */
+  private refreshTimestamp?: number;
+
+  private _status: PlConnectionStatus = 'OK';
+  private readonly statusListener?: PlConnectionStatusListener;
+
+  public readonly grpcTransport: GrpcTransport;
+  public readonly grpcPl: PlatformClient;
+
+  public readonly httpDispatcher: Dispatcher;
+
+  constructor(
+    configOrAddress: PlClientConfig | string,
+    ops: {
+      auth?: AuthOps;
+      statusListener?: PlConnectionStatusListener;
+    } = {}
+  ) {
+    this.conf =
+      typeof configOrAddress === 'string' ? plAddressToConfig(configOrAddress) : configOrAddress;
+
+    const grpcInterceptors: Interceptor[] = [];
+
+    const { auth, statusListener } = ops;
+
+    if (auth !== undefined) {
+      this.refreshTimestamp = inferAuthRefreshTime(
+        auth.authInformation,
+        this.conf.authMaxRefreshSeconds
+      );
+      grpcInterceptors.push(this.createAuthInterceptor());
+      this.authInformation = auth.authInformation;
+      this.onAuthUpdate = auth.onUpdate;
+      this.onAuthRefreshProblem = auth.onUpdateError;
+      this.onAuthError = auth.onAuthError;
+    }
+
+    grpcInterceptors.push(this.createErrorInterceptor());
+
+    const grpcOptions: GrpcOptions = {
+      host: this.conf.hostAndPort,
+      timeout: this.conf.defaultRequestTimeout,
+      channelCredentials: this.conf.ssl
+        ? ChannelCredentials.createSsl()
+        : ChannelCredentials.createInsecure(),
+      clientOptions: {
+        'grpc.use_local_subchannel_pool': 1,
+        interceptors: grpcInterceptors
+      }
+    };
+
+    if (this.conf.grpcProxy) process.env.grpc_proxy = this.conf.grpcProxy;
+    else delete process.env.grpc_proxy;
+
+    this.grpcTransport = new GrpcTransport(grpcOptions);
+    this.grpcPl = new PlatformClient(this.grpcTransport);
+
+    // setting up http(s)
+    if (this.conf.httpProxy !== undefined)
+      this.httpDispatcher = new ProxyAgent(this.conf.httpProxy);
+    else this.httpDispatcher = new Agent();
+
+    if (statusListener !== undefined) {
+      this.statusListener = statusListener;
+      statusListener(this._status);
+    }
+  }
+
+  /** Returns true if client is authenticated. Even with anonymous auth information
+   * connection is considered authenticated. Unauthenticated clients are used for
+   * login and similar tasks, see {@link UnauthenticatedPlClient}. */
+  public get authenticated(): boolean {
+    return this.authInformation !== undefined;
+  }
+
+  /** null means anonymous connection */
+  public get authUser(): string | null {
+    if (!this.authenticated) throw new Error('Client is not authenticated');
+    if (this.authInformation?.jwtToken)
+      return parsePlJwt(this.authInformation?.jwtToken).user.login;
+    else return null;
+  }
+
+  private updateStatus(newStatus: PlConnectionStatus) {
+    process.nextTick(() => {
+      if (this._status !== newStatus) {
+        this._status = newStatus;
+        if (this.statusListener !== undefined) this.statusListener(this._status);
+        if (this.onAuthError !== undefined) this.onAuthError();
+      }
+    });
+  }
+
+  public get status(): PlConnectionStatus {
+    return this._status;
+  }
+
+  private authRefreshInProgress: boolean = false;
+
+  private refreshAuthInformationIfNeeded(): void {
+    if (
+      this.refreshTimestamp === undefined ||
+      Date.now() < this.refreshTimestamp ||
+      this.authRefreshInProgress ||
+      this._status === 'Unauthenticated'
+    )
+      return;
+
+    // Running refresh in background
+    this.authRefreshInProgress = true;
+    (async () => {
+      try {
+        const response = await this.grpcPl.getJWTToken({
+          expiration: {
+            seconds: BigInt(this.conf.authTTLSeconds),
+            nanos: 0
+          }
+        }).response;
+        this.authInformation = { jwtToken: response.token };
+        this.refreshTimestamp = inferAuthRefreshTime(
+          this.authInformation,
+          this.conf.authMaxRefreshSeconds
+        );
+        if (this.onAuthUpdate) this.onAuthUpdate(this.authInformation);
+      } catch (e: unknown) {
+        if (this.onAuthRefreshProblem) this.onAuthRefreshProblem(e);
+      } finally {
+        this.authRefreshInProgress = false;
+      }
+    })();
+  }
+
+  /** Detects certain errors and update client status accordingly */
+  private createErrorInterceptor(): Interceptor {
+    return (options, nextCall) => {
+      return new InterceptingCall(nextCall(options), {
+        start: (metadata, listener, next) => {
+          next(metadata, {
+            onReceiveStatus: (status, next) => {
+              if (status.code == GrpcStatus.UNAUTHENTICATED)
+                // (!!!) don't change to "==="
+                this.updateStatus('Unauthenticated');
+              if (status.code == GrpcStatus.UNAVAILABLE)
+                // (!!!) don't change to "==="
+                this.updateStatus('Disconnected');
+              next(status);
+            }
+          });
+        }
+      });
+    };
+  }
+
+  /** Injects authentication information if needed */
+  private createAuthInterceptor(): Interceptor {
+    return (options, nextCall) => {
+      return new InterceptingCall(nextCall(options), {
+        start: (metadata, listener, next) => {
+          if (this.authInformation?.jwtToken !== undefined) {
+            metadata.set('authorization', 'Bearer ' + this.authInformation.jwtToken);
+            this.refreshAuthInformationIfNeeded();
+            next(metadata, listener);
+          } else {
+            next(metadata, listener);
+          }
+        }
+      });
+    };
+  }
+
+  createTx(ops: PlCallOps = {}): LLPlTransaction {
+    return new LLPlTransaction((abortSignal) => {
+      let totalAbortSignal = abortSignal;
+      if (ops.abortSignal)
+        // this will be fixed in typescript 5.5.0
+        // see this https://github.com/microsoft/TypeScript/issues/58026
+        // and this https://github.com/microsoft/TypeScript/pull/58211
+        totalAbortSignal = (AbortSignal as any).any([totalAbortSignal, ops.abortSignal]);
+      return this.grpcPl.tx({
+        abort: totalAbortSignal,
+        timeout: ops.timeout ?? this.conf.defaultTransactionTimeout
+      });
+    });
+  }
+
+  /** Closes underlying transport */
+  public close() {
+    this.grpcTransport.close();
+  }
+}

package/src/core/ll_transaction.test.ts

@@ -0,0 +1,152 @@
+import { getTestLLClient } from '../test/test_config';
+import { TxAPI_Open_Request_WritableTx } from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api';
+import { createLocalResourceId } from './types';
+
+import { isTimeoutOrCancelError } from './errors';
+import { Aborted } from '@milaboratories/ts-helpers';
+
+test('transaction timeout test', async () => {
+  const client = await getTestLLClient();
+  const tx = client.createTx({ timeout: 500 });
+
+  await expect(async () => {
+    const response = await tx.send(
+      {
+        oneofKind: 'txOpen',
+        txOpen: { name: 'test', writable: TxAPI_Open_Request_WritableTx.WRITABLE }
+      },
+      false
+    );
+    expect(response.txOpen.tx?.isValid).toBeTruthy();
+    await tx.await();
+  }).rejects.toThrow(Aborted);
+});
+
+test('check timeout error type (passive)', async () => {
+  const client = await getTestLLClient();
+  const tx = client.createTx({ timeout: 500 });
+
+  try {
+    const response = await tx.send(
+      {
+        oneofKind: 'txOpen',
+        txOpen: { name: 'test', writable: TxAPI_Open_Request_WritableTx.WRITABLE }
+      },
+      false
+    );
+    expect(response.txOpen.tx?.isValid).toBeTruthy();
+    await tx.await();
+  } catch (err: unknown) {
+    expect(isTimeoutOrCancelError(err)).toBe(true);
+  }
+});
+
+test('check timeout error type (active)', async () => {
+  const client = await getTestLLClient();
+  const tx = client.createTx({ timeout: 500 });
+
+  try {
+    const openResponse = await tx.send(
+      {
+        oneofKind: 'txOpen',
+        txOpen: { name: 'test', writable: TxAPI_Open_Request_WritableTx.WRITABLE }
+      },
+      false
+    );
+    expect(openResponse.txOpen.tx?.isValid).toBeTruthy();
+
+    const rData = Uint8Array.from([
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff,
+      (Math.random() * 256) & 0xff
+    ]);
+
+    const createResponse = await tx.send(
+      {
+        oneofKind: 'resourceCreateValue',
+        resourceCreateValue: {
+          id: createLocalResourceId(false, 1, 1),
+          type: { name: 'TestValue', version: '1' },
+          data: rData,
+          errorIfExists: false
+        }
+      },
+      false
+    );
+    const id = (await createResponse).resourceCreateValue.resourceId;
+
+    while (true) {
+      const vr = await tx.send(
+        {
+          oneofKind: 'resourceGet',
+          resourceGet: { resourceId: id, loadFields: false }
+        },
+        false
+      );
+
+      expect(Buffer.compare(vr.resourceGet.resource!.data, rData)).toBe(0);
+    }
+  } catch (err: unknown) {
+    expect(isTimeoutOrCancelError(err)).toBe(true);
+  }
+});
+
+test('check is abort error (active)', async () => {
+  const client = await getTestLLClient();
+  const tx = client.createTx({ abortSignal: AbortSignal.timeout(100) });
+
+  try {
+    const openResponse = await tx.send(
+      {
+        oneofKind: 'txOpen',
+        txOpen: { name: 'test', writable: TxAPI_Open_Request_WritableTx.WRITABLE }
+      },
+      false
+    );
+    expect(openResponse.txOpen.tx?.isValid).toBeTruthy();
+
+    const rData = Uint8Array.from([
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff,
+      Math.random() & 0xff
+    ]);
+
+    const createResponse = await tx.send(
+      {
+        oneofKind: 'resourceCreateValue',
+        resourceCreateValue: {
+          id: createLocalResourceId(false, 1, 1),
+          type: { name: 'TestValue', version: '1' },
+          data: rData,
+          errorIfExists: false
+        }
+      },
+      false
+    );
+    const id = (await createResponse).resourceCreateValue.resourceId;
+
+    while (true) {
+      const vr = await tx.send(
+        {
+          oneofKind: 'resourceGet',
+          resourceGet: { resourceId: id, loadFields: false }
+        },
+        false
+      );
+
+      expect(Buffer.compare(vr.resourceGet.resource!.data, rData)).toBe(0);
+    }
+  } catch (err: unknown) {
+    expect(isTimeoutOrCancelError(err)).toBe(true);
+  }
+});