@milaboratories/pl-client 2.4.20 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-client",
-  "version": "2.4.20",
+  "version": "2.5.0",
   "description": "New TS/JS client for Platform API",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -23,6 +23,7 @@
     "@protobuf-ts/runtime-rpc": "^2.9.4",
     "canonicalize": "^2.0.0",
     "denque": "^2.1.0",
+    "lru-cache": "^11.0.1",
     "https-proxy-agent": "^7.0.5",
     "cacheable-lookup": "^6.1.0",
     "long": "^5.2.3",
@@ -41,7 +42,7 @@
     "jest": "^29.7.0",
     "@jest/globals": "^29.7.0",
     "ts-jest": "^29.2.5",
-    "@milaboratories/platforma-build-configs": "1.0.1"
+    "@milaboratories/platforma-build-configs": "1.0.2"
   },
   "scripts": {
     "type-check": "tsc --noEmit --composite false",

package/src/core/cache.ts

@@ -0,0 +1,9 @@
+import { BasicResourceData, ResourceData } from './types';
+
+export type ResourceDataCacheRecord = {
+  /** There is a slight chance of inconsistent data retrieval from tx if we allow later transactions to leak resource data into earlier transactions.
+   * This field allows to prevent this. */
+  cacheTxOpenTimestamp: number;
+  data: ResourceData | undefined;
+  readonly basicData: BasicResourceData;
+};

package/src/core/client.ts

@@ -20,6 +20,9 @@ import { PlDriver, PlDriverDefinition } from './driver';
 import { MaintenanceAPI_Ping_Response } from '../proto/github.com/milaboratory/pl/plapi/plapiproto/api';
 import * as tp from 'node:timers/promises';
 import { Dispatcher } from 'undici';
+import { LRUCache } from 'lru-cache';
+import { ResourceDataCacheRecord } from './cache';
+import { DefaultFinalResourceDataPredicate, FinalResourceDataPredicate } from './final';
 
 export type TxOps = PlCallOps & {
   sync?: boolean;
@@ -56,17 +59,33 @@ export class PlClient {
 
   private _serverInfo: MaintenanceAPI_Ping_Response | undefined = undefined;
 
+  //
+  // Caching
+  //
+
+  /** This function determines whether resource data can be cached */
+  public readonly finalPredicate: FinalResourceDataPredicate;
+
+  /** Resource data cache, to minimize redundant data rereading from remote db */
+  private readonly resourceDataCache: LRUCache<ResourceId, ResourceDataCacheRecord>;
+
   private constructor(
     configOrAddress: PlClientConfig | string,
     auth: AuthOps,
     ops: {
       statusListener?: PlConnectionStatusListener;
+      finalPredicate?: FinalResourceDataPredicate;
     } = {}
   ) {
     this.ll = new LLPlClient(configOrAddress, { auth, ...ops });
     const conf = this.ll.conf;
     this.txDelay = conf.txDelay;
     this.forceSync = conf.forceSync;
+    this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;
+    this.resourceDataCache = new LRUCache({
+      maxSize: conf.maxCacheBytes,
+      sizeCalculation: (v) => (v.basicData.data?.length ?? 0) + 64
+    });
     switch (conf.retryBackoffAlgorithm) {
       case 'exponential':
         this.defaultRetryOptions = {
@@ -199,7 +218,14 @@ export class PlClient {
       // opening low-level tx
       const llTx = this.ll.createTx(ops);
       // wrapping it into high-level tx (this also asynchronously sends initialization message)
-      const tx = new PlTransaction(llTx, name, writable, clientRoot);
+      const tx = new PlTransaction(
+        llTx,
+        name,
+        writable,
+        clientRoot,
+        this.finalPredicate,
+        this.resourceDataCache
+      );
 
       let ok = false;
       let result: T | undefined = undefined;

package/src/core/config.ts

@@ -45,6 +45,9 @@ export interface PlClientConfig {
   /** Last resort measure to solve complicated race conditions in pl. */
   forceSync: boolean;
 
+  /** Maximal number of bytes of resource state to cache */
+  maxCacheBytes: number;
+
   //
   // Retry
   //
@@ -54,23 +57,30 @@ export interface PlClientConfig {
    * (pl uses optimistic transaction model with regular retries in write transactions)
    * */
   retryBackoffAlgorithm: 'exponential' | 'linear';
+
   /** Maximal number of attempts in */
   retryMaxAttempts: number;
+
   /** Delay after first failed attempt, in ms. */
   retryInitialDelay: number;
+
   /** Each time delay will be multiplied by this number (1.5 means plus on 50% each attempt) */
   retryExponentialBackoffMultiplier: number;
+
   /** [used only for ] This value will be added to the delay from the previous step, in ms */
   retryLinearBackoffStep: number;
+
   /** Value from 0 to 1, determine level of randomness to introduce to the backoff delays sequence. (0 meaning no randomness) */
   retryJitter: number;
 }
 
-export const DEFAULT_REQUEST_TIMEOUT = 1000;
-export const DEFAULT_TX_TIMEOUT = 10_000;
+export const DEFAULT_REQUEST_TIMEOUT = 2000;
+export const DEFAULT_TX_TIMEOUT = 30_000;
 export const DEFAULT_TOKEN_TTL_SECONDS = 31 * 24 * 60 * 60;
 export const DEFAULT_AUTH_MAX_REFRESH = 12 * 24 * 60 * 60;
 
+export const DEFAULT_MAX_CACHE_BYTES = 35_000_000; // 35 Mb
+
 export const DEFAULT_RETRY_BACKOFF_ALGORITHM = 'exponential';
 export const DEFAULT_RETRY_MAX_ATTEMPTS = 10;
 export const DEFAULT_RETRY_INITIAL_DELAY = 4; // 4 ms
@@ -110,6 +120,8 @@ export function plAddressToConfig(
       txDelay: 0,
       forceSync: false,
 
+      maxCacheBytes: DEFAULT_MAX_CACHE_BYTES,
+
       retryBackoffAlgorithm: DEFAULT_RETRY_BACKOFF_ALGORITHM,
       retryMaxAttempts: DEFAULT_RETRY_MAX_ATTEMPTS,
       retryInitialDelay: DEFAULT_RETRY_INITIAL_DELAY,
@@ -149,6 +161,8 @@ export function plAddressToConfig(
     txDelay: parseInt(url.searchParams.get('tx-delay')) ?? 0,
     forceSync: Boolean(url.searchParams.get('force-sync')) ?? false,
 
+    maxCacheBytes: parseInt(url.searchParams.get('max-cache-bytes')) ?? DEFAULT_MAX_CACHE_BYTES,
+
     retryBackoffAlgorithm: (url.searchParams.get('retry-backoff-algorithm') ??
       DEFAULT_RETRY_BACKOFF_ALGORITHM) as any,
     retryMaxAttempts:

package/src/core/final.ts

@@ -0,0 +1,84 @@
+import { Optional } from 'utility-types';
+import { BasicResourceData, isNotNullResourceId, isNullResourceId, ResourceData } from './types';
+
+/**
+ * Function is used to guide multiple layers of caching in pl-client and derived pl-tree.
+ *
+ * This function defines expected resource-specific state mutation behaviour,
+ * if it returns true, system will expect that this data will never change as long as resource exist.
+ *
+ * If resource data contain information about fields, if should be taken into account, fields are undefined,
+ * "final" state should be calculated for "basic" part of resource data only.
+ */
+export type FinalResourceDataPredicate = (
+  resourceData: Optional<ResourceData, 'fields'>
+) => boolean;
+
+function readyOrDuplicateOrError(r: ResourceData | BasicResourceData): boolean {
+  return (
+    r.resourceReady || isNotNullResourceId(r.originalResourceId) || isNotNullResourceId(r.error)
+  );
+}
+
+function readyAndHasAllOutputsFilled(r: Optional<ResourceData, 'fields'>): boolean {
+  if (!readyOrDuplicateOrError(r)) return false;
+  if (!r.outputsLocked) return false;
+  if (r.fields === undefined) return true; // if fields are not provided basic resource state is not expected to change in the future
+  for (const f of r.fields)
+    if (isNullResourceId(f.error) && (isNullResourceId(f.value) || !f.valueIsFinal)) return false;
+  return true;
+}
+
+// solaly for logging
+const unknownResourceTypeNames = new Set<string>();
+
+/** Default implementation, defining behaviour for built-in resource types. */
+export const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate = (r): boolean => {
+  switch (r.type.name) {
+    case 'StdMap':
+    case 'std/map':
+    case 'EphStdMap':
+    case 'PFrame':
+    case 'BContext':
+    case 'BlockPackCustom':
+    case 'BinaryMap':
+    case 'BinaryValue':
+    case 'BlobMap':
+    case 'BResolveSingle':
+    case 'BResolveSingleNoResult':
+    case 'BQueryResult':
+    case 'TengoTemplate':
+    case 'TengoLib':
+    case 'SoftwareInfo':
+    case 'Dummy':
+      return readyOrDuplicateOrError(r);
+    case 'json/resourceError':
+      return r.type.version === '1';
+    case 'json/object':
+    case 'json/string':
+    case 'json/array':
+    case 'json/number':
+    case 'BContextEnd':
+    case 'Frontend/FromUrl':
+    case 'Frontend/FromFolder':
+    case 'BObjectSpec':
+      return true;
+    case 'UserProject':
+      return false;
+    default:
+      if (r.type.name.startsWith('Blob/')) return true;
+      else if (r.type.name.startsWith('BlobUpload/')) {
+        return readyAndHasAllOutputsFilled(r);
+      } else if (r.type.name.startsWith('PColumnData/')) {
+        return readyOrDuplicateOrError(r);
+      } else {
+        // Unknonw resource type detected
+        // Set used to log this message only once
+        if (!unknownResourceTypeNames.has(r.type.name)) {
+          console.log('UNKNOWN RESOURCE TYPE: ' + r.type.name);
+          unknownResourceTypeNames.add(r.type.name);
+        }
+      }
+  }
+  return false;
+};

package/src/core/ll_client.ts

@@ -77,6 +77,13 @@ export class LLPlClient {
 
     grpcInterceptors.push(this.createErrorInterceptor());
 
+    //
+    // Leaving it here for now
+    // https://github.com/grpc/grpc-node/issues/2788
+    //
+    // We should implement message pooling algorithm to overcome hardcoded NO_DELAY behaviour
+    // of HTTP/2 and allow our small messages to batch together.
+    //
     const grpcOptions: GrpcOptions = {
       host: this.conf.hostAndPort,
       timeout: this.conf.defaultRequestTimeout,
@@ -84,7 +91,7 @@ export class LLPlClient {
         ? ChannelCredentials.createSsl()
         : ChannelCredentials.createInsecure(),
       clientOptions: {
-        'grpc.use_local_subchannel_pool': 1,
+        'grpc.keepalive_time_ms': 30_000, // 30 seconds
         interceptors: grpcInterceptors
       }
     };

package/src/core/transaction.ts

@@ -11,7 +11,9 @@ import {
   ResourceData,
   ResourceId,
   ResourceType,
-  FutureFieldType
+  FutureFieldType,
+  isLocalResourceId,
+  extractBasicResourceData
 } from './types';
 import {
   ClientMessageRequest,
@@ -25,6 +27,9 @@ import { toBytes } from '../util/util';
 import { fieldTypeToProto, protoToField, protoToResource } from './type_conversion';
 import { notEmpty } from '@milaboratories/ts-helpers';
 import { isNotFoundError } from './errors';
+import { FinalResourceDataPredicate } from './final';
+import { LRUCache } from 'lru-cache';
+import { ResourceDataCacheRecord } from './cache';
 
 /** Reference to resource, used only within transaction */
 export interface ResourceRef {
@@ -132,6 +137,9 @@ export class PlTransaction {
   private readonly globalTxId: Promise<bigint>;
   private readonly localTxId: number = PlTransaction.nextLocalTxId();
 
+  /** Used in caching */
+  private readonly txOpenTimestamp = Date.now();
+
   private localResourceIdCounter = 0;
 
   /** Store logical tx open / closed state to prevent invalid sequence of requests.
@@ -148,7 +156,9 @@ export class PlTransaction {
     private readonly ll: LLPlTransaction,
     public readonly name: string,
     public readonly writable: boolean,
-    private readonly _clientRoot: OptionalResourceId
+    private readonly _clientRoot: OptionalResourceId,
+    private readonly finalPredicate: FinalResourceDataPredicate,
+    private readonly sharedResourceDataCache: LRUCache<ResourceId, ResourceDataCacheRecord>
   ) {
     // initiating transaction
     this.globalTxId = this.sendSingleAndParse(
@@ -436,23 +446,82 @@ export class PlTransaction {
     );
   }
 
+  /** This method may return stale resource state from cache if resource was removed */
   public async getResourceData(rId: AnyResourceRef, loadFields: true): Promise<ResourceData>;
+  /** This method may return stale resource state from cache if resource was removed */
   public async getResourceData(rId: AnyResourceRef, loadFields: false): Promise<BasicResourceData>;
+  /** This method may return stale resource state from cache if resource was removed */
   public async getResourceData(
     rId: AnyResourceRef,
     loadFields: boolean
   ): Promise<BasicResourceData | ResourceData>;
+  /** This method may return stale resource state from cache if ignoreCache == false if resource was removed */
   public async getResourceData(
     rId: AnyResourceRef,
-    loadFields: boolean = true
+    loadFields: true,
+    ignoreCache: boolean
+  ): Promise<ResourceData>;
+  /** This method may return stale resource state from cache if ignoreCache == false if resource was removed */
+  public async getResourceData(
+    rId: AnyResourceRef,
+    loadFields: false,
+    ignoreCache: boolean
+  ): Promise<BasicResourceData>;
+  /** This method may return stale resource state from cache if ignoreCache == false if resource was removed */
+  public async getResourceData(
+    rId: AnyResourceRef,
+    loadFields: boolean,
+    ignoreCache: boolean
+  ): Promise<BasicResourceData | ResourceData>;
+  public async getResourceData(
+    rId: AnyResourceRef,
+    loadFields: boolean = true,
+    ignoreCache: boolean = false
   ): Promise<BasicResourceData | ResourceData> {
-    return await this.sendSingleAndParse(
+    if (!ignoreCache && !isResourceRef(rId) && !isLocalResourceId(rId)) {
+      // checking if we can return result from cache
+      const fromCache = this.sharedResourceDataCache.get(rId);
+      if (fromCache && fromCache.cacheTxOpenTimestamp < this.txOpenTimestamp) {
+        if (!loadFields) return fromCache.basicData;
+        else if (fromCache.data) return fromCache.data;
+      }
+    }
+
+    const result = await this.sendSingleAndParse(
       {
         oneofKind: 'resourceGet',
         resourceGet: { resourceId: toResourceId(rId), loadFields: loadFields }
       },
       (r) => protoToResource(notEmpty(r.resourceGet.resource))
     );
+
+    // we will cache only final resource data states
+    // caching result even if we were ignore the cache
+    if (!isResourceRef(rId) && !isLocalResourceId(rId) && this.finalPredicate(result)) {
+      const fromCache = this.sharedResourceDataCache.get(rId);
+      if (fromCache) {
+        if (loadFields && !fromCache.data) {
+          fromCache.data = result;
+          // updating timestamp becuse we updated the record
+          fromCache.cacheTxOpenTimestamp = this.txOpenTimestamp;
+        }
+      } else {
+        if (loadFields)
+          this.sharedResourceDataCache.set(rId, {
+            basicData: extractBasicResourceData(result),
+            data: result,
+            cacheTxOpenTimestamp: this.txOpenTimestamp
+          });
+        else
+          this.sharedResourceDataCache.set(rId, {
+            basicData: extractBasicResourceData(result),
+            data: undefined,
+            cacheTxOpenTimestamp: this.txOpenTimestamp
+          });
+      }
+    }
+
+    return result;
   }
 
   public async getResourceDataIfExists(
@@ -471,7 +540,17 @@ export class PlTransaction {
     rId: AnyResourceRef,
     loadFields: boolean = true
   ): Promise<BasicResourceData | ResourceData | undefined> {
-    return notFoundToUndefined(async () => await this.getResourceData(rId, loadFields));
+    // calling this mehtod will ignore cache, because user intention is to detect resource absence
+    // which cache will prevent
+    const result = await notFoundToUndefined(
+      async () => await this.getResourceData(rId, loadFields, true)
+    );
+
+    // cleaning cache record if resorce was removed from the db
+    if (result === undefined && !isResourceRef(rId) && !isLocalResourceId(rId))
+      this.sharedResourceDataCache.delete(rId);
+
+    return result;
   }
 
   /**

package/src/core/types.ts

@@ -70,7 +70,7 @@ export function resourceTypesEqual(type1: ResourceType, type2: ResourceType): bo
 }
 
 /** Readonly fields here marks properties of resource that can't change according to pl's state machine. */
-export interface BasicResourceData {
+export type BasicResourceData = {
   readonly id: ResourceId;
   readonly originalResourceId: OptionalResourceId;
 
@@ -88,30 +88,57 @@ export interface BasicResourceData {
   /** 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 function extractBasicResourceData(rd: ResourceData): BasicResourceData {
+  const {
+    id,
+    originalResourceId,
+    kind,
+    type,
+    data,
+    error,
+    inputsLocked,
+    outputsLocked,
+    resourceReady,
+    final
+  } = rd;
+  return {
+    id,
+    originalResourceId,
+    kind,
+    type,
+    data,
+    error,
+    inputsLocked,
+    outputsLocked,
+    resourceReady,
+    final
+  };
 }
 
 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 type ResourceData = BasicResourceData & {
+  readonly 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;
+export type FieldData = {
+  readonly name: string;
+  readonly type: FieldType;
+  readonly status: FieldStatus;
+  readonly value: OptionalResourceId;
+  readonly error: OptionalResourceId;
 
   /** True if value the fields points to is in final state. */
-  valueIsFinal: boolean;
-}
+  readonly valueIsFinal: boolean;
+};
 
 //
 // Local / Global ResourceId arithmetics