@milaboratories/pl-client 2.4.10

package/src/core/type_conversion.ts

@@ -0,0 +1,121 @@
+import {
+  Field,
+  Field_ValueStatus,
+  Resource,
+  Resource_Kind
+} from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api_types';
+import { FieldType as GrpcFieldType } from '../proto/github.com/milaboratory/pl/plapi/plapiproto/base_types';
+import {
+  FieldData,
+  FieldStatus,
+  NullResourceId,
+  OptionalResourceId,
+  FieldType,
+  ResourceData,
+  ResourceId,
+  ResourceKind
+} from './types';
+import { assertNever, notEmpty } from '@milaboratories/ts-helpers';
+import { throwPlNotFoundError } from './errors';
+
+const ResourceErrorField = 'resourceError';
+
+function resourceIsDeleted(proto: Resource): boolean {
+  return proto.deletedTime !== undefined && proto.deletedTime.seconds !== 0n;
+}
+
+/** Throws "native" pl not found error, if resource is marked as deleted. */
+export function protoToResource(proto: Resource): ResourceData {
+  if (resourceIsDeleted(proto)) throwPlNotFoundError('resource deleted');
+  return {
+    id: proto.id as ResourceId,
+    originalResourceId: proto.originalResourceId as OptionalResourceId,
+    type: notEmpty(proto.type),
+    data: proto.data,
+    inputsLocked: proto.inputsLocked,
+    outputsLocked: proto.outputsLocked,
+    resourceReady: proto.resourceReady,
+    kind: protoToResourceKind(proto.kind),
+    error: protoToError(proto),
+    final: proto.isFinal,
+    fields: proto.fields?.filter((f) => f.id!.fieldName !== ResourceErrorField).map(protoToField)
+  };
+}
+
+function protoToResourceKind(proto: Resource_Kind): ResourceKind {
+  switch (proto) {
+    case Resource_Kind.STRUCTURAL:
+      return 'Structural';
+    case Resource_Kind.VALUE:
+      return 'Value';
+  }
+
+  throw new Error('invalid ResourceKind: ' + proto);
+}
+
+function protoToError(proto: Resource): OptionalResourceId {
+  const f = proto.fields.find((f) => f?.id?.fieldName === ResourceErrorField);
+  return (f?.error ?? NullResourceId) as OptionalResourceId;
+}
+
+export function protoToField(proto: Field): FieldData {
+  return {
+    name: notEmpty(proto.id?.fieldName),
+    type: protoToFieldType(proto.type),
+    status: protoToFieldStatus(proto.valueStatus),
+    value: proto.value as OptionalResourceId,
+    error: proto.error as OptionalResourceId,
+    valueIsFinal: proto.valueIsFinal
+  };
+}
+
+function protoToFieldType(proto: GrpcFieldType): FieldType {
+  switch (proto) {
+    case GrpcFieldType.INPUT:
+      return 'Input';
+    case GrpcFieldType.OUTPUT:
+      return 'Output';
+    case GrpcFieldType.SERVICE:
+      return 'Service';
+    case GrpcFieldType.ONE_TIME_WRITABLE:
+      return 'OTW';
+    case GrpcFieldType.DYNAMIC:
+      return 'Dynamic';
+    case GrpcFieldType.MULTIPLE_TIMES_WRITABLE:
+      return 'MTW';
+    default:
+      throw new Error('invalid FieldType: ' + proto);
+  }
+}
+
+function protoToFieldStatus(proto: Field_ValueStatus): FieldStatus {
+  switch (proto) {
+    case Field_ValueStatus.EMPTY:
+      return 'Empty';
+    case Field_ValueStatus.ASSIGNED:
+      return 'Assigned';
+    case Field_ValueStatus.RESOLVED:
+      return 'Resolved';
+    default:
+      throw new Error('invalid FieldStatus: ' + proto);
+  }
+}
+
+export function fieldTypeToProto(type: FieldType): GrpcFieldType {
+  switch (type) {
+    case 'Input':
+      return GrpcFieldType.INPUT;
+    case 'Output':
+      return GrpcFieldType.OUTPUT;
+    case 'Dynamic':
+      return GrpcFieldType.DYNAMIC;
+    case 'Service':
+      return GrpcFieldType.SERVICE;
+    case 'MTW':
+      return GrpcFieldType.MULTIPLE_TIMES_WRITABLE;
+    case 'OTW':
+      return GrpcFieldType.ONE_TIME_WRITABLE;
+    default:
+      return assertNever(type);
+  }
+}

package/src/core/types.test.ts

@@ -0,0 +1,22 @@
+import {
+  createGlobalResourceId,
+  createLocalResourceId,
+  NullResourceId,
+  resourceIdFromString,
+  resourceIdToString
+} from './types';
+
+test.each(
+  [
+    NullResourceId,
+    createGlobalResourceId(true, 0x3457748574857n),
+    createGlobalResourceId(false, 0x3457748574857n),
+    createLocalResourceId(true, 1234, 34423),
+    createLocalResourceId(false, 1234, 34423)
+  ].map((rid) => ({
+    name: resourceIdToString(rid),
+    rid
+  }))
+)(`resource id to and from string: $name`, ({ rid }) => {
+  expect(resourceIdFromString(resourceIdToString(rid))).toEqual(rid);
+});

package/src/core/types.ts

@@ -0,0 +1,223 @@
+import { notEmpty } from '@milaboratories/ts-helpers';
+import { version } from 'ts-jest/dist/transformers/hoist-jest';
+
+// more details here: https://egghead.io/blog/using-branded-types-in-typescript
+declare const __resource_id_type__: unique symbol;
+type BrandResourceId<B> = bigint & { [__resource_id_type__]: B };
+
+/** Global resource id */
+export type ResourceId = BrandResourceId<'global'>;
+
+/** Null resource id */
+export type NullResourceId = BrandResourceId<'null'>;
+
+/** Local resource id */
+export type LocalResourceId = BrandResourceId<'local'>;
+
+/** Any non-null resource id */
+export type AnyResourceId = ResourceId | LocalResourceId;
+
+/** Any resource id */
+export type OptionalResourceId = NullResourceId | ResourceId;
+
+/** All possible resource flavours */
+export type OptionalAnyResourceId = NullResourceId | ResourceId | LocalResourceId;
+
+export const NullResourceId = 0n as NullResourceId;
+
+export function isNullResourceId(resourceId: bigint): resourceId is NullResourceId {
+  return resourceId === NullResourceId;
+}
+
+export function isNotNullResourceId(resourceId: OptionalResourceId): resourceId is ResourceId {
+  return resourceId !== NullResourceId;
+}
+
+export function ensureResourceIdNotNull(resourceId: OptionalResourceId): ResourceId {
+  if (!isNotNullResourceId(resourceId)) throw new Error('null resource id');
+  return resourceId;
+}
+
+export function isAnyResourceId(resourceId: bigint): resourceId is AnyResourceId {
+  return resourceId !== 0n;
+}
+
+// see local / global resource logic below...
+
+export type ResourceKind = 'Structural' | 'Value';
+
+export type FieldType = 'Input' | 'Output' | 'Service' | 'OTW' | 'Dynamic' | 'MTW';
+
+export type FutureFieldType = 'Output' | 'Input' | 'Service';
+
+export type FieldStatus = 'Empty' | 'Assigned' | 'Resolved';
+
+export interface ResourceType {
+  readonly name: string;
+  readonly version: string;
+}
+
+export function resourceType(name: string, version: string): ResourceType {
+  return { name, version };
+}
+
+export function resourceTypeToString(rt: ResourceType): string {
+  return `${rt.name}:${rt.version}`;
+}
+
+export function resourceTypesEqual(type1: ResourceType, type2: ResourceType): boolean {
+  return type1.name === type2.name && type1.version === type2.version;
+}
+
+/** Readonly fields here marks properties of resource that can't change according to pl's state machine. */
+export interface BasicResourceData {
+  readonly id: ResourceId;
+  readonly originalResourceId: OptionalResourceId;
+
+  readonly kind: ResourceKind;
+  readonly type: ResourceType;
+
+  readonly data?: Uint8Array;
+
+  readonly error: OptionalResourceId;
+
+  readonly inputsLocked: boolean;
+  readonly outputsLocked: boolean;
+  readonly resourceReady: boolean;
+
+  /** This value is derived from resource state by the server and can be used as
+   * a robust criteria to determine resource is in final state. */
+  readonly final: boolean;
+}
+
+export const jsonToData = (data: unknown) => Buffer.from(JSON.stringify(data));
+
+export const resDataToJson = (res: ResourceData) => JSON.parse(notEmpty(res.data).toString());
+
+export interface ResourceData extends BasicResourceData {
+  fields: FieldData[];
+}
+
+export function getField(r: ResourceData, name: string): FieldData {
+  return notEmpty(r.fields.find((f) => f.name === name));
+}
+
+export interface FieldData {
+  name: string;
+  type: FieldType;
+  status: FieldStatus;
+  value: OptionalResourceId;
+  error: OptionalResourceId;
+
+  /** True if value the fields points to is in final state. */
+  valueIsFinal: boolean;
+}
+
+//
+// Local / Global ResourceId arithmetics
+//
+
+// Note: txId and other numerical values are made numbers but not bigint intentionally,
+//       after implementing security model based on signed resource ids this will make
+//       much more sense
+
+const ResourceIdRootMask = 1n << 63n;
+const ResourceIdLocalMask = 1n << 62n;
+const NoFlagsIdMask = 0x3fffffffffffffffn;
+const LocalResourceIdTxIdOffset = 24n;
+export const MaxLocalId = 0xffffff;
+export const MaxTxId = 0xffffffff;
+/** Mask valid after applying shift */
+const TxIdMask = BigInt(MaxTxId);
+const LocalIdMask = BigInt(MaxLocalId);
+
+// /** Basically removes embedded tx id */
+// const LocalIdCleanMask = 0xFF00000000FFFFFFn;
+
+export function isRootResourceId(id: bigint) {
+  return (id & ResourceIdRootMask) !== 0n;
+}
+
+export function isLocalResourceId(id: bigint): id is LocalResourceId {
+  return (id & ResourceIdLocalMask) !== 0n;
+}
+
+export function createLocalResourceId(
+  isRoot: boolean,
+  localCounterValue: number,
+  localTxId: number
+): LocalResourceId {
+  if (
+    localCounterValue > MaxLocalId ||
+    localTxId > MaxTxId ||
+    localCounterValue < 0 ||
+    localTxId <= 0
+  )
+    throw Error('wrong local id or tx id');
+  return ((isRoot ? ResourceIdRootMask : 0n) |
+    ResourceIdLocalMask |
+    BigInt(localCounterValue) |
+    (BigInt(localTxId) << LocalResourceIdTxIdOffset)) as LocalResourceId;
+}
+
+export function createGlobalResourceId(isRoot: boolean, unmaskedId: bigint): ResourceId {
+  return ((isRoot ? ResourceIdRootMask : 0n) | unmaskedId) as ResourceId;
+}
+
+export function extractTxId(localResourceId: LocalResourceId): number {
+  return Number((localResourceId >> LocalResourceIdTxIdOffset) & TxIdMask);
+}
+
+export function checkLocalityOfResourceId(resourceId: AnyResourceId, expectedTxId: number): void {
+  if (!isLocalResourceId(resourceId)) return;
+  if (extractTxId(resourceId) !== expectedTxId)
+    throw Error(
+      'local id from another transaction, globalize id before leaking it from the transaction'
+    );
+}
+
+export function resourceIdToString(resourceId: OptionalAnyResourceId): string {
+  if (isNullResourceId(resourceId)) return 'XX:0x0';
+  if (isLocalResourceId(resourceId))
+    return (
+      (isRootResourceId(resourceId) ? 'R' : 'N') +
+      'L:0x' +
+      (LocalIdMask & resourceId).toString(16) +
+      '[0x' +
+      extractTxId(resourceId).toString(16) +
+      ']'
+    );
+  else
+    return (
+      (isRootResourceId(resourceId) ? 'R' : 'N') +
+      'G:0x' +
+      (NoFlagsIdMask & resourceId).toString(16)
+    );
+}
+
+const resourceIdRegexp =
+  /^(?:(?<xx>XX)|(?<rn>[XRN])(?<lg>[XLG])):0x(?<rid>[0-9a-fA-F]+)(?:\[0x(?<txid>[0-9a-fA-F]+)])?$/;
+
+export function resourceIdFromString(str: string): OptionalAnyResourceId | undefined {
+  const match = str.match(resourceIdRegexp);
+  if (match === null) return undefined;
+  const { xx, rn, lg, rid, txid } = match.groups!;
+  if (xx) return NullResourceId;
+  if (lg === 'L')
+    return createLocalResourceId(rn === 'R', Number.parseInt(rid, 16), Number.parseInt(txid, 16));
+  else return createGlobalResourceId(rn === 'R', BigInt('0x' + rid));
+}
+
+/** Converts bigint to global resource id */
+export function bigintToResourceId(resourceId: bigint): ResourceId {
+  if (isLocalResourceId(resourceId))
+    throw new Error(`Local resource id: ${resourceIdToString(resourceId)}`);
+  if (isNullResourceId(resourceId)) throw new Error(`Null resource id.`);
+  return resourceId as ResourceId;
+}
+
+export function stringifyWithResourceId(object: unknown | undefined): string {
+  return JSON.stringify(object, (key, value) =>
+    typeof value === 'bigint' ? resourceIdToString(value as OptionalAnyResourceId) : value
+  );
+}

package/src/core/unauth_client.test.ts

@@ -0,0 +1,21 @@
+import { UnauthenticatedPlClient } from './unauth_client';
+import { getTestConfig } from '../test/test_config';
+import { UnauthenticatedError } from './errors';
+
+test('ping test', async () => {
+  const client = new UnauthenticatedPlClient(getTestConfig().address);
+  const response = await client.ping();
+  expect(response).toHaveProperty('coreVersion');
+});
+
+test('wrong login', async () => {
+  const testConfig = getTestConfig();
+  if (testConfig.test_user === undefined || testConfig.test_password === undefined) {
+    console.log('skipped');
+    return;
+  }
+  const client = new UnauthenticatedPlClient(testConfig.address);
+  await expect(client.login(testConfig.test_user, testConfig.test_password + 'A')).rejects.toThrow(
+    UnauthenticatedError
+  );
+});

package/src/core/unauth_client.ts

@@ -0,0 +1,48 @@
+import { AuthInformation, PlClientConfig } from './config';
+import {
+  AuthAPI_ListMethods_Response,
+  MaintenanceAPI_Ping_Response
+} from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api';
+import { LLPlClient } from './ll_client';
+import { notEmpty } from '@milaboratories/ts-helpers';
+import { UnauthenticatedError } from './errors';
+
+/** Primarily used for initial authentication (login) */
+export class UnauthenticatedPlClient {
+  public readonly ll: LLPlClient;
+
+  constructor(configOrAddress: PlClientConfig | string) {
+    this.ll = new LLPlClient(configOrAddress);
+  }
+
+  public async ping(): Promise<MaintenanceAPI_Ping_Response> {
+    return (await this.ll.grpcPl.ping({})).response;
+  }
+
+  public async authMethods(): Promise<AuthAPI_ListMethods_Response> {
+    return (await this.ll.grpcPl.authMethods({})).response;
+  }
+
+  public async requireAuth(): Promise<boolean> {
+    return (await this.authMethods()).methods.length > 0;
+  }
+
+  public async login(user: string, password: string): Promise<AuthInformation> {
+    try {
+      const response = await this.ll.grpcPl.getJWTToken(
+        { expiration: { seconds: BigInt(this.ll.conf.authTTLSeconds), nanos: 0 } },
+        {
+          meta: {
+            authorization: 'Basic ' + Buffer.from(user + ':' + password).toString('base64')
+          }
+        }
+      ).response;
+      const jwtToken = notEmpty(response.token);
+      if (jwtToken === '') throw new Error('empty token');
+      return { jwtToken };
+    } catch (e: any) {
+      if (e.code === 'UNAUTHENTICATED') throw new UnauthenticatedError(e.message);
+      throw new Error(e);
+    }
+  }
+}

package/src/helpers/pl.ts

@@ -0,0 +1,141 @@
+/**
+ * @packageDocumentation
+ *
+ * This file is exported under Pl "namespace" to the client users.
+ *
+ * It defines well known pl types, and methods to manipulate them.
+ *
+ */
+
+import { FutureFieldType, ResourceType } from '../core/types';
+import { AnyRef, field, FieldRef, PlTransaction, ResourceRef } from '../core/transaction';
+
+function rt(name: string, version: string): ResourceType {
+  return { name, version };
+}
+
+export const ClientRoot = rt('ClientRoot', '1');
+
+export const StructTestResource = rt('StructTest', '1');
+export const ValueTestResource = rt('ValueTest', '1');
+
+export const JsonString = rt('json/string', '1');
+export const JsonBool = rt('json/bool', '1');
+export const JsonObject = rt('json/object', '1');
+export const JsonArray = rt('json/array', '1');
+export const JsonNumber = rt('json/number', '1');
+export const JsonNull = rt('json/null', '1');
+
+export const EphStdMap: ResourceType = rt('EphStdMap', '1');
+export const StdMap: ResourceType = rt('StdMap', '1');
+
+//
+// Standard value resources
+//
+
+export function createPlNull(tx: PlTransaction): ResourceRef {
+  return tx.createValue(JsonNull, Buffer.from(JSON.stringify(null)));
+}
+
+export function createPlBool(tx: PlTransaction, val: boolean): ResourceRef {
+  return tx.createValue(JsonBool, Buffer.from(JSON.stringify(val)));
+}
+
+export function createPlNumber(tx: PlTransaction, val: number): ResourceRef {
+  return tx.createValue(JsonNumber, Buffer.from(JSON.stringify(val)));
+}
+
+export function createPlString(tx: PlTransaction, val: string): ResourceRef {
+  return tx.createValue(JsonString, Buffer.from(JSON.stringify(val)));
+}
+
+export function createPlArray(tx: PlTransaction, val: any[]): ResourceRef {
+  return tx.createValue(JsonArray, Buffer.from(JSON.stringify(val)));
+}
+
+export function createPlObject(tx: PlTransaction, val: object): ResourceRef {
+  return tx.createValue(JsonObject, Buffer.from(JSON.stringify(val)));
+}
+
+//
+// Pl Map
+//
+
+export type PlRecordEntry<Key extends string = string, Ref extends AnyRef = AnyRef> = [Key, Ref];
+
+export type PlRecord<Key extends string = string, Ref extends AnyRef = AnyRef> = Record<Key, Ref>;
+
+export function plEntry<Key extends string = string, Ref extends AnyRef = AnyRef>(
+  key: Key,
+  ref: Ref
+): PlRecordEntry<Key, Ref> {
+  return [key, ref];
+}
+
+export function plEntries<Key extends string = string, Ref extends AnyRef = AnyRef>(
+  record: PlRecord<Key, Ref>,
+  fields?: Key[]
+): PlRecordEntry<Key, Ref>[] {
+  return fields === undefined
+    ? (Object.entries(record) as PlRecordEntry<Key, Ref>[])
+    : fields.map((key) => plEntry(key, record[key]));
+}
+
+/** Helper method to build standard pl map from a set of entries */
+export function createPlMap(
+  tx: PlTransaction,
+  entries: PlRecordEntry[] | PlRecord,
+  ephemeral: boolean,
+  type?: ResourceType
+): ResourceRef {
+  const actualType = type ?? (ephemeral ? EphStdMap : StdMap);
+  const rId = ephemeral ? tx.createEphemeral(actualType) : tx.createStruct(actualType);
+
+  for (const [name, value] of Array.isArray(entries) ? entries : plEntries(entries))
+    tx.createField(field(rId, name), 'Input', value);
+
+  tx.lock(rId);
+
+  return rId;
+}
+
+export function futureRecord<Key extends string>(
+  tx: PlTransaction,
+  rId: AnyRef,
+  keys: Key[],
+  fieldType: FutureFieldType,
+  prefix: string = ''
+): PlRecord<Key, FieldRef> {
+  return Object.fromEntries(
+    keys.map((k) => plEntry(k, tx.getFutureFieldValue(rId, `${prefix}${k}`, fieldType)))
+  ) as PlRecord<Key, FieldRef>;
+}
+
+//
+// Holder
+//
+
+/** Name of the field in block holder, that references the actual block-pack. */
+export const Holder = StdMap;
+export const EphHolder = EphStdMap;
+export const HolderRefField = 'ref';
+
+export function wrapInHolder(tx: PlTransaction, ref: AnyRef): ResourceRef {
+  const holder = tx.createStruct(Holder);
+  const mainHolderField = field(holder, HolderRefField);
+  tx.createField(mainHolderField, 'Input', ref);
+  tx.lock(holder);
+  return holder;
+}
+
+export function wrapInEphHolder(tx: PlTransaction, ref: AnyRef): ResourceRef {
+  const holder = tx.createEphemeral(EphHolder);
+  const mainHolderField = field(holder, HolderRefField);
+  tx.createField(mainHolderField, 'Input', ref);
+  tx.lock(holder);
+  return holder;
+}
+
+export function unwrapHolder(tx: PlTransaction, ref: AnyRef): FieldRef {
+  return tx.getFutureFieldValue(ref, HolderRefField, 'Input');
+}