@milaboratories/pl-client 2.4.10

package/src/core/default_client.ts

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { AuthInformation, plAddressToConfig, PlClientConfig } from './config';
+import canonicalize from 'canonicalize';
+import YAML from 'yaml';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { notEmpty } from '@milaboratories/ts-helpers';
+import { UnauthenticatedPlClient } from './unauth_client';
+import { PlClient } from './client';
+import { createHash } from 'crypto';
+import { inferAuthRefreshTime } from './auth';
+
+const CONFIG_FILE_LOCAL_JSON = 'pl.json';
+const CONFIG_FILE_USER_JSON = path.join(os.homedir(), '.pl.json');
+const CONFIG_FILE_LOCAL_YAML = 'pl.yaml';
+const CONFIG_FILE_USER_YAML = path.join(os.homedir(), '.pl.yaml');
+const CONF_FILE_SEQUENCE = [
+  CONFIG_FILE_LOCAL_JSON,
+  CONFIG_FILE_LOCAL_YAML,
+  CONFIG_FILE_USER_JSON,
+  CONFIG_FILE_USER_YAML
+];
+
+const AUTH_DATA_FILE = '.pl_auth.json';
+
+type FileConfigOverrideFields =
+  | 'grpcProxy'
+  | 'httpProxy'
+  | 'user'
+  | 'password'
+  | 'alternativeRoot'
+  | 'defaultTransactionTimeout'
+  | 'defaultRequestTimeout'
+  | 'authTTLSeconds'
+  | 'authMaxRefreshSeconds';
+const FILE_CONFIG_OVERRIDE_FIELDS: FileConfigOverrideFields[] = [
+  'grpcProxy',
+  'httpProxy',
+  'user',
+  'password',
+  'alternativeRoot',
+  'defaultTransactionTimeout',
+  'defaultRequestTimeout',
+  'authTTLSeconds',
+  'authMaxRefreshSeconds'
+];
+
+type PlConfigFile = {
+  address: string;
+} & Partial<Pick<PlClientConfig, FileConfigOverrideFields>>;
+
+interface AuthCache {
+  /** To check if config changed */
+  confHash: string;
+  expiration: number;
+  authInformation: AuthInformation;
+}
+
+export function tryGetFileConfig(): [PlConfigFile, string] | undefined {
+  for (const confPath of CONF_FILE_SEQUENCE)
+    if (fs.existsSync(confPath)) {
+      const fileContent = fs.readFileSync(confPath, { encoding: 'utf-8' });
+      if (confPath.endsWith('json')) return [JSON.parse(fileContent) as PlConfigFile, confPath];
+      else return [YAML.parse(fileContent) as PlConfigFile, confPath];
+    }
+  return undefined;
+}
+
+function saveAuthInfoCallback(
+  confHash: string,
+  authMaxRefreshSeconds: number
+): (newAuthInfo: AuthInformation) => void {
+  return (newAuthInfo) => {
+    fs.writeFileSync(
+      AUTH_DATA_FILE,
+      Buffer.from(
+        JSON.stringify({
+          confHash,
+          authInformation: newAuthInfo,
+          expiration: inferAuthRefreshTime(newAuthInfo, authMaxRefreshSeconds)
+        } as AuthCache)
+      ),
+      'utf8'
+    );
+  };
+}
+
+const cleanAuthInfoCallback = () => {
+  fs.rmSync(AUTH_DATA_FILE);
+};
+
+/** Uses default algorithm to construct a pl client from the environment */
+export async function defaultPlClient(): Promise<PlClient> {
+  let config: PlClientConfig | undefined = undefined;
+  if (process.env.PL_ADDRESS !== undefined) {
+    config = plAddressToConfig(process.env.PL_ADDRESS);
+  } else {
+    const fromFile = tryGetFileConfig();
+    if (fromFile !== undefined) {
+      const [fileConfig, configPath] = fromFile;
+      const address = notEmpty(fileConfig.address, `no pl address in file: ${configPath}`);
+      config = plAddressToConfig(address);
+      // applying overrides
+      for (const field of FILE_CONFIG_OVERRIDE_FIELDS)
+        if (fileConfig[field] !== undefined) (config as any)[field] = fileConfig[field];
+    }
+  }
+
+  if (config === undefined)
+    throw new Error("Can't find configuration to create default platform client.");
+
+  if (process.env.PL_USER !== undefined) config.user = process.env.PL_USER;
+
+  if (process.env.PL_PASSWORD !== undefined) config.user = process.env.PL_PASSWORD;
+
+  const confHash = createHash('sha256')
+    .update(Buffer.from(canonicalize(config)!))
+    .digest('base64');
+
+  let authInformation: AuthInformation | undefined = undefined;
+
+  // try recover auth information from cache
+  if (fs.existsSync(AUTH_DATA_FILE)) {
+    const cache: AuthCache = JSON.parse(fs.readFileSync(AUTH_DATA_FILE, { encoding: 'utf-8' }));
+    if (cache.confHash === confHash && cache.expiration > Date.now())
+      authInformation = cache.authInformation;
+  }
+
+  if (authInformation === undefined) {
+    const client = new UnauthenticatedPlClient(config);
+
+    if (await client.requireAuth()) {
+      if (config.user === undefined || config.password === undefined)
+        throw new Error(`No auth information for found to authenticate with PL server.`);
+      authInformation = await client.login(config.user, config.password);
+    } else {
+      // No authorization is required
+      authInformation = {};
+    }
+
+    // saving cache
+    fs.writeFileSync(
+      AUTH_DATA_FILE,
+      Buffer.from(
+        JSON.stringify({
+          confHash,
+          authInformation,
+          expiration: inferAuthRefreshTime(authInformation, config.authMaxRefreshSeconds)
+        } as AuthCache)
+      ),
+      'utf8'
+    );
+  }
+
+  return await PlClient.init(config, {
+    authInformation,
+    onUpdate: (newAuthInfo) => saveAuthInfoCallback(confHash, config!.authMaxRefreshSeconds),
+    onUpdateError: cleanAuthInfoCallback,
+    onAuthError: cleanAuthInfoCallback
+  });
+}

package/src/core/driver.ts

@@ -0,0 +1,30 @@
+import { PlClient } from './client';
+import { GrpcTransport } from '@protobuf-ts/grpc-transport';
+import type { RpcOptions } from '@protobuf-ts/runtime-rpc';
+import { Dispatcher } from 'undici';
+import { ResourceType } from './types';
+
+/** Drivers must implement this interface */
+export interface PlDriver {
+  close(): void;
+}
+
+/** Definition to use driver via {@link PlClient} */
+export interface PlDriverDefinition<Drv extends PlDriver> {
+  /** Used as key to only once instantiate specific drivers */
+  readonly name: string;
+
+  /** Initialization routine, will be executed only once for each driver in a specific client */
+  init(pl: PlClient, grpcTransport: GrpcTransport, httpDispatcher: Dispatcher): Drv;
+}
+
+// addRTypeToMetadata adds a metadata with resource type
+// for every RPC call. It is necessary for the platform core
+// to proxy the call to the proper controller.
+export function addRTypeToMetadata(rType: ResourceType, options?: RpcOptions) {
+  options = options ?? {};
+  options.meta = options.meta ?? {};
+  options.meta['resourceType'] = `${rType.name}:${rType.version}`;
+
+  return options;
+}

package/src/core/error.test.ts

@@ -0,0 +1,14 @@
+import * as tp from 'node:timers/promises';
+import { isTimeoutOrCancelError } from './errors';
+
+test('timeout of sleep error type detection', async () => {
+  let noError = false;
+  try {
+    await tp.setTimeout(1000, undefined, { signal: AbortSignal.timeout(10) });
+    noError = true;
+  } catch (err: unknown) {
+    expect((err as any).code).toStrictEqual('ABORT_ERR');
+    expect(isTimeoutOrCancelError(err)).toEqual(true);
+  }
+  expect(noError).toBe(false);
+});

package/src/core/errors.ts

@@ -0,0 +1,84 @@
+import { Status } from '../proto/github.com/googleapis/googleapis/google/rpc/status';
+import { Aborted } from '@milaboratories/ts-helpers';
+
+export function isConnectionProblem(err: unknown, nested: boolean = false): boolean {
+  if (err instanceof DisconnectedError) return true;
+  if ((err as any).name == 'RpcError' && (err as any).code == 'UNAVAILABLE') return true;
+  if ((err as any).cause !== undefined && !nested)
+    // nested limits the depth of search
+    return isConnectionProblem((err as any).cause, true);
+  return false;
+}
+
+export function isUnauthenticated(err: unknown, nested: boolean = false): boolean {
+  if (err instanceof UnauthenticatedError) return true;
+  if ((err as any).name == 'RpcError' && (err as any).code == 'UNAUTHENTICATED') return true;
+  if ((err as any).cause !== undefined && !nested)
+    // nested limits the depth of search
+    return isUnauthenticated((err as any).cause, true);
+  return false;
+}
+
+export function isTimeoutOrCancelError(err: unknown, nested: boolean = false): boolean {
+  if (err instanceof Aborted || (err as any).name == 'AbortError') return true;
+  if ((err as any).code == 'ABORT_ERR') return true;
+  if (
+    (err as any).name == 'RpcError' &&
+    ((err as any).code == 'CANCELLED' || (err as any).code == 'DEADLINE_EXCEEDED')
+  )
+    return true;
+  if ((err as any).cause !== undefined && !nested)
+    // nested limits the depth of search
+    return isTimeoutOrCancelError((err as any).cause, true);
+  return false;
+}
+
+export const PlErrorCodeNotFound = 5;
+
+export class PlError extends Error {
+  constructor(public readonly status: Status) {
+    super(`code=${status.code} ${status.message}`);
+  }
+}
+
+export function throwPlNotFoundError(message: string): never {
+  throw new RecoverablePlError({ code: PlErrorCodeNotFound, message, details: [] });
+}
+
+export class RecoverablePlError extends PlError {
+  constructor(status: Status) {
+    super(status);
+  }
+}
+
+export class UnrecoverablePlError extends PlError {
+  constructor(status: Status) {
+    super(status);
+  }
+}
+
+export function isNotFoundError(err: unknown, nested: boolean = false): boolean {
+  if ((err as any).name == 'RpcError' && (err as any).code == 'NOT_FOUND') return true;
+  if ((err as any).cause !== undefined && !nested) return isNotFoundError((err as any).cause, true);
+  return err instanceof RecoverablePlError && err.status.code === PlErrorCodeNotFound;
+}
+
+export class UnauthenticatedError extends Error {
+  constructor(message: string) {
+    super('LoginFailed: ' + message);
+  }
+}
+
+export class DisconnectedError extends Error {
+  constructor(message: string) {
+    super('Disconnected: ' + message);
+  }
+}
+
+export function rethrowMeaningfulError(error: any, wrapIfUnknown: boolean = false): never {
+  if (isUnauthenticated(error)) throw new UnauthenticatedError(error.message);
+  if (isConnectionProblem(error)) throw new DisconnectedError(error.message);
+  if (isTimeoutOrCancelError(error)) throw new Aborted(error);
+  if (wrapIfUnknown) throw new Error(error.message, { cause: error });
+  else throw error;
+}

package/src/core/http.ts

@@ -0,0 +1,178 @@
+// import * as util from 'util';
+// import http from 'node:http';
+// import https from 'node:https';
+// import { Readable, finished } from 'stream';
+//
+// type RequestOptions = https.RequestOptions;
+//
+// export const finishedP = util.promisify(finished);
+//
+// export const readableToBuffer = (
+//   stream: http.IncomingMessage
+// ): Promise<Buffer> => {
+//   if (stream.destroyed) {
+//     return Promise.reject(stream.errored);
+//   }
+//
+//   return new Promise((resolve, reject) => {
+//     const chunks: Buffer[] = [];
+//     stream.on('data', chunk => chunks.push(chunk));
+//     stream.on('error', reject);
+//     stream.on('end', () => {
+//       resolve(Buffer.concat(chunks));
+//     });
+//   });
+// };
+//
+// class Body {
+//   private buff: Buffer | undefined;
+//
+//   public constructor(private message: http.IncomingMessage) {}
+//
+//   async redable() {
+//     return this.buffer().then(b => Readable.from(b));
+//   }
+//
+//   async buffer(): Promise<Buffer> {
+//     if (!this.buff) {
+//       this.buff = await readableToBuffer(this.message).catch(e => {
+//         throw e;
+//       });
+//     }
+//
+//     return this.buff;
+//   }
+//
+//   async string() {
+//     return this.buffer().then(b => b.toString());
+//   }
+//
+//   async json() {
+//     return this.string().then(s => JSON.parse(s));
+//   }
+// }
+//
+// export class HttpClient {
+//   constructor(private options: RequestOptions) {
+//   }
+//
+//   assingOptions(options: RequestOptions) {
+//     Object.assign(this.options, options);
+//   }
+//
+//   request(
+//     url: URL | string,
+//     conf: {
+//       data?: Buffer | string;
+//     } & RequestOptions
+//   ) {
+//     url = typeof url === 'string' ? new URL(url) : url;
+//
+//     const data = conf.data ?? Buffer.from('');
+//
+//     delete conf.data;
+//
+//     const options: RequestOptions = Object.assign(
+//       {
+//         hostname: url.hostname,
+//         path: url.pathname + url.search,
+//         port: url.port,
+//       } as RequestOptions,
+//       this.options,
+//       conf,
+//     );
+//
+//     if (!options.method) {
+//       options.method = 'GET';
+//     }
+//
+//     if (!options.headers) {
+//       options.headers = {};
+//     }
+//
+//     options.headers['Content-Length'] = Buffer.byteLength(data);
+//
+//     // console.log('options', JSON.stringify(options, null, 2));
+//
+//     const isTls = url.protocol === 'https:';
+//
+//     const lib = isTls ? https : http;
+//
+//     return new Promise<{
+//       statusCode: number;
+//       ok: boolean;
+//       headers: http.IncomingHttpHeaders;
+//       body: Body;
+//     }>((resolve, reject) => {
+//       const timeout = options.timeout ?? 30000;
+//
+//       const t = setTimeout(() => {
+//         req.end();
+//         reject(Error(`Timeout ${timeout} exceeded`));
+//       }, timeout);
+//
+//       resolve = wrapFunction(resolve, () => clearTimeout(t)); // @TODO PromiseTimeout in utils
+//       reject = wrapFunction(reject, () => clearTimeout(t));
+//
+//       const req = lib.request(options, message => {
+//         const statusCode = message.statusCode ?? 500;
+//         resolve({
+//           statusCode,
+//           headers: message.headers,
+//           ok: statusCode >= 200 && statusCode < 300,
+//           body: new Body(message),
+//         });
+//       });
+//
+//       req.on('connect', (message, socket) => {
+//         const statusCode = message.statusCode ?? 500;
+//         socket.end();
+//         socket.on('error', () => {});
+//         resolve({
+//           statusCode,
+//           ok: statusCode >= 200 && statusCode < 300,
+//           headers: message.headers,
+//           body: new Body(message),
+//         });
+//       });
+//
+//       req.on('error', e => {
+//         reject(e);
+//       });
+//
+//       if (data.length) {
+//         req.write(data);
+//       }
+//
+//       req.end();
+//     });
+//   }
+//
+//   async connectProxy(proxy: URL | string) {
+//     proxy = new URL(proxy);
+//
+//     const headers = {} as http.OutgoingHttpHeaders;
+//
+//     if (proxy.username && proxy.password) {
+//       headers['Proxy-Authorization'] = `Basic ${Buffer.from(proxy.username + ':' + proxy.password).toString('base64')}`;
+//     }
+//
+//     return this.request(proxy, {
+//       method: 'CONNECT',
+//       path: 'www.google.com:80', // @TODO temp (it seems that we need a target in order to get 200 from the proxy)
+//       headers,
+//       agent: undefined
+//     }).then(r => ({ok: r.ok, statusCode: r.statusCode})).catch(() => ({ok: false, statusCode: 500}));
+//   }
+// }
+//
+// export const wrapFunction = <T extends unknown[], U>(
+//   fn: (...args: T) => U,
+//   before: () => void
+// ) => {
+//   return (...args: T): U => {
+//     before();
+//     return fn(...args);
+//   };
+// };
+//

package/src/core/ll_client.test.ts

@@ -0,0 +1,111 @@
+import { LLPlClient } from './ll_client';
+import { getTestConfig, getTestLLClient, getTestClientConf } from '../test/test_config';
+import { TxAPI_Open_Request_WritableTx } from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api';
+import { request } from 'undici';
+import * as tp from 'node:timers/promises';
+
+import { UnauthenticatedError } from './errors';
+
+test('authenticated instance test', async () => {
+  const client = await getTestLLClient();
+  const tx = client.createTx();
+  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.complete();
+  await tx.await();
+});
+
+test('unauthenticated status change', async () => {
+  const cfg = getTestConfig();
+  if (cfg.test_password === undefined) {
+    console.log("skipping test because target server doesn't support authentication");
+    return;
+  }
+
+  const client = new LLPlClient(cfg.address);
+  expect(client.status).toBe('OK');
+
+  const tx = client.createTx();
+
+  await expect(async () => {
+    await tx.send(
+      {
+        oneofKind: 'txOpen',
+        txOpen: { name: 'test', writable: TxAPI_Open_Request_WritableTx.WRITABLE }
+      },
+      false
+    );
+  }).rejects.toThrow(UnauthenticatedError);
+
+  await expect(async () => {
+    await tx.await();
+  }).rejects.toThrow(UnauthenticatedError);
+
+  await tp.setImmediate();
+
+  expect(client.status).toEqual('Unauthenticated');
+});
+
+test('automatic token update', async () => {
+  const { conf, auth } = await getTestClientConf();
+  conf.authMaxRefreshSeconds = 1;
+  let numberOfAuthUpdates = 0;
+  const client = new LLPlClient(conf, {
+    auth: {
+      authInformation: auth.authInformation,
+      onUpdate: (auth) => {
+        console.log(auth);
+        ++numberOfAuthUpdates;
+      }
+    }
+  });
+
+  for (let i = 0; i < 6; i++) {
+    const tx = client.createTx();
+    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.complete();
+    await tx.await();
+
+    if (numberOfAuthUpdates > 1) {
+      return;
+    }
+
+    await tp.setTimeout(1000);
+  }
+}, 5000);
+
+test('test simple https call', async () => {
+  const client = await getTestLLClient();
+  const response = await request('https://cdn.milaboratory.com/ping', {
+    dispatcher: client.httpDispatcher
+  });
+  const text = await response.body.text();
+  expect(text).toEqual('pong');
+});
+
+test('test https call via proxy', async () => {
+  const testConfig = getTestConfig();
+  if (testConfig.test_proxy === undefined) {
+    console.log('skipped');
+    return;
+  }
+  const client = await getTestLLClient({ httpProxy: testConfig.test_proxy });
+  const response = await request('https://cdn.milaboratory.com/ping', {
+    dispatcher: client.httpDispatcher
+  });
+  const text = await response.body.text();
+  expect(text).toEqual('pong');
+});