@milaboratories/pl-client 3.13.2 → 3.14.1

package/dist/core/client.cjs

@@ -114,6 +114,10 @@ var PlClient = class PlClient {
 	async license() {
 		return await this.ll.license();
 	}
+	/** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */
+	async listUsers() {
+		return await this.ll.listUsers();
+	}
 	async getUserRoot(opts = {}) {
 		return this.userResources.getUserRoot(opts);
 	}

package/dist/core/client.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"client.cjs","names":["initialTxStat","plAddressToConfig","LLPlClient","DefaultFinalResourceDataPredicate","LRUCache","addStat","isNullSignedResourceId","ensureSignedResourceIdNotNull","UserResources","ClientRoot","advisoryLock","PlTransaction","parseSignedResourceId","TxCommitConflict","tp"],"sources":["../../src/core/client.ts"],"sourcesContent":["import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from \"./config\";\nimport type { PlCallOps } from \"./ll_client\";\nimport { LLPlClient } from \"./ll_client\";\nimport { PlTransaction, TxCommitConflict } from \"./transaction\";\nimport type { Role } from \"./transaction\";\nimport type { OptionalSignedResourceId, SignedResourceId } from \"./types\";\nimport {\n  ensureSignedResourceIdNotNull,\n  isNullSignedResourceId,\n  NullSignedResourceId,\n  parseSignedResourceId,\n} from \"./types\";\nimport type { ColorProof } from \"./types\";\nimport { ClientRoot } from \"../helpers/pl\";\nimport type { MiLogger, RetryOptions } from \"@milaboratories/ts-helpers\";\nimport { assertNever, createRetryState, nextRetryStateOrError } from \"@milaboratories/ts-helpers\";\nimport type { PlDriver, PlDriverDefinition } from \"./driver\";\nimport type {\n  MaintenanceAPI_Ping_Response,\n  MaintenanceAPI_License_Response,\n} from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport { MaintenanceAPI_Ping_Response_Compression } from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport * as tp from \"node:timers/promises\";\nimport type { Dispatcher } from \"undici\";\nimport { LRUCache } from \"lru-cache\";\nimport type { ResourceDataCacheRecord } from \"./cache\";\nimport type { FinalResourceDataPredicate } from \"./final\";\nimport { DefaultFinalResourceDataPredicate } from \"./final\";\nimport type { AllTxStat, TxStat } from \"./stat\";\nimport { addStat, initialTxStat } from \"./stat\";\nimport type { WireConnection } from \"./wire\";\nimport { advisoryLock } from \"./advisory_locks\";\nimport { plAddressToConfig } from \"./config\";\nimport { UserResources } from \"./user_resources\";\nimport type { BackendCapability } from \"./capabilities\";\n\nexport type TxOps = PlCallOps & {\n  sync?: boolean;\n  retryOptions?: RetryOptions;\n  name?: string;\n  lockId?: string;\n};\n\nconst defaultTxOps = {\n  sync: false,\n};\n\nfunction alternativeRootFieldName(alternativeRoot: string): string {\n  return `alternative_root_${alternativeRoot}`;\n}\n\n/** Client to access core PL API. */\nexport class PlClient {\n  private readonly drivers = new Map<string, PlDriver>();\n\n  /** Artificial delay introduced after write transactions completion, to\n   * somewhat throttle the load on pl. Delay introduced after sync, if requested. */\n  private readonly txDelay: number;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly forceSync: boolean;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly defaultRetryOptions: RetryOptions;\n\n  private readonly buildLLPlClient: (\n    shouldUseGzip: boolean,\n    wireProtocol?: wireProtocol,\n  ) => Promise<LLPlClient>;\n  private _ll?: LLPlClient;\n\n  private get ll(): LLPlClient {\n    if (this._ll === undefined) {\n      throw new Error(\"LLPlClient not initialized\");\n    }\n    return this._ll;\n  }\n\n  /** Stores client root (this abstraction is intended for future implementation of the security model) */\n  private _clientRoot: OptionalSignedResourceId = NullSignedResourceId;\n\n  private _userResources?: UserResources;\n\n  /** Cached effective role of the authenticated session, fetched once during\n   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)\n   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */\n  private _currentUserRole: Role | null = null;\n\n  private _txCommittedStat: TxStat = initialTxStat();\n  private _txConflictStat: TxStat = initialTxStat();\n  private _txErrorStat: TxStat = initialTxStat();\n\n  //\n  // Caching\n  //\n\n  /** This function determines whether resource data can be cached */\n  public readonly finalPredicate: FinalResourceDataPredicate;\n\n  /** Resource data cache, to minimize redundant data rereading from remote db */\n  private readonly resourceDataCache: LRUCache<SignedResourceId, ResourceDataCacheRecord>;\n\n  private constructor(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      finalPredicate?: FinalResourceDataPredicate;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const conf =\n      typeof configOrAddress === \"string\" ? plAddressToConfig(configOrAddress) : configOrAddress;\n\n    // An empty or whitespace-only asUser means \"no impersonation\"; normalize to undefined so a\n    // directly-constructed { asUser: \"\" } does not slip through as an empty login.\n    if (conf.asUser !== undefined && conf.asUser.trim() === \"\") conf.asUser = undefined;\n\n    // asUser (impersonation) and alternativeRoot both repoint the client root, so they cannot be\n    // combined. Validate here, before init() touches the network, so a misconfiguration fails fast.\n    if (conf.asUser !== undefined && conf.alternativeRoot !== undefined)\n      throw new Error(\"PlClient: asUser and alternativeRoot cannot be combined.\");\n\n    this.buildLLPlClient = async (\n      shouldUseGzip: boolean,\n      wireProtocol?: wireProtocol,\n    ): Promise<LLPlClient> => {\n      if (wireProtocol) conf.wireProtocol = wireProtocol;\n      return await LLPlClient.build(conf, { auth, ...ops, shouldUseGzip });\n    };\n\n    this.txDelay = conf.txDelay;\n    this.forceSync = conf.forceSync;\n    this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;\n    this.resourceDataCache = new LRUCache({\n      maxSize: conf.maxCacheBytes,\n      sizeCalculation: (v) => (v.basicData.data?.length ?? 0) + 64,\n    });\n    switch (conf.retryBackoffAlgorithm) {\n      case \"exponential\":\n        this.defaultRetryOptions = {\n          type: \"exponentialBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffMultiplier: conf.retryExponentialBackoffMultiplier,\n          jitter: conf.retryJitter,\n        };\n        break;\n      case \"linear\":\n        this.defaultRetryOptions = {\n          type: \"linearBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffStep: conf.retryLinearBackoffStep,\n          jitter: conf.retryJitter,\n        };\n        break;\n      default:\n        assertNever(conf.retryBackoffAlgorithm);\n    }\n  }\n\n  public get txCommittedStat(): TxStat {\n    return { ...this._txCommittedStat };\n  }\n\n  public get txConflictStat(): TxStat {\n    return { ...this._txConflictStat };\n  }\n\n  public get txErrorStat(): TxStat {\n    return { ...this._txErrorStat };\n  }\n\n  public get txTotalStat(): TxStat {\n    return addStat(addStat(this._txCommittedStat, this._txConflictStat), this._txErrorStat);\n  }\n\n  public get allTxStat(): AllTxStat {\n    return {\n      committed: this.txCommittedStat,\n      conflict: this.txConflictStat,\n      error: this.txErrorStat,\n    };\n  }\n\n  public async ping(): Promise<MaintenanceAPI_Ping_Response> {\n    return await this.ll.ping();\n  }\n\n  public async license(): Promise<MaintenanceAPI_License_Response> {\n    return await this.ll.license();\n  }\n\n  /**\n   * Returns the user root SignedResourceId via ListUserResources.\n   * @param opts.login - target user login; omit for the authenticated user.\n   * @returns SignedResourceId of the user root, or undefined if the server returned no userRoot entry.\n   * @throws if the backend does not implement ListUserResources (callers should catch with isUnimplementedError).\n   */\n  public async getUserRoot(opts: {\n    login?: string;\n    createIfNotExists: true;\n  }): Promise<SignedResourceId>;\n  public async getUserRoot(opts?: {\n    login?: string;\n    createIfNotExists?: boolean;\n  }): Promise<SignedResourceId | undefined>;\n  public async getUserRoot(\n    opts: { login?: string; createIfNotExists?: boolean } = {},\n  ): Promise<SignedResourceId | undefined> {\n    return this.userResources.getUserRoot(opts);\n  }\n\n  public get conf(): PlClientConfig {\n    return this.ll.conf;\n  }\n\n  public get httpDispatcher(): Dispatcher {\n    return this.ll.httpDispatcher;\n  }\n\n  public get connectionOpts(): WireConnection {\n    return this.ll.wireConnection;\n  }\n\n  private get initialized() {\n    return !isNullSignedResourceId(this._clientRoot);\n  }\n\n  private checkInitialized() {\n    if (!this.initialized) throw new Error(\"Client not initialized\");\n  }\n\n  public get clientRoot(): SignedResourceId {\n    this.checkInitialized();\n    return ensureSignedResourceIdNotNull(this._clientRoot);\n  }\n\n  public get serverInfo(): MaintenanceAPI_Ping_Response {\n    this.checkInitialized();\n    return this._ll!.serverInfo;\n  }\n\n  public hasCapability(capability: BackendCapability): boolean {\n    this.checkInitialized();\n    return this._ll!.hasCapability(capability);\n  }\n\n  /** Effective role of the authenticated session, resolved once during init via\n   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)\n   *  connection, or when the backend predates GetSessionInfo. Mirrors\n   *  {@link authUser}'s null contract. */\n  public get currentUserRole(): Role | null {\n    this.checkInitialized();\n    return this._currentUserRole;\n  }\n\n  /** Login of the authenticated user, or `null` for an anonymous connection. */\n  public get authUser(): string | null {\n    this.checkInitialized();\n    return this.userResources.authUser;\n  }\n\n  /**\n   * True if the backend honors per-file `permissions` on workdir fill rules.\n   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.\n   */\n  public get supportsWritableWorkdirFiles(): boolean {\n    this.checkInitialized();\n    return this._ll!.supportsWritableWorkdirFiles;\n  }\n\n  /** User resources index for discovering data libraries and other shared resources. */\n  public get userResources(): UserResources {\n    if (!this._ll) throw new Error(\"Client not initialized\");\n\n    if (!this._userResources) {\n      this._userResources = new UserResources(this._ll, this._withTx.bind(this), this._ll.authUser);\n    }\n\n    return this._userResources;\n  }\n\n  /** Discovers or creates the user's root resource via UserResources,\n   *  then handles alternativeRoot if configured. */\n  private async init() {\n    if (this.initialized) throw new Error(\"Already initialized\");\n\n    // Initial client is created without gzip to perform server ping and detect optimal wire protocol.\n    // LLPlClient.build() internally calls detectOptimalWireProtocol() which starts with default 'grpc',\n    // then retries with 'rest' if ping fails, alternating until a working protocol is found.\n    // We save the detected wireProtocol here because if the server supports gzip compression,\n    // we'll need to reinitialize the client with gzip enabled - passing the already-detected\n    // wireProtocol avoids redundant protocol detection on reinit.\n    this._ll = await this.buildLLPlClient(false);\n    const wireProtocol = this._ll.wireProtocol;\n\n    // LLPlClient.build() guarantees a successful ping; read the cached response instead of pinging again.\n    const info = this._ll.serverInfo;\n    if (info.compression === MaintenanceAPI_Ping_Response_Compression.GZIP) {\n      await this._ll.close();\n      this._ll = await this.buildLLPlClient(true, wireProtocol);\n    }\n\n    // Resolve the client root. Normally the caller's own root; when `asUser` is set (admin impersonation),\n    // the target user's root instead. The backend authorizes impersonation by role and silently returns the\n    // caller's own root for non-admins, so no client-side role gate is needed here.\n    let userRoot: SignedResourceId;\n    if (this.conf.asUser === undefined) {\n      userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });\n    } else {\n      const impersonatedRoot = await this.userResources.getUserRoot({ login: this.conf.asUser });\n      if (impersonatedRoot === undefined)\n        throw new Error(\n          `PlClient: cannot open root of user '${this.conf.asUser}': no root found (the user may have never logged in).`,\n        );\n      userRoot = impersonatedRoot;\n    }\n\n    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,\n    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,\n    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.\n    if (this.userResources.authUser !== null && this._ll.hasCapability(\"publicGrants:v1\")) {\n      this._currentUserRole = (await this._ll.getSessionInfo()).role;\n    }\n\n    if (this.conf.alternativeRoot === undefined) {\n      this._clientRoot = userRoot;\n    } else {\n      this._clientRoot = await this._withTx(\"initialization\", true, userRoot, async (tx) => {\n        const aFId = {\n          resourceId: userRoot,\n          fieldName: alternativeRootFieldName(this.conf.alternativeRoot!),\n        };\n\n        const altRoot = tx.createEphemeral(ClientRoot);\n        tx.lock(altRoot);\n        tx.createField(aFId, \"Dynamic\");\n        tx.setField(aFId, altRoot);\n        await tx.commit();\n\n        return await altRoot.globalId;\n      });\n    }\n  }\n\n  /** Returns true if field existed */\n  public async deleteAlternativeRoot(alternativeRootName: string): Promise<boolean> {\n    this.checkInitialized();\n    if (this.ll.conf.alternativeRoot !== undefined)\n      throw new Error(\"Initialized with alternative root.\");\n    return await this.withWriteTx(\"delete-alternative-root\", async (tx) => {\n      const fId = {\n        resourceId: tx.clientRoot,\n        fieldName: alternativeRootFieldName(alternativeRootName),\n      };\n      const exists = tx.fieldExists(fId);\n      tx.removeField(fId);\n      await tx.commit();\n      return await exists;\n    });\n  }\n\n  private async _withTx<T>(\n    name: string,\n    writable: boolean,\n    clientRoot: OptionalSignedResourceId,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops?: TxOps,\n  ): Promise<T> {\n    // for exponential / linear backoff\n    let retryState = createRetryState(ops?.retryOptions ?? this.defaultRetryOptions);\n\n    while (true) {\n      const release = ops?.lockId ? await advisoryLock(ops.lockId) : () => {};\n\n      try {\n        // opening low-level tx\n        const llTx = this.ll.createTx(writable, ops);\n        // wrapping it into high-level tx (this also asynchronously sends initialization message)\n        const tx = new PlTransaction(\n          llTx,\n          name,\n          writable,\n          clientRoot,\n          this.finalPredicate,\n          this.resourceDataCache,\n        );\n\n        // Auto-set default color proof from the client root's signature.\n        // Skip when backend doesn't implement the `set_default_color` TX request.\n        if (this.ll.supportsResourceSignatures && !isNullSignedResourceId(clientRoot) && writable) {\n          const parsed = parseSignedResourceId(clientRoot);\n          if (parsed.signature) {\n            tx.setDefaultColor(parsed.signature as ColorProof);\n          }\n        }\n\n        let ok = false;\n        let result: T | undefined = undefined;\n        let txId;\n\n        try {\n          // executing transaction body\n          result = await body(tx);\n          // collecting stat\n          this._txCommittedStat = addStat(this._txCommittedStat, tx.stat);\n          ok = true;\n        } catch (e: unknown) {\n          // the only recoverable\n          if (e instanceof TxCommitConflict) {\n            // ignoring\n            // collecting stat\n            this._txConflictStat = addStat(this._txConflictStat, tx.stat);\n          } else {\n            // collecting stat\n            this._txErrorStat = addStat(this._txErrorStat, tx.stat);\n            throw e;\n          }\n        } finally {\n          // close underlying grpc stream, if not yet done\n\n          // even though we can skip two lines below for read-only transactions,\n          // we don't do it to simplify reasoning about what is going on in\n          // concurrent code, especially in significant latency situations\n          await tx.complete();\n          await tx.await();\n\n          txId = await tx.getGlobalTxId();\n        }\n\n        if (ok) {\n          // syncing on transaction if requested\n          if (ops?.sync === undefined ? this.forceSync : ops?.sync) await this.ll.txSync(txId);\n\n          // introducing artificial delay, if requested\n          if (writable && this.txDelay > 0)\n            await tp.setTimeout(this.txDelay, undefined, { signal: ops?.abortSignal });\n\n          return result!;\n        }\n      } finally {\n        release();\n      }\n\n      // we only get here after TxCommitConflict error,\n      // all other errors terminate this loop instantly\n\n      await tp.setTimeout(retryState.nextDelay, undefined, { signal: ops?.abortSignal });\n      retryState = nextRetryStateOrError(retryState);\n    }\n  }\n\n  private async withTx<T>(\n    name: string,\n    writable: boolean,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, writable, this.clientRoot, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withWriteTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, true, body, { ...ops, ...defaultTxOps });\n  }\n\n  /**\n   * Runs a write transaction whose default color is `root`'s signature instead of the client\n   * root's, and whose `tx.clientRoot` is `root`. For admin cross-root operations (e.g. copying a\n   * project into another user's root so the copy is minted in that user's color). The backend\n   * still authorizes the write by role.\n   */\n  public async withWriteTxOnRoot<T>(\n    root: SignedResourceId,\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, true, root, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withReadTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, false, body, { ...ops, ...defaultTxOps });\n  }\n\n  public getDriver<Drv extends PlDriver>(definition: PlDriverDefinition<Drv>): Drv {\n    const attached = this.drivers.get(definition.name);\n    if (attached !== undefined) return attached as Drv;\n    const driver = definition.init(this, this.ll, this.httpDispatcher);\n    this.drivers.set(definition.name, driver);\n    return driver;\n  }\n\n  /** Closes underlying transport */\n  public async close() {\n    await this.ll.close();\n  }\n\n  public static async init(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const pl = new PlClient(configOrAddress, auth, ops);\n    await pl.init();\n    return pl;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA2CA,MAAM,eAAe,EACnB,MAAM,MACR;AAEA,SAAS,yBAAyB,iBAAiC;CACjE,OAAO,oBAAoB;AAC7B;;AAGA,IAAa,WAAb,MAAa,SAAS;CACpB,0BAA2B,IAAI,IAAsB;;;CAIrD;;CAGA;;CAGA;CAEA;CAIA;CAEA,IAAY,KAAiB;EAC3B,IAAI,KAAK,QAAQ,KAAA,GACf,MAAM,IAAI,MAAM,4BAA4B;EAE9C,OAAO,KAAK;CACd;;CAGA,cAAQ;CAER;;;;CAKA,mBAAwC;CAExC,mBAAmCA,aAAAA,cAAc;CACjD,kBAAkCA,aAAAA,cAAc;CAChD,eAA+BA,aAAAA,cAAc;;CAO7C;;CAGA;CAEA,YACE,iBACA,MACA,MAII,CAAC,GACL;EACA,MAAM,OACJ,OAAO,oBAAoB,WAAWC,eAAAA,kBAAkB,eAAe,IAAI;EAI7E,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,OAAO,KAAK,MAAM,IAAI,KAAK,SAAS,KAAA;EAI1E,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,oBAAoB,KAAA,GACxD,MAAM,IAAI,MAAM,0DAA0D;EAE5E,KAAK,kBAAkB,OACrB,eACA,iBACwB;GACxB,IAAI,cAAc,KAAK,eAAe;GACtC,OAAO,MAAMC,kBAAAA,WAAW,MAAM,MAAM;IAAE;IAAM,GAAG;IAAK;GAAc,CAAC;EACrE;EAEA,KAAK,UAAU,KAAK;EACpB,KAAK,YAAY,KAAK;EACtB,KAAK,iBAAiB,IAAI,kBAAkBC,cAAAA;EAC5C,KAAK,oBAAoB,IAAIC,UAAAA,SAAS;GACpC,SAAS,KAAK;GACd,kBAAkB,OAAO,EAAE,UAAU,MAAM,UAAU,KAAK;EAC5D,CAAC;EACD,QAAQ,KAAK,uBAAb;GACE,KAAK;IACH,KAAK,sBAAsB;KACzB,MAAM;KACN,cAAc,KAAK;KACnB,aAAa,KAAK;KAClB,mBAAmB,KAAK;KACxB,QAAQ,KAAK;IACf;IACA;GACF,KAAK;IACH,KAAK,sBAAsB;KACzB,MAAM;KACN,cAAc,KAAK;KACnB,aAAa,KAAK;KAClB,aAAa,KAAK;KAClB,QAAQ,KAAK;IACf;IACA;GACF,SACE,CAAA,GAAA,2BAAA,YAAA,CAAY,KAAK,qBAAqB;EAC1C;CACF;CAEA,IAAW,kBAA0B;EACnC,OAAO,EAAE,GAAG,KAAK,iBAAiB;CACpC;CAEA,IAAW,iBAAyB;EAClC,OAAO,EAAE,GAAG,KAAK,gBAAgB;CACnC;CAEA,IAAW,cAAsB;EAC/B,OAAO,EAAE,GAAG,KAAK,aAAa;CAChC;CAEA,IAAW,cAAsB;EAC/B,OAAOC,aAAAA,QAAQA,aAAAA,QAAQ,KAAK,kBAAkB,KAAK,eAAe,GAAG,KAAK,YAAY;CACxF;CAEA,IAAW,YAAuB;EAChC,OAAO;GACL,WAAW,KAAK;GAChB,UAAU,KAAK;GACf,OAAO,KAAK;EACd;CACF;CAEA,MAAa,OAA8C;EACzD,OAAO,MAAM,KAAK,GAAG,KAAK;CAC5B;CAEA,MAAa,UAAoD;EAC/D,OAAO,MAAM,KAAK,GAAG,QAAQ;CAC/B;CAgBA,MAAa,YACX,OAAwD,CAAC,GAClB;EACvC,OAAO,KAAK,cAAc,YAAY,IAAI;CAC5C;CAEA,IAAW,OAAuB;EAChC,OAAO,KAAK,GAAG;CACjB;CAEA,IAAW,iBAA6B;EACtC,OAAO,KAAK,GAAG;CACjB;CAEA,IAAW,iBAAiC;EAC1C,OAAO,KAAK,GAAG;CACjB;CAEA,IAAY,cAAc;EACxB,OAAO,CAACC,cAAAA,uBAAuB,KAAK,WAAW;CACjD;CAEA,mBAA2B;EACzB,IAAI,CAAC,KAAK,aAAa,MAAM,IAAI,MAAM,wBAAwB;CACjE;CAEA,IAAW,aAA+B;EACxC,KAAK,iBAAiB;EACtB,OAAOC,cAAAA,8BAA8B,KAAK,WAAW;CACvD;CAEA,IAAW,aAA2C;EACpD,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK;CACnB;CAEA,cAAqB,YAAwC;EAC3D,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK,cAAc,UAAU;CAC3C;;;;;CAMA,IAAW,kBAA+B;EACxC,KAAK,iBAAiB;EACtB,OAAO,KAAK;CACd;;CAGA,IAAW,WAA0B;EACnC,KAAK,iBAAiB;EACtB,OAAO,KAAK,cAAc;CAC5B;;;;;CAMA,IAAW,+BAAwC;EACjD,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK;CACnB;;CAGA,IAAW,gBAA+B;EACxC,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,MAAM,wBAAwB;EAEvD,IAAI,CAAC,KAAK,gBACR,KAAK,iBAAiB,IAAIC,uBAAAA,cAAc,KAAK,KAAK,KAAK,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ;EAG9F,OAAO,KAAK;CACd;;;CAIA,MAAc,OAAO;EACnB,IAAI,KAAK,aAAa,MAAM,IAAI,MAAM,qBAAqB;EAQ3D,KAAK,MAAM,MAAM,KAAK,gBAAgB,KAAK;EAC3C,MAAM,eAAe,KAAK,IAAI;EAI9B,IADa,KAAK,IAAI,WACb,gBAAA,GAA+D;GACtE,MAAM,KAAK,IAAI,MAAM;GACrB,KAAK,MAAM,MAAM,KAAK,gBAAgB,MAAM,YAAY;EAC1D;EAKA,IAAI;EACJ,IAAI,KAAK,KAAK,WAAW,KAAA,GACvB,WAAW,MAAM,KAAK,cAAc,YAAY,EAAE,mBAAmB,KAAK,CAAC;OACtE;GACL,MAAM,mBAAmB,MAAM,KAAK,cAAc,YAAY,EAAE,OAAO,KAAK,KAAK,OAAO,CAAC;GACzF,IAAI,qBAAqB,KAAA,GACvB,MAAM,IAAI,MACR,uCAAuC,KAAK,KAAK,OAAO,sDAC1D;GACF,WAAW;EACb;EAKA,IAAI,KAAK,cAAc,aAAa,QAAQ,KAAK,IAAI,cAAc,iBAAiB,GAClF,KAAK,oBAAoB,MAAM,KAAK,IAAI,eAAe,EAAA,CAAG;EAG5D,IAAI,KAAK,KAAK,oBAAoB,KAAA,GAChC,KAAK,cAAc;OAEnB,KAAK,cAAc,MAAM,KAAK,QAAQ,kBAAkB,MAAM,UAAU,OAAO,OAAO;GACpF,MAAM,OAAO;IACX,YAAY;IACZ,WAAW,yBAAyB,KAAK,KAAK,eAAgB;GAChE;GAEA,MAAM,UAAU,GAAG,gBAAgBC,WAAAA,UAAU;GAC7C,GAAG,KAAK,OAAO;GACf,GAAG,YAAY,MAAM,SAAS;GAC9B,GAAG,SAAS,MAAM,OAAO;GACzB,MAAM,GAAG,OAAO;GAEhB,OAAO,MAAM,QAAQ;EACvB,CAAC;CAEL;;CAGA,MAAa,sBAAsB,qBAA+C;EAChF,KAAK,iBAAiB;EACtB,IAAI,KAAK,GAAG,KAAK,oBAAoB,KAAA,GACnC,MAAM,IAAI,MAAM,oCAAoC;EACtD,OAAO,MAAM,KAAK,YAAY,2BAA2B,OAAO,OAAO;GACrE,MAAM,MAAM;IACV,YAAY,GAAG;IACf,WAAW,yBAAyB,mBAAmB;GACzD;GACA,MAAM,SAAS,GAAG,YAAY,GAAG;GACjC,GAAG,YAAY,GAAG;GAClB,MAAM,GAAG,OAAO;GAChB,OAAO,MAAM;EACf,CAAC;CACH;CAEA,MAAc,QACZ,MACA,UACA,YACA,MACA,KACY;EAEZ,IAAI,cAAA,GAAA,2BAAA,iBAAA,CAA8B,KAAK,gBAAgB,KAAK,mBAAmB;EAE/E,OAAO,MAAM;GACX,MAAM,UAAU,KAAK,SAAS,MAAMC,uBAAAA,aAAa,IAAI,MAAM,UAAU,CAAC;GAEtE,IAAI;IAIF,MAAM,KAAK,IAAIC,oBAAAA,cAFF,KAAK,GAAG,SAAS,UAAU,GAGnC,GACH,MACA,UACA,YACA,KAAK,gBACL,KAAK,iBACP;IAIA,IAAI,KAAK,GAAG,8BAA8B,CAACL,cAAAA,uBAAuB,UAAU,KAAK,UAAU;KACzF,MAAM,SAASM,cAAAA,sBAAsB,UAAU;KAC/C,IAAI,OAAO,WACT,GAAG,gBAAgB,OAAO,SAAuB;IAErD;IAEA,IAAI,KAAK;IACT,IAAI,SAAwB,KAAA;IAC5B,IAAI;IAEJ,IAAI;KAEF,SAAS,MAAM,KAAK,EAAE;KAEtB,KAAK,mBAAmBP,aAAAA,QAAQ,KAAK,kBAAkB,GAAG,IAAI;KAC9D,KAAK;IACP,SAAS,GAAY;KAEnB,IAAI,aAAaQ,oBAAAA,kBAGf,KAAK,kBAAkBR,aAAAA,QAAQ,KAAK,iBAAiB,GAAG,IAAI;UACvD;MAEL,KAAK,eAAeA,aAAAA,QAAQ,KAAK,cAAc,GAAG,IAAI;MACtD,MAAM;KACR;IACF,UAAU;KAMR,MAAM,GAAG,SAAS;KAClB,MAAM,GAAG,MAAM;KAEf,OAAO,MAAM,GAAG,cAAc;IAChC;IAEA,IAAI,IAAI;KAEN,IAAI,KAAK,SAAS,KAAA,IAAY,KAAK,YAAY,KAAK,MAAM,MAAM,KAAK,GAAG,OAAO,IAAI;KAGnF,IAAI,YAAY,KAAK,UAAU,GAC7B,MAAMS,qBAAG,WAAW,KAAK,SAAS,KAAA,GAAW,EAAE,QAAQ,KAAK,YAAY,CAAC;KAE3E,OAAO;IACT;GACF,UAAU;IACR,QAAQ;GACV;GAKA,MAAMA,qBAAG,WAAW,WAAW,WAAW,KAAA,GAAW,EAAE,QAAQ,KAAK,YAAY,CAAC;GACjF,cAAA,GAAA,2BAAA,sBAAA,CAAmC,UAAU;EAC/C;CACF;CAEA,MAAc,OACZ,MACA,UACA,MACA,MAAsB,CAAC,GACX;EACZ,KAAK,iBAAiB;EACtB,OAAO,MAAM,KAAK,QAAQ,MAAM,UAAU,KAAK,YAAY,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CAC9F;CAEA,MAAa,YACX,MACA,MACA,MAAsB,CAAC,GACX;EACZ,OAAO,MAAM,KAAK,OAAO,MAAM,MAAM,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CACxE;;;;;;;CAQA,MAAa,kBACX,MACA,MACA,MACA,MAAsB,CAAC,GACX;EACZ,KAAK,iBAAiB;EACtB,OAAO,MAAM,KAAK,QAAQ,MAAM,MAAM,MAAM,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CAC/E;CAEA,MAAa,WACX,MACA,MACA,MAAsB,CAAC,GACX;EACZ,OAAO,MAAM,KAAK,OAAO,MAAM,OAAO,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CACzE;CAEA,UAAuC,YAA0C;EAC/E,MAAM,WAAW,KAAK,QAAQ,IAAI,WAAW,IAAI;EACjD,IAAI,aAAa,KAAA,GAAW,OAAO;EACnC,MAAM,SAAS,WAAW,KAAK,MAAM,KAAK,IAAI,KAAK,cAAc;EACjE,KAAK,QAAQ,IAAI,WAAW,MAAM,MAAM;EACxC,OAAO;CACT;;CAGA,MAAa,QAAQ;EACnB,MAAM,KAAK,GAAG,MAAM;CACtB;CAEA,aAAoB,KAClB,iBACA,MACA,MAGI,CAAC,GACL;EACA,MAAM,KAAK,IAAI,SAAS,iBAAiB,MAAM,GAAG;EAClD,MAAM,GAAG,KAAK;EACd,OAAO;CACT;AACF"}
+{"version":3,"file":"client.cjs","names":["initialTxStat","plAddressToConfig","LLPlClient","DefaultFinalResourceDataPredicate","LRUCache","addStat","isNullSignedResourceId","ensureSignedResourceIdNotNull","UserResources","ClientRoot","advisoryLock","PlTransaction","parseSignedResourceId","TxCommitConflict","tp"],"sources":["../../src/core/client.ts"],"sourcesContent":["import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from \"./config\";\nimport type { PlCallOps } from \"./ll_client\";\nimport { LLPlClient } from \"./ll_client\";\nimport { PlTransaction, TxCommitConflict } from \"./transaction\";\nimport type { Role } from \"./transaction\";\nimport type { OptionalSignedResourceId, SignedResourceId } from \"./types\";\nimport {\n  ensureSignedResourceIdNotNull,\n  isNullSignedResourceId,\n  NullSignedResourceId,\n  parseSignedResourceId,\n} from \"./types\";\nimport type { ColorProof } from \"./types\";\nimport { ClientRoot } from \"../helpers/pl\";\nimport type { MiLogger, RetryOptions } from \"@milaboratories/ts-helpers\";\nimport { assertNever, createRetryState, nextRetryStateOrError } from \"@milaboratories/ts-helpers\";\nimport type { PlDriver, PlDriverDefinition } from \"./driver\";\nimport type {\n  MaintenanceAPI_Ping_Response,\n  MaintenanceAPI_License_Response,\n  AuthAPI_User,\n} from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport { MaintenanceAPI_Ping_Response_Compression } from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport * as tp from \"node:timers/promises\";\nimport type { Dispatcher } from \"undici\";\nimport { LRUCache } from \"lru-cache\";\nimport type { ResourceDataCacheRecord } from \"./cache\";\nimport type { FinalResourceDataPredicate } from \"./final\";\nimport { DefaultFinalResourceDataPredicate } from \"./final\";\nimport type { AllTxStat, TxStat } from \"./stat\";\nimport { addStat, initialTxStat } from \"./stat\";\nimport type { WireConnection } from \"./wire\";\nimport { advisoryLock } from \"./advisory_locks\";\nimport { plAddressToConfig } from \"./config\";\nimport { UserResources } from \"./user_resources\";\nimport type { BackendCapability } from \"./capabilities\";\n\nexport type TxOps = PlCallOps & {\n  sync?: boolean;\n  retryOptions?: RetryOptions;\n  name?: string;\n  lockId?: string;\n};\n\nconst defaultTxOps = {\n  sync: false,\n};\n\nfunction alternativeRootFieldName(alternativeRoot: string): string {\n  return `alternative_root_${alternativeRoot}`;\n}\n\n/** Client to access core PL API. */\nexport class PlClient {\n  private readonly drivers = new Map<string, PlDriver>();\n\n  /** Artificial delay introduced after write transactions completion, to\n   * somewhat throttle the load on pl. Delay introduced after sync, if requested. */\n  private readonly txDelay: number;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly forceSync: boolean;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly defaultRetryOptions: RetryOptions;\n\n  private readonly buildLLPlClient: (\n    shouldUseGzip: boolean,\n    wireProtocol?: wireProtocol,\n  ) => Promise<LLPlClient>;\n  private _ll?: LLPlClient;\n\n  private get ll(): LLPlClient {\n    if (this._ll === undefined) {\n      throw new Error(\"LLPlClient not initialized\");\n    }\n    return this._ll;\n  }\n\n  /** Stores client root (this abstraction is intended for future implementation of the security model) */\n  private _clientRoot: OptionalSignedResourceId = NullSignedResourceId;\n\n  private _userResources?: UserResources;\n\n  /** Cached effective role of the authenticated session, fetched once during\n   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)\n   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */\n  private _currentUserRole: Role | null = null;\n\n  private _txCommittedStat: TxStat = initialTxStat();\n  private _txConflictStat: TxStat = initialTxStat();\n  private _txErrorStat: TxStat = initialTxStat();\n\n  //\n  // Caching\n  //\n\n  /** This function determines whether resource data can be cached */\n  public readonly finalPredicate: FinalResourceDataPredicate;\n\n  /** Resource data cache, to minimize redundant data rereading from remote db */\n  private readonly resourceDataCache: LRUCache<SignedResourceId, ResourceDataCacheRecord>;\n\n  private constructor(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      finalPredicate?: FinalResourceDataPredicate;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const conf =\n      typeof configOrAddress === \"string\" ? plAddressToConfig(configOrAddress) : configOrAddress;\n\n    // An empty or whitespace-only asUser means \"no impersonation\"; normalize to undefined so a\n    // directly-constructed { asUser: \"\" } does not slip through as an empty login.\n    if (conf.asUser !== undefined && conf.asUser.trim() === \"\") conf.asUser = undefined;\n\n    // asUser (impersonation) and alternativeRoot both repoint the client root, so they cannot be\n    // combined. Validate here, before init() touches the network, so a misconfiguration fails fast.\n    if (conf.asUser !== undefined && conf.alternativeRoot !== undefined)\n      throw new Error(\"PlClient: asUser and alternativeRoot cannot be combined.\");\n\n    this.buildLLPlClient = async (\n      shouldUseGzip: boolean,\n      wireProtocol?: wireProtocol,\n    ): Promise<LLPlClient> => {\n      if (wireProtocol) conf.wireProtocol = wireProtocol;\n      return await LLPlClient.build(conf, { auth, ...ops, shouldUseGzip });\n    };\n\n    this.txDelay = conf.txDelay;\n    this.forceSync = conf.forceSync;\n    this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;\n    this.resourceDataCache = new LRUCache({\n      maxSize: conf.maxCacheBytes,\n      sizeCalculation: (v) => (v.basicData.data?.length ?? 0) + 64,\n    });\n    switch (conf.retryBackoffAlgorithm) {\n      case \"exponential\":\n        this.defaultRetryOptions = {\n          type: \"exponentialBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffMultiplier: conf.retryExponentialBackoffMultiplier,\n          jitter: conf.retryJitter,\n        };\n        break;\n      case \"linear\":\n        this.defaultRetryOptions = {\n          type: \"linearBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffStep: conf.retryLinearBackoffStep,\n          jitter: conf.retryJitter,\n        };\n        break;\n      default:\n        assertNever(conf.retryBackoffAlgorithm);\n    }\n  }\n\n  public get txCommittedStat(): TxStat {\n    return { ...this._txCommittedStat };\n  }\n\n  public get txConflictStat(): TxStat {\n    return { ...this._txConflictStat };\n  }\n\n  public get txErrorStat(): TxStat {\n    return { ...this._txErrorStat };\n  }\n\n  public get txTotalStat(): TxStat {\n    return addStat(addStat(this._txCommittedStat, this._txConflictStat), this._txErrorStat);\n  }\n\n  public get allTxStat(): AllTxStat {\n    return {\n      committed: this.txCommittedStat,\n      conflict: this.txConflictStat,\n      error: this.txErrorStat,\n    };\n  }\n\n  public async ping(): Promise<MaintenanceAPI_Ping_Response> {\n    return await this.ll.ping();\n  }\n\n  public async license(): Promise<MaintenanceAPI_License_Response> {\n    return await this.ll.license();\n  }\n\n  /** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */\n  public async listUsers(): Promise<AuthAPI_User[]> {\n    return await this.ll.listUsers();\n  }\n\n  /**\n   * Returns the user root SignedResourceId via ListUserResources.\n   * @param opts.login - target user login; omit for the authenticated user.\n   * @returns SignedResourceId of the user root, or undefined if the server returned no userRoot entry.\n   * @throws if the backend does not implement ListUserResources (callers should catch with isUnimplementedError).\n   */\n  public async getUserRoot(opts: {\n    login?: string;\n    createIfNotExists: true;\n  }): Promise<SignedResourceId>;\n  public async getUserRoot(opts?: {\n    login?: string;\n    createIfNotExists?: boolean;\n  }): Promise<SignedResourceId | undefined>;\n  public async getUserRoot(\n    opts: { login?: string; createIfNotExists?: boolean } = {},\n  ): Promise<SignedResourceId | undefined> {\n    return this.userResources.getUserRoot(opts);\n  }\n\n  public get conf(): PlClientConfig {\n    return this.ll.conf;\n  }\n\n  public get httpDispatcher(): Dispatcher {\n    return this.ll.httpDispatcher;\n  }\n\n  public get connectionOpts(): WireConnection {\n    return this.ll.wireConnection;\n  }\n\n  private get initialized() {\n    return !isNullSignedResourceId(this._clientRoot);\n  }\n\n  private checkInitialized() {\n    if (!this.initialized) throw new Error(\"Client not initialized\");\n  }\n\n  public get clientRoot(): SignedResourceId {\n    this.checkInitialized();\n    return ensureSignedResourceIdNotNull(this._clientRoot);\n  }\n\n  public get serverInfo(): MaintenanceAPI_Ping_Response {\n    this.checkInitialized();\n    return this._ll!.serverInfo;\n  }\n\n  public hasCapability(capability: BackendCapability): boolean {\n    this.checkInitialized();\n    return this._ll!.hasCapability(capability);\n  }\n\n  /** Effective role of the authenticated session, resolved once during init via\n   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)\n   *  connection, or when the backend predates GetSessionInfo. Mirrors\n   *  {@link authUser}'s null contract. */\n  public get currentUserRole(): Role | null {\n    this.checkInitialized();\n    return this._currentUserRole;\n  }\n\n  /** Login of the authenticated user, or `null` for an anonymous connection. */\n  public get authUser(): string | null {\n    this.checkInitialized();\n    return this.userResources.authUser;\n  }\n\n  /**\n   * True if the backend honors per-file `permissions` on workdir fill rules.\n   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.\n   */\n  public get supportsWritableWorkdirFiles(): boolean {\n    this.checkInitialized();\n    return this._ll!.supportsWritableWorkdirFiles;\n  }\n\n  /** User resources index for discovering data libraries and other shared resources. */\n  public get userResources(): UserResources {\n    if (!this._ll) throw new Error(\"Client not initialized\");\n\n    if (!this._userResources) {\n      this._userResources = new UserResources(this._ll, this._withTx.bind(this), this._ll.authUser);\n    }\n\n    return this._userResources;\n  }\n\n  /** Discovers or creates the user's root resource via UserResources,\n   *  then handles alternativeRoot if configured. */\n  private async init() {\n    if (this.initialized) throw new Error(\"Already initialized\");\n\n    // Initial client is created without gzip to perform server ping and detect optimal wire protocol.\n    // LLPlClient.build() internally calls detectOptimalWireProtocol() which starts with default 'grpc',\n    // then retries with 'rest' if ping fails, alternating until a working protocol is found.\n    // We save the detected wireProtocol here because if the server supports gzip compression,\n    // we'll need to reinitialize the client with gzip enabled - passing the already-detected\n    // wireProtocol avoids redundant protocol detection on reinit.\n    this._ll = await this.buildLLPlClient(false);\n    const wireProtocol = this._ll.wireProtocol;\n\n    // LLPlClient.build() guarantees a successful ping; read the cached response instead of pinging again.\n    const info = this._ll.serverInfo;\n    if (info.compression === MaintenanceAPI_Ping_Response_Compression.GZIP) {\n      await this._ll.close();\n      this._ll = await this.buildLLPlClient(true, wireProtocol);\n    }\n\n    // Resolve the client root. Normally the caller's own root; when `asUser` is set (admin impersonation),\n    // the target user's root instead. The backend authorizes impersonation by role and silently returns the\n    // caller's own root for non-admins, so no client-side role gate is needed here.\n    let userRoot: SignedResourceId;\n    if (this.conf.asUser === undefined) {\n      userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });\n    } else {\n      const impersonatedRoot = await this.userResources.getUserRoot({ login: this.conf.asUser });\n      if (impersonatedRoot === undefined)\n        throw new Error(\n          `PlClient: cannot open root of user '${this.conf.asUser}': no root found (the user may have never logged in).`,\n        );\n      userRoot = impersonatedRoot;\n    }\n\n    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,\n    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,\n    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.\n    if (this.userResources.authUser !== null && this._ll.hasCapability(\"publicGrants:v1\")) {\n      this._currentUserRole = (await this._ll.getSessionInfo()).role;\n    }\n\n    if (this.conf.alternativeRoot === undefined) {\n      this._clientRoot = userRoot;\n    } else {\n      this._clientRoot = await this._withTx(\"initialization\", true, userRoot, async (tx) => {\n        const aFId = {\n          resourceId: userRoot,\n          fieldName: alternativeRootFieldName(this.conf.alternativeRoot!),\n        };\n\n        const altRoot = tx.createEphemeral(ClientRoot);\n        tx.lock(altRoot);\n        tx.createField(aFId, \"Dynamic\");\n        tx.setField(aFId, altRoot);\n        await tx.commit();\n\n        return await altRoot.globalId;\n      });\n    }\n  }\n\n  /** Returns true if field existed */\n  public async deleteAlternativeRoot(alternativeRootName: string): Promise<boolean> {\n    this.checkInitialized();\n    if (this.ll.conf.alternativeRoot !== undefined)\n      throw new Error(\"Initialized with alternative root.\");\n    return await this.withWriteTx(\"delete-alternative-root\", async (tx) => {\n      const fId = {\n        resourceId: tx.clientRoot,\n        fieldName: alternativeRootFieldName(alternativeRootName),\n      };\n      const exists = tx.fieldExists(fId);\n      tx.removeField(fId);\n      await tx.commit();\n      return await exists;\n    });\n  }\n\n  private async _withTx<T>(\n    name: string,\n    writable: boolean,\n    clientRoot: OptionalSignedResourceId,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops?: TxOps,\n  ): Promise<T> {\n    // for exponential / linear backoff\n    let retryState = createRetryState(ops?.retryOptions ?? this.defaultRetryOptions);\n\n    while (true) {\n      const release = ops?.lockId ? await advisoryLock(ops.lockId) : () => {};\n\n      try {\n        // opening low-level tx\n        const llTx = this.ll.createTx(writable, ops);\n        // wrapping it into high-level tx (this also asynchronously sends initialization message)\n        const tx = new PlTransaction(\n          llTx,\n          name,\n          writable,\n          clientRoot,\n          this.finalPredicate,\n          this.resourceDataCache,\n        );\n\n        // Auto-set default color proof from the client root's signature.\n        // Skip when backend doesn't implement the `set_default_color` TX request.\n        if (this.ll.supportsResourceSignatures && !isNullSignedResourceId(clientRoot) && writable) {\n          const parsed = parseSignedResourceId(clientRoot);\n          if (parsed.signature) {\n            tx.setDefaultColor(parsed.signature as ColorProof);\n          }\n        }\n\n        let ok = false;\n        let result: T | undefined = undefined;\n        let txId;\n\n        try {\n          // executing transaction body\n          result = await body(tx);\n          // collecting stat\n          this._txCommittedStat = addStat(this._txCommittedStat, tx.stat);\n          ok = true;\n        } catch (e: unknown) {\n          // the only recoverable\n          if (e instanceof TxCommitConflict) {\n            // ignoring\n            // collecting stat\n            this._txConflictStat = addStat(this._txConflictStat, tx.stat);\n          } else {\n            // collecting stat\n            this._txErrorStat = addStat(this._txErrorStat, tx.stat);\n            throw e;\n          }\n        } finally {\n          // close underlying grpc stream, if not yet done\n\n          // even though we can skip two lines below for read-only transactions,\n          // we don't do it to simplify reasoning about what is going on in\n          // concurrent code, especially in significant latency situations\n          await tx.complete();\n          await tx.await();\n\n          txId = await tx.getGlobalTxId();\n        }\n\n        if (ok) {\n          // syncing on transaction if requested\n          if (ops?.sync === undefined ? this.forceSync : ops?.sync) await this.ll.txSync(txId);\n\n          // introducing artificial delay, if requested\n          if (writable && this.txDelay > 0)\n            await tp.setTimeout(this.txDelay, undefined, { signal: ops?.abortSignal });\n\n          return result!;\n        }\n      } finally {\n        release();\n      }\n\n      // we only get here after TxCommitConflict error,\n      // all other errors terminate this loop instantly\n\n      await tp.setTimeout(retryState.nextDelay, undefined, { signal: ops?.abortSignal });\n      retryState = nextRetryStateOrError(retryState);\n    }\n  }\n\n  private async withTx<T>(\n    name: string,\n    writable: boolean,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, writable, this.clientRoot, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withWriteTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, true, body, { ...ops, ...defaultTxOps });\n  }\n\n  /**\n   * Runs a write transaction whose default color is `root`'s signature instead of the client\n   * root's, and whose `tx.clientRoot` is `root`. For admin cross-root operations (e.g. copying a\n   * project into another user's root so the copy is minted in that user's color). The backend\n   * still authorizes the write by role.\n   */\n  public async withWriteTxOnRoot<T>(\n    root: SignedResourceId,\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, true, root, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withReadTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, false, body, { ...ops, ...defaultTxOps });\n  }\n\n  public getDriver<Drv extends PlDriver>(definition: PlDriverDefinition<Drv>): Drv {\n    const attached = this.drivers.get(definition.name);\n    if (attached !== undefined) return attached as Drv;\n    const driver = definition.init(this, this.ll, this.httpDispatcher);\n    this.drivers.set(definition.name, driver);\n    return driver;\n  }\n\n  /** Closes underlying transport */\n  public async close() {\n    await this.ll.close();\n  }\n\n  public static async init(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const pl = new PlClient(configOrAddress, auth, ops);\n    await pl.init();\n    return pl;\n  }\n}\n"],"mappings":"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"}

package/dist/core/client.d.ts

@@ -1,5 +1,5 @@
 import { SignedResourceId } from "./types.js";
-import { MaintenanceAPI_License_Response, MaintenanceAPI_Ping_Response } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api.js";
+import { AuthAPI_User, MaintenanceAPI_License_Response, MaintenanceAPI_Ping_Response } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api.js";
 import { FinalResourceDataPredicate } from "./final.js";
 import { AllTxStat, TxStat } from "./stat.js";
 import { PlTransaction, Role } from "./transaction.js";
@@ -54,6 +54,8 @@ declare class PlClient {
   get allTxStat(): AllTxStat;
   ping(): Promise<MaintenanceAPI_Ping_Response>;
   license(): Promise<MaintenanceAPI_License_Response>;
+  /** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */
+  listUsers(): Promise<AuthAPI_User[]>;
   /**
    * Returns the user root SignedResourceId via ListUserResources.
    * @param opts.login - target user login; omit for the authenticated user.

package/dist/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","names":[],"sources":["../../src/core/client.ts"],"mappings":";;;;;;;;;;;;;;;KAoCY,KAAA,GAAQ,SAAA;EAClB,IAAA;EACA,YAAA,GAAe,YAAY;EAC3B,IAAA;EACA,MAAA;AAAA;;cAYW,QAAA;EAAA,iBACM,OAAA;EAdjB;;EAAA,iBAkBiB,OAAA;EAjBX;EAAA,iBAoBW,SAAA;EARE;EAAA,iBAWF,mBAAA;EAAA,iBAEA,eAAA;EAAA,QAIT,GAAA;EAAA,YAEI,EAAA;EAmGc;EAAA,QA3FlB,WAAA;EAAA,QAEA,cAAA;EAyGqB;;;EAAA,QApGrB,gBAAA;EAAA,QAEA,gBAAA;EAAA,QACA,eAAA;EAAA,QACA,YAAA;EAqHJ;EAAA,SA9GY,cAAA,EAAgB,0BAAA;EAyHH;EAAA,iBAtHZ,iBAAA;EAAA,QAEV,WAAA;EAAA,IA4DI,eAAA,IAAmB,MAAA;EAAA,IAInB,cAAA,IAAkB,MAAA;EAAA,IAIlB,WAAA,IAAe,MAAA;EAAA,IAIf,WAAA,IAAe,MAAA;EAAA,IAIf,SAAA,IAAa,SAAA;EAQX,IAAA,IAAQ,OAAA,CAAQ,4BAAA;EAIhB,OAAA,IAAW,OAAA,CAAQ,+BAAA;EAoRD;;;;;;EA1QlB,WAAA,CAAY,IAAA;IACvB,KAAA;IACA,iBAAA;EAAA,IACE,OAAA,CAAQ,gBAAA;EACC,WAAA,CAAY,IAAA;IACvB,KAAA;IACA,iBAAA;EAAA,IACE,OAAA,CAAQ,gBAAA;EAAA,IAOD,IAAA,IAAQ,cAAA;EAAA,IAIR,cAAA,IAAkB,UAAA;EAAA,IAIlB,cAAA,IAAkB,cAAA;EAAA,YAIjB,WAAA;EAAA,QAIJ,gBAAA;EAAA,IAIG,UAAA,IAAc,gBAAA;EAAA,IAKd,UAAA,IAAc,4BAAA;EAKlB,aAAA,CAAc,UAAA,EAAY,iBAAA;EA4PkB;;;;EAAA,IAnPxC,eAAA,IAAmB,IAAA;EAoQT;EAAA,IA9PV,QAAA;EAgQH;;;;EAAA,IAvPG,4BAAA;EAnNM;EAAA,IAyNN,aAAA,IAAiB,aAAA;EAnNX;;EAAA,QA+NH,IAAA;EAvNF;EAqRC,qBAAA,CAAsB,mBAAA,WAA8B,OAAA;EAAA,QAgBnD,OAAA;EAAA,QA0FA,MAAA;EAUD,WAAA,IACX,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EA3XH;;;;;;EAqYK,iBAAA,IACX,IAAA,EAAM,gBAAA,EACN,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EAKE,UAAA,IACX,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EAIJ,SAAA,aAAsB,QAAA,EAAU,UAAA,EAAY,kBAAA,CAAmB,GAAA,IAAO,GAAA;EA1UhD;EAmVhB,KAAA,IAAK,OAAA;EAAA,OAIE,IAAA,CAClB,eAAA,EAAiB,cAAA,WACjB,IAAA,EAAM,OAAA,EACN,GAAA;IACE,cAAA,GAAiB,0BAAA;IACjB,MAAA,GAAS,QAAA;EAAA,IACL,OAAA,CAAA,QAAA;AAAA"}
+{"version":3,"file":"client.d.ts","names":[],"sources":["../../src/core/client.ts"],"mappings":";;;;;;;;;;;;;;;KAqCY,KAAA,GAAQ,SAAA;EAClB,IAAA;EACA,YAAA,GAAe,YAAY;EAC3B,IAAA;EACA,MAAA;AAAA;;cAYW,QAAA;EAAA,iBACM,OAAA;EAdjB;;EAAA,iBAkBiB,OAAA;EAjBX;EAAA,iBAoBW,SAAA;EARE;EAAA,iBAWF,mBAAA;EAAA,iBAEA,eAAA;EAAA,QAIT,GAAA;EAAA,YAEI,EAAA;EAmGc;EAAA,QA3FlB,WAAA;EAAA,QAEA,cAAA;EAyGqB;;;EAAA,QApGrB,gBAAA;EAAA,QAEA,gBAAA;EAAA,QACA,eAAA;EAAA,QACA,YAAA;EAsHJ;EAAA,SA/GY,cAAA,EAAgB,0BAAA;EAmH5B;EAAA,iBAhHa,iBAAA;EAAA,QAEV,WAAA;EAAA,IA4DI,eAAA,IAAmB,MAAA;EAAA,IAInB,cAAA,IAAkB,MAAA;EAAA,IAIlB,WAAA,IAAe,MAAA;EAAA,IAIf,WAAA,IAAe,MAAA;EAAA,IAIf,SAAA,IAAa,SAAA;EAQX,IAAA,IAAQ,OAAA,CAAQ,4BAAA;EAIhB,OAAA,IAAW,OAAA,CAAQ,+BAAA;EAyRnB;EApRA,SAAA,IAAa,OAAA,CAAQ,YAAA;EAoRH;;;;;;EA1QlB,WAAA,CAAY,IAAA;IACvB,KAAA;IACA,iBAAA;EAAA,IACE,OAAA,CAAQ,gBAAA;EACC,WAAA,CAAY,IAAA;IACvB,KAAA;IACA,iBAAA;EAAA,IACE,OAAA,CAAQ,gBAAA;EAAA,IAOD,IAAA,IAAQ,cAAA;EAAA,IAIR,cAAA,IAAkB,UAAA;EAAA,IAIlB,cAAA,IAAkB,cAAA;EAAA,YAIjB,WAAA;EAAA,QAIJ,gBAAA;EAAA,IAIG,UAAA,IAAc,gBAAA;EAAA,IAKd,UAAA,IAAc,4BAAA;EAKlB,aAAA,CAAc,UAAA,EAAY,iBAAA;EA4PkB;;;;EAAA,IAnPxC,eAAA,IAAmB,IAAA;EAoQT;EAAA,IA9PV,QAAA;EAgQH;;;;EAAA,IAvPG,4BAAA;EAxNM;EAAA,IA8NN,aAAA,IAAiB,aAAA;EAxNX;;EAAA,QAoOH,IAAA;EA5NF;EA0RC,qBAAA,CAAsB,mBAAA,WAA8B,OAAA;EAAA,QAgBnD,OAAA;EAAA,QA0FA,MAAA;EAUD,WAAA,IACX,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EAhYH;;;;;;EA0YK,iBAAA,IACX,IAAA,EAAM,gBAAA,EACN,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EAKE,UAAA,IACX,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,aAAA,KAAkB,OAAA,CAAQ,CAAA,GACrC,GAAA,GAAK,OAAA,CAAQ,KAAA,IACZ,OAAA,CAAQ,CAAA;EAIJ,SAAA,aAAsB,QAAA,EAAU,UAAA,EAAY,kBAAA,CAAmB,GAAA,IAAO,GAAA;EA/UhD;EAwVhB,KAAA,IAAK,OAAA;EAAA,OAIE,IAAA,CAClB,eAAA,EAAiB,cAAA,WACjB,IAAA,EAAM,OAAA,EACN,GAAA;IACE,cAAA,GAAiB,0BAAA;IACjB,MAAA,GAAS,QAAA;EAAA,IACL,OAAA,CAAA,QAAA;AAAA"}

package/dist/core/client.js

@@ -112,6 +112,10 @@ var PlClient = class PlClient {
 	async license() {
 		return await this.ll.license();
 	}
+	/** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */
+	async listUsers() {
+		return await this.ll.listUsers();
+	}
 	async getUserRoot(opts = {}) {
 		return this.userResources.getUserRoot(opts);
 	}

package/dist/core/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../src/core/client.ts"],"sourcesContent":["import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from \"./config\";\nimport type { PlCallOps } from \"./ll_client\";\nimport { LLPlClient } from \"./ll_client\";\nimport { PlTransaction, TxCommitConflict } from \"./transaction\";\nimport type { Role } from \"./transaction\";\nimport type { OptionalSignedResourceId, SignedResourceId } from \"./types\";\nimport {\n  ensureSignedResourceIdNotNull,\n  isNullSignedResourceId,\n  NullSignedResourceId,\n  parseSignedResourceId,\n} from \"./types\";\nimport type { ColorProof } from \"./types\";\nimport { ClientRoot } from \"../helpers/pl\";\nimport type { MiLogger, RetryOptions } from \"@milaboratories/ts-helpers\";\nimport { assertNever, createRetryState, nextRetryStateOrError } from \"@milaboratories/ts-helpers\";\nimport type { PlDriver, PlDriverDefinition } from \"./driver\";\nimport type {\n  MaintenanceAPI_Ping_Response,\n  MaintenanceAPI_License_Response,\n} from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport { MaintenanceAPI_Ping_Response_Compression } from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport * as tp from \"node:timers/promises\";\nimport type { Dispatcher } from \"undici\";\nimport { LRUCache } from \"lru-cache\";\nimport type { ResourceDataCacheRecord } from \"./cache\";\nimport type { FinalResourceDataPredicate } from \"./final\";\nimport { DefaultFinalResourceDataPredicate } from \"./final\";\nimport type { AllTxStat, TxStat } from \"./stat\";\nimport { addStat, initialTxStat } from \"./stat\";\nimport type { WireConnection } from \"./wire\";\nimport { advisoryLock } from \"./advisory_locks\";\nimport { plAddressToConfig } from \"./config\";\nimport { UserResources } from \"./user_resources\";\nimport type { BackendCapability } from \"./capabilities\";\n\nexport type TxOps = PlCallOps & {\n  sync?: boolean;\n  retryOptions?: RetryOptions;\n  name?: string;\n  lockId?: string;\n};\n\nconst defaultTxOps = {\n  sync: false,\n};\n\nfunction alternativeRootFieldName(alternativeRoot: string): string {\n  return `alternative_root_${alternativeRoot}`;\n}\n\n/** Client to access core PL API. */\nexport class PlClient {\n  private readonly drivers = new Map<string, PlDriver>();\n\n  /** Artificial delay introduced after write transactions completion, to\n   * somewhat throttle the load on pl. Delay introduced after sync, if requested. */\n  private readonly txDelay: number;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly forceSync: boolean;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly defaultRetryOptions: RetryOptions;\n\n  private readonly buildLLPlClient: (\n    shouldUseGzip: boolean,\n    wireProtocol?: wireProtocol,\n  ) => Promise<LLPlClient>;\n  private _ll?: LLPlClient;\n\n  private get ll(): LLPlClient {\n    if (this._ll === undefined) {\n      throw new Error(\"LLPlClient not initialized\");\n    }\n    return this._ll;\n  }\n\n  /** Stores client root (this abstraction is intended for future implementation of the security model) */\n  private _clientRoot: OptionalSignedResourceId = NullSignedResourceId;\n\n  private _userResources?: UserResources;\n\n  /** Cached effective role of the authenticated session, fetched once during\n   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)\n   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */\n  private _currentUserRole: Role | null = null;\n\n  private _txCommittedStat: TxStat = initialTxStat();\n  private _txConflictStat: TxStat = initialTxStat();\n  private _txErrorStat: TxStat = initialTxStat();\n\n  //\n  // Caching\n  //\n\n  /** This function determines whether resource data can be cached */\n  public readonly finalPredicate: FinalResourceDataPredicate;\n\n  /** Resource data cache, to minimize redundant data rereading from remote db */\n  private readonly resourceDataCache: LRUCache<SignedResourceId, ResourceDataCacheRecord>;\n\n  private constructor(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      finalPredicate?: FinalResourceDataPredicate;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const conf =\n      typeof configOrAddress === \"string\" ? plAddressToConfig(configOrAddress) : configOrAddress;\n\n    // An empty or whitespace-only asUser means \"no impersonation\"; normalize to undefined so a\n    // directly-constructed { asUser: \"\" } does not slip through as an empty login.\n    if (conf.asUser !== undefined && conf.asUser.trim() === \"\") conf.asUser = undefined;\n\n    // asUser (impersonation) and alternativeRoot both repoint the client root, so they cannot be\n    // combined. Validate here, before init() touches the network, so a misconfiguration fails fast.\n    if (conf.asUser !== undefined && conf.alternativeRoot !== undefined)\n      throw new Error(\"PlClient: asUser and alternativeRoot cannot be combined.\");\n\n    this.buildLLPlClient = async (\n      shouldUseGzip: boolean,\n      wireProtocol?: wireProtocol,\n    ): Promise<LLPlClient> => {\n      if (wireProtocol) conf.wireProtocol = wireProtocol;\n      return await LLPlClient.build(conf, { auth, ...ops, shouldUseGzip });\n    };\n\n    this.txDelay = conf.txDelay;\n    this.forceSync = conf.forceSync;\n    this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;\n    this.resourceDataCache = new LRUCache({\n      maxSize: conf.maxCacheBytes,\n      sizeCalculation: (v) => (v.basicData.data?.length ?? 0) + 64,\n    });\n    switch (conf.retryBackoffAlgorithm) {\n      case \"exponential\":\n        this.defaultRetryOptions = {\n          type: \"exponentialBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffMultiplier: conf.retryExponentialBackoffMultiplier,\n          jitter: conf.retryJitter,\n        };\n        break;\n      case \"linear\":\n        this.defaultRetryOptions = {\n          type: \"linearBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffStep: conf.retryLinearBackoffStep,\n          jitter: conf.retryJitter,\n        };\n        break;\n      default:\n        assertNever(conf.retryBackoffAlgorithm);\n    }\n  }\n\n  public get txCommittedStat(): TxStat {\n    return { ...this._txCommittedStat };\n  }\n\n  public get txConflictStat(): TxStat {\n    return { ...this._txConflictStat };\n  }\n\n  public get txErrorStat(): TxStat {\n    return { ...this._txErrorStat };\n  }\n\n  public get txTotalStat(): TxStat {\n    return addStat(addStat(this._txCommittedStat, this._txConflictStat), this._txErrorStat);\n  }\n\n  public get allTxStat(): AllTxStat {\n    return {\n      committed: this.txCommittedStat,\n      conflict: this.txConflictStat,\n      error: this.txErrorStat,\n    };\n  }\n\n  public async ping(): Promise<MaintenanceAPI_Ping_Response> {\n    return await this.ll.ping();\n  }\n\n  public async license(): Promise<MaintenanceAPI_License_Response> {\n    return await this.ll.license();\n  }\n\n  /**\n   * Returns the user root SignedResourceId via ListUserResources.\n   * @param opts.login - target user login; omit for the authenticated user.\n   * @returns SignedResourceId of the user root, or undefined if the server returned no userRoot entry.\n   * @throws if the backend does not implement ListUserResources (callers should catch with isUnimplementedError).\n   */\n  public async getUserRoot(opts: {\n    login?: string;\n    createIfNotExists: true;\n  }): Promise<SignedResourceId>;\n  public async getUserRoot(opts?: {\n    login?: string;\n    createIfNotExists?: boolean;\n  }): Promise<SignedResourceId | undefined>;\n  public async getUserRoot(\n    opts: { login?: string; createIfNotExists?: boolean } = {},\n  ): Promise<SignedResourceId | undefined> {\n    return this.userResources.getUserRoot(opts);\n  }\n\n  public get conf(): PlClientConfig {\n    return this.ll.conf;\n  }\n\n  public get httpDispatcher(): Dispatcher {\n    return this.ll.httpDispatcher;\n  }\n\n  public get connectionOpts(): WireConnection {\n    return this.ll.wireConnection;\n  }\n\n  private get initialized() {\n    return !isNullSignedResourceId(this._clientRoot);\n  }\n\n  private checkInitialized() {\n    if (!this.initialized) throw new Error(\"Client not initialized\");\n  }\n\n  public get clientRoot(): SignedResourceId {\n    this.checkInitialized();\n    return ensureSignedResourceIdNotNull(this._clientRoot);\n  }\n\n  public get serverInfo(): MaintenanceAPI_Ping_Response {\n    this.checkInitialized();\n    return this._ll!.serverInfo;\n  }\n\n  public hasCapability(capability: BackendCapability): boolean {\n    this.checkInitialized();\n    return this._ll!.hasCapability(capability);\n  }\n\n  /** Effective role of the authenticated session, resolved once during init via\n   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)\n   *  connection, or when the backend predates GetSessionInfo. Mirrors\n   *  {@link authUser}'s null contract. */\n  public get currentUserRole(): Role | null {\n    this.checkInitialized();\n    return this._currentUserRole;\n  }\n\n  /** Login of the authenticated user, or `null` for an anonymous connection. */\n  public get authUser(): string | null {\n    this.checkInitialized();\n    return this.userResources.authUser;\n  }\n\n  /**\n   * True if the backend honors per-file `permissions` on workdir fill rules.\n   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.\n   */\n  public get supportsWritableWorkdirFiles(): boolean {\n    this.checkInitialized();\n    return this._ll!.supportsWritableWorkdirFiles;\n  }\n\n  /** User resources index for discovering data libraries and other shared resources. */\n  public get userResources(): UserResources {\n    if (!this._ll) throw new Error(\"Client not initialized\");\n\n    if (!this._userResources) {\n      this._userResources = new UserResources(this._ll, this._withTx.bind(this), this._ll.authUser);\n    }\n\n    return this._userResources;\n  }\n\n  /** Discovers or creates the user's root resource via UserResources,\n   *  then handles alternativeRoot if configured. */\n  private async init() {\n    if (this.initialized) throw new Error(\"Already initialized\");\n\n    // Initial client is created without gzip to perform server ping and detect optimal wire protocol.\n    // LLPlClient.build() internally calls detectOptimalWireProtocol() which starts with default 'grpc',\n    // then retries with 'rest' if ping fails, alternating until a working protocol is found.\n    // We save the detected wireProtocol here because if the server supports gzip compression,\n    // we'll need to reinitialize the client with gzip enabled - passing the already-detected\n    // wireProtocol avoids redundant protocol detection on reinit.\n    this._ll = await this.buildLLPlClient(false);\n    const wireProtocol = this._ll.wireProtocol;\n\n    // LLPlClient.build() guarantees a successful ping; read the cached response instead of pinging again.\n    const info = this._ll.serverInfo;\n    if (info.compression === MaintenanceAPI_Ping_Response_Compression.GZIP) {\n      await this._ll.close();\n      this._ll = await this.buildLLPlClient(true, wireProtocol);\n    }\n\n    // Resolve the client root. Normally the caller's own root; when `asUser` is set (admin impersonation),\n    // the target user's root instead. The backend authorizes impersonation by role and silently returns the\n    // caller's own root for non-admins, so no client-side role gate is needed here.\n    let userRoot: SignedResourceId;\n    if (this.conf.asUser === undefined) {\n      userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });\n    } else {\n      const impersonatedRoot = await this.userResources.getUserRoot({ login: this.conf.asUser });\n      if (impersonatedRoot === undefined)\n        throw new Error(\n          `PlClient: cannot open root of user '${this.conf.asUser}': no root found (the user may have never logged in).`,\n        );\n      userRoot = impersonatedRoot;\n    }\n\n    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,\n    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,\n    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.\n    if (this.userResources.authUser !== null && this._ll.hasCapability(\"publicGrants:v1\")) {\n      this._currentUserRole = (await this._ll.getSessionInfo()).role;\n    }\n\n    if (this.conf.alternativeRoot === undefined) {\n      this._clientRoot = userRoot;\n    } else {\n      this._clientRoot = await this._withTx(\"initialization\", true, userRoot, async (tx) => {\n        const aFId = {\n          resourceId: userRoot,\n          fieldName: alternativeRootFieldName(this.conf.alternativeRoot!),\n        };\n\n        const altRoot = tx.createEphemeral(ClientRoot);\n        tx.lock(altRoot);\n        tx.createField(aFId, \"Dynamic\");\n        tx.setField(aFId, altRoot);\n        await tx.commit();\n\n        return await altRoot.globalId;\n      });\n    }\n  }\n\n  /** Returns true if field existed */\n  public async deleteAlternativeRoot(alternativeRootName: string): Promise<boolean> {\n    this.checkInitialized();\n    if (this.ll.conf.alternativeRoot !== undefined)\n      throw new Error(\"Initialized with alternative root.\");\n    return await this.withWriteTx(\"delete-alternative-root\", async (tx) => {\n      const fId = {\n        resourceId: tx.clientRoot,\n        fieldName: alternativeRootFieldName(alternativeRootName),\n      };\n      const exists = tx.fieldExists(fId);\n      tx.removeField(fId);\n      await tx.commit();\n      return await exists;\n    });\n  }\n\n  private async _withTx<T>(\n    name: string,\n    writable: boolean,\n    clientRoot: OptionalSignedResourceId,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops?: TxOps,\n  ): Promise<T> {\n    // for exponential / linear backoff\n    let retryState = createRetryState(ops?.retryOptions ?? this.defaultRetryOptions);\n\n    while (true) {\n      const release = ops?.lockId ? await advisoryLock(ops.lockId) : () => {};\n\n      try {\n        // opening low-level tx\n        const llTx = this.ll.createTx(writable, ops);\n        // wrapping it into high-level tx (this also asynchronously sends initialization message)\n        const tx = new PlTransaction(\n          llTx,\n          name,\n          writable,\n          clientRoot,\n          this.finalPredicate,\n          this.resourceDataCache,\n        );\n\n        // Auto-set default color proof from the client root's signature.\n        // Skip when backend doesn't implement the `set_default_color` TX request.\n        if (this.ll.supportsResourceSignatures && !isNullSignedResourceId(clientRoot) && writable) {\n          const parsed = parseSignedResourceId(clientRoot);\n          if (parsed.signature) {\n            tx.setDefaultColor(parsed.signature as ColorProof);\n          }\n        }\n\n        let ok = false;\n        let result: T | undefined = undefined;\n        let txId;\n\n        try {\n          // executing transaction body\n          result = await body(tx);\n          // collecting stat\n          this._txCommittedStat = addStat(this._txCommittedStat, tx.stat);\n          ok = true;\n        } catch (e: unknown) {\n          // the only recoverable\n          if (e instanceof TxCommitConflict) {\n            // ignoring\n            // collecting stat\n            this._txConflictStat = addStat(this._txConflictStat, tx.stat);\n          } else {\n            // collecting stat\n            this._txErrorStat = addStat(this._txErrorStat, tx.stat);\n            throw e;\n          }\n        } finally {\n          // close underlying grpc stream, if not yet done\n\n          // even though we can skip two lines below for read-only transactions,\n          // we don't do it to simplify reasoning about what is going on in\n          // concurrent code, especially in significant latency situations\n          await tx.complete();\n          await tx.await();\n\n          txId = await tx.getGlobalTxId();\n        }\n\n        if (ok) {\n          // syncing on transaction if requested\n          if (ops?.sync === undefined ? this.forceSync : ops?.sync) await this.ll.txSync(txId);\n\n          // introducing artificial delay, if requested\n          if (writable && this.txDelay > 0)\n            await tp.setTimeout(this.txDelay, undefined, { signal: ops?.abortSignal });\n\n          return result!;\n        }\n      } finally {\n        release();\n      }\n\n      // we only get here after TxCommitConflict error,\n      // all other errors terminate this loop instantly\n\n      await tp.setTimeout(retryState.nextDelay, undefined, { signal: ops?.abortSignal });\n      retryState = nextRetryStateOrError(retryState);\n    }\n  }\n\n  private async withTx<T>(\n    name: string,\n    writable: boolean,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, writable, this.clientRoot, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withWriteTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, true, body, { ...ops, ...defaultTxOps });\n  }\n\n  /**\n   * Runs a write transaction whose default color is `root`'s signature instead of the client\n   * root's, and whose `tx.clientRoot` is `root`. For admin cross-root operations (e.g. copying a\n   * project into another user's root so the copy is minted in that user's color). The backend\n   * still authorizes the write by role.\n   */\n  public async withWriteTxOnRoot<T>(\n    root: SignedResourceId,\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, true, root, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withReadTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, false, body, { ...ops, ...defaultTxOps });\n  }\n\n  public getDriver<Drv extends PlDriver>(definition: PlDriverDefinition<Drv>): Drv {\n    const attached = this.drivers.get(definition.name);\n    if (attached !== undefined) return attached as Drv;\n    const driver = definition.init(this, this.ll, this.httpDispatcher);\n    this.drivers.set(definition.name, driver);\n    return driver;\n  }\n\n  /** Closes underlying transport */\n  public async close() {\n    await this.ll.close();\n  }\n\n  public static async init(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const pl = new PlClient(configOrAddress, auth, ops);\n    await pl.init();\n    return pl;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA2CA,MAAM,eAAe,EACnB,MAAM,MACR;AAEA,SAAS,yBAAyB,iBAAiC;CACjE,OAAO,oBAAoB;AAC7B;;AAGA,IAAa,WAAb,MAAa,SAAS;CACpB,0BAA2B,IAAI,IAAsB;;;CAIrD;;CAGA;;CAGA;CAEA;CAIA;CAEA,IAAY,KAAiB;EAC3B,IAAI,KAAK,QAAQ,KAAA,GACf,MAAM,IAAI,MAAM,4BAA4B;EAE9C,OAAO,KAAK;CACd;;CAGA,cAAQ;CAER;;;;CAKA,mBAAwC;CAExC,mBAAmC,cAAc;CACjD,kBAAkC,cAAc;CAChD,eAA+B,cAAc;;CAO7C;;CAGA;CAEA,YACE,iBACA,MACA,MAII,CAAC,GACL;EACA,MAAM,OACJ,OAAO,oBAAoB,WAAW,kBAAkB,eAAe,IAAI;EAI7E,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,OAAO,KAAK,MAAM,IAAI,KAAK,SAAS,KAAA;EAI1E,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,oBAAoB,KAAA,GACxD,MAAM,IAAI,MAAM,0DAA0D;EAE5E,KAAK,kBAAkB,OACrB,eACA,iBACwB;GACxB,IAAI,cAAc,KAAK,eAAe;GACtC,OAAO,MAAM,WAAW,MAAM,MAAM;IAAE;IAAM,GAAG;IAAK;GAAc,CAAC;EACrE;EAEA,KAAK,UAAU,KAAK;EACpB,KAAK,YAAY,KAAK;EACtB,KAAK,iBAAiB,IAAI,kBAAkB;EAC5C,KAAK,oBAAoB,IAAI,SAAS;GACpC,SAAS,KAAK;GACd,kBAAkB,OAAO,EAAE,UAAU,MAAM,UAAU,KAAK;EAC5D,CAAC;EACD,QAAQ,KAAK,uBAAb;GACE,KAAK;IACH,KAAK,sBAAsB;KACzB,MAAM;KACN,cAAc,KAAK;KACnB,aAAa,KAAK;KAClB,mBAAmB,KAAK;KACxB,QAAQ,KAAK;IACf;IACA;GACF,KAAK;IACH,KAAK,sBAAsB;KACzB,MAAM;KACN,cAAc,KAAK;KACnB,aAAa,KAAK;KAClB,aAAa,KAAK;KAClB,QAAQ,KAAK;IACf;IACA;GACF,SACE,YAAY,KAAK,qBAAqB;EAC1C;CACF;CAEA,IAAW,kBAA0B;EACnC,OAAO,EAAE,GAAG,KAAK,iBAAiB;CACpC;CAEA,IAAW,iBAAyB;EAClC,OAAO,EAAE,GAAG,KAAK,gBAAgB;CACnC;CAEA,IAAW,cAAsB;EAC/B,OAAO,EAAE,GAAG,KAAK,aAAa;CAChC;CAEA,IAAW,cAAsB;EAC/B,OAAO,QAAQ,QAAQ,KAAK,kBAAkB,KAAK,eAAe,GAAG,KAAK,YAAY;CACxF;CAEA,IAAW,YAAuB;EAChC,OAAO;GACL,WAAW,KAAK;GAChB,UAAU,KAAK;GACf,OAAO,KAAK;EACd;CACF;CAEA,MAAa,OAA8C;EACzD,OAAO,MAAM,KAAK,GAAG,KAAK;CAC5B;CAEA,MAAa,UAAoD;EAC/D,OAAO,MAAM,KAAK,GAAG,QAAQ;CAC/B;CAgBA,MAAa,YACX,OAAwD,CAAC,GAClB;EACvC,OAAO,KAAK,cAAc,YAAY,IAAI;CAC5C;CAEA,IAAW,OAAuB;EAChC,OAAO,KAAK,GAAG;CACjB;CAEA,IAAW,iBAA6B;EACtC,OAAO,KAAK,GAAG;CACjB;CAEA,IAAW,iBAAiC;EAC1C,OAAO,KAAK,GAAG;CACjB;CAEA,IAAY,cAAc;EACxB,OAAO,CAAC,uBAAuB,KAAK,WAAW;CACjD;CAEA,mBAA2B;EACzB,IAAI,CAAC,KAAK,aAAa,MAAM,IAAI,MAAM,wBAAwB;CACjE;CAEA,IAAW,aAA+B;EACxC,KAAK,iBAAiB;EACtB,OAAO,8BAA8B,KAAK,WAAW;CACvD;CAEA,IAAW,aAA2C;EACpD,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK;CACnB;CAEA,cAAqB,YAAwC;EAC3D,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK,cAAc,UAAU;CAC3C;;;;;CAMA,IAAW,kBAA+B;EACxC,KAAK,iBAAiB;EACtB,OAAO,KAAK;CACd;;CAGA,IAAW,WAA0B;EACnC,KAAK,iBAAiB;EACtB,OAAO,KAAK,cAAc;CAC5B;;;;;CAMA,IAAW,+BAAwC;EACjD,KAAK,iBAAiB;EACtB,OAAO,KAAK,IAAK;CACnB;;CAGA,IAAW,gBAA+B;EACxC,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,MAAM,wBAAwB;EAEvD,IAAI,CAAC,KAAK,gBACR,KAAK,iBAAiB,IAAI,cAAc,KAAK,KAAK,KAAK,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ;EAG9F,OAAO,KAAK;CACd;;;CAIA,MAAc,OAAO;EACnB,IAAI,KAAK,aAAa,MAAM,IAAI,MAAM,qBAAqB;EAQ3D,KAAK,MAAM,MAAM,KAAK,gBAAgB,KAAK;EAC3C,MAAM,eAAe,KAAK,IAAI;EAI9B,IADa,KAAK,IAAI,WACb,gBAAA,GAA+D;GACtE,MAAM,KAAK,IAAI,MAAM;GACrB,KAAK,MAAM,MAAM,KAAK,gBAAgB,MAAM,YAAY;EAC1D;EAKA,IAAI;EACJ,IAAI,KAAK,KAAK,WAAW,KAAA,GACvB,WAAW,MAAM,KAAK,cAAc,YAAY,EAAE,mBAAmB,KAAK,CAAC;OACtE;GACL,MAAM,mBAAmB,MAAM,KAAK,cAAc,YAAY,EAAE,OAAO,KAAK,KAAK,OAAO,CAAC;GACzF,IAAI,qBAAqB,KAAA,GACvB,MAAM,IAAI,MACR,uCAAuC,KAAK,KAAK,OAAO,sDAC1D;GACF,WAAW;EACb;EAKA,IAAI,KAAK,cAAc,aAAa,QAAQ,KAAK,IAAI,cAAc,iBAAiB,GAClF,KAAK,oBAAoB,MAAM,KAAK,IAAI,eAAe,EAAA,CAAG;EAG5D,IAAI,KAAK,KAAK,oBAAoB,KAAA,GAChC,KAAK,cAAc;OAEnB,KAAK,cAAc,MAAM,KAAK,QAAQ,kBAAkB,MAAM,UAAU,OAAO,OAAO;GACpF,MAAM,OAAO;IACX,YAAY;IACZ,WAAW,yBAAyB,KAAK,KAAK,eAAgB;GAChE;GAEA,MAAM,UAAU,GAAG,gBAAgB,UAAU;GAC7C,GAAG,KAAK,OAAO;GACf,GAAG,YAAY,MAAM,SAAS;GAC9B,GAAG,SAAS,MAAM,OAAO;GACzB,MAAM,GAAG,OAAO;GAEhB,OAAO,MAAM,QAAQ;EACvB,CAAC;CAEL;;CAGA,MAAa,sBAAsB,qBAA+C;EAChF,KAAK,iBAAiB;EACtB,IAAI,KAAK,GAAG,KAAK,oBAAoB,KAAA,GACnC,MAAM,IAAI,MAAM,oCAAoC;EACtD,OAAO,MAAM,KAAK,YAAY,2BAA2B,OAAO,OAAO;GACrE,MAAM,MAAM;IACV,YAAY,GAAG;IACf,WAAW,yBAAyB,mBAAmB;GACzD;GACA,MAAM,SAAS,GAAG,YAAY,GAAG;GACjC,GAAG,YAAY,GAAG;GAClB,MAAM,GAAG,OAAO;GAChB,OAAO,MAAM;EACf,CAAC;CACH;CAEA,MAAc,QACZ,MACA,UACA,YACA,MACA,KACY;EAEZ,IAAI,aAAa,iBAAiB,KAAK,gBAAgB,KAAK,mBAAmB;EAE/E,OAAO,MAAM;GACX,MAAM,UAAU,KAAK,SAAS,MAAM,aAAa,IAAI,MAAM,UAAU,CAAC;GAEtE,IAAI;IAIF,MAAM,KAAK,IAAI,cAFF,KAAK,GAAG,SAAS,UAAU,GAGnC,GACH,MACA,UACA,YACA,KAAK,gBACL,KAAK,iBACP;IAIA,IAAI,KAAK,GAAG,8BAA8B,CAAC,uBAAuB,UAAU,KAAK,UAAU;KACzF,MAAM,SAAS,sBAAsB,UAAU;KAC/C,IAAI,OAAO,WACT,GAAG,gBAAgB,OAAO,SAAuB;IAErD;IAEA,IAAI,KAAK;IACT,IAAI,SAAwB,KAAA;IAC5B,IAAI;IAEJ,IAAI;KAEF,SAAS,MAAM,KAAK,EAAE;KAEtB,KAAK,mBAAmB,QAAQ,KAAK,kBAAkB,GAAG,IAAI;KAC9D,KAAK;IACP,SAAS,GAAY;KAEnB,IAAI,aAAa,kBAGf,KAAK,kBAAkB,QAAQ,KAAK,iBAAiB,GAAG,IAAI;UACvD;MAEL,KAAK,eAAe,QAAQ,KAAK,cAAc,GAAG,IAAI;MACtD,MAAM;KACR;IACF,UAAU;KAMR,MAAM,GAAG,SAAS;KAClB,MAAM,GAAG,MAAM;KAEf,OAAO,MAAM,GAAG,cAAc;IAChC;IAEA,IAAI,IAAI;KAEN,IAAI,KAAK,SAAS,KAAA,IAAY,KAAK,YAAY,KAAK,MAAM,MAAM,KAAK,GAAG,OAAO,IAAI;KAGnF,IAAI,YAAY,KAAK,UAAU,GAC7B,MAAM,GAAG,WAAW,KAAK,SAAS,KAAA,GAAW,EAAE,QAAQ,KAAK,YAAY,CAAC;KAE3E,OAAO;IACT;GACF,UAAU;IACR,QAAQ;GACV;GAKA,MAAM,GAAG,WAAW,WAAW,WAAW,KAAA,GAAW,EAAE,QAAQ,KAAK,YAAY,CAAC;GACjF,aAAa,sBAAsB,UAAU;EAC/C;CACF;CAEA,MAAc,OACZ,MACA,UACA,MACA,MAAsB,CAAC,GACX;EACZ,KAAK,iBAAiB;EACtB,OAAO,MAAM,KAAK,QAAQ,MAAM,UAAU,KAAK,YAAY,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CAC9F;CAEA,MAAa,YACX,MACA,MACA,MAAsB,CAAC,GACX;EACZ,OAAO,MAAM,KAAK,OAAO,MAAM,MAAM,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CACxE;;;;;;;CAQA,MAAa,kBACX,MACA,MACA,MACA,MAAsB,CAAC,GACX;EACZ,KAAK,iBAAiB;EACtB,OAAO,MAAM,KAAK,QAAQ,MAAM,MAAM,MAAM,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CAC/E;CAEA,MAAa,WACX,MACA,MACA,MAAsB,CAAC,GACX;EACZ,OAAO,MAAM,KAAK,OAAO,MAAM,OAAO,MAAM;GAAE,GAAG;GAAK,GAAG;EAAa,CAAC;CACzE;CAEA,UAAuC,YAA0C;EAC/E,MAAM,WAAW,KAAK,QAAQ,IAAI,WAAW,IAAI;EACjD,IAAI,aAAa,KAAA,GAAW,OAAO;EACnC,MAAM,SAAS,WAAW,KAAK,MAAM,KAAK,IAAI,KAAK,cAAc;EACjE,KAAK,QAAQ,IAAI,WAAW,MAAM,MAAM;EACxC,OAAO;CACT;;CAGA,MAAa,QAAQ;EACnB,MAAM,KAAK,GAAG,MAAM;CACtB;CAEA,aAAoB,KAClB,iBACA,MACA,MAGI,CAAC,GACL;EACA,MAAM,KAAK,IAAI,SAAS,iBAAiB,MAAM,GAAG;EAClD,MAAM,GAAG,KAAK;EACd,OAAO;CACT;AACF"}
+{"version":3,"file":"client.js","names":[],"sources":["../../src/core/client.ts"],"sourcesContent":["import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from \"./config\";\nimport type { PlCallOps } from \"./ll_client\";\nimport { LLPlClient } from \"./ll_client\";\nimport { PlTransaction, TxCommitConflict } from \"./transaction\";\nimport type { Role } from \"./transaction\";\nimport type { OptionalSignedResourceId, SignedResourceId } from \"./types\";\nimport {\n  ensureSignedResourceIdNotNull,\n  isNullSignedResourceId,\n  NullSignedResourceId,\n  parseSignedResourceId,\n} from \"./types\";\nimport type { ColorProof } from \"./types\";\nimport { ClientRoot } from \"../helpers/pl\";\nimport type { MiLogger, RetryOptions } from \"@milaboratories/ts-helpers\";\nimport { assertNever, createRetryState, nextRetryStateOrError } from \"@milaboratories/ts-helpers\";\nimport type { PlDriver, PlDriverDefinition } from \"./driver\";\nimport type {\n  MaintenanceAPI_Ping_Response,\n  MaintenanceAPI_License_Response,\n  AuthAPI_User,\n} from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport { MaintenanceAPI_Ping_Response_Compression } from \"../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api\";\nimport * as tp from \"node:timers/promises\";\nimport type { Dispatcher } from \"undici\";\nimport { LRUCache } from \"lru-cache\";\nimport type { ResourceDataCacheRecord } from \"./cache\";\nimport type { FinalResourceDataPredicate } from \"./final\";\nimport { DefaultFinalResourceDataPredicate } from \"./final\";\nimport type { AllTxStat, TxStat } from \"./stat\";\nimport { addStat, initialTxStat } from \"./stat\";\nimport type { WireConnection } from \"./wire\";\nimport { advisoryLock } from \"./advisory_locks\";\nimport { plAddressToConfig } from \"./config\";\nimport { UserResources } from \"./user_resources\";\nimport type { BackendCapability } from \"./capabilities\";\n\nexport type TxOps = PlCallOps & {\n  sync?: boolean;\n  retryOptions?: RetryOptions;\n  name?: string;\n  lockId?: string;\n};\n\nconst defaultTxOps = {\n  sync: false,\n};\n\nfunction alternativeRootFieldName(alternativeRoot: string): string {\n  return `alternative_root_${alternativeRoot}`;\n}\n\n/** Client to access core PL API. */\nexport class PlClient {\n  private readonly drivers = new Map<string, PlDriver>();\n\n  /** Artificial delay introduced after write transactions completion, to\n   * somewhat throttle the load on pl. Delay introduced after sync, if requested. */\n  private readonly txDelay: number;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly forceSync: boolean;\n\n  /** Last resort measure to solve complicated race conditions in pl. */\n  private readonly defaultRetryOptions: RetryOptions;\n\n  private readonly buildLLPlClient: (\n    shouldUseGzip: boolean,\n    wireProtocol?: wireProtocol,\n  ) => Promise<LLPlClient>;\n  private _ll?: LLPlClient;\n\n  private get ll(): LLPlClient {\n    if (this._ll === undefined) {\n      throw new Error(\"LLPlClient not initialized\");\n    }\n    return this._ll;\n  }\n\n  /** Stores client root (this abstraction is intended for future implementation of the security model) */\n  private _clientRoot: OptionalSignedResourceId = NullSignedResourceId;\n\n  private _userResources?: UserResources;\n\n  /** Cached effective role of the authenticated session, fetched once during\n   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)\n   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */\n  private _currentUserRole: Role | null = null;\n\n  private _txCommittedStat: TxStat = initialTxStat();\n  private _txConflictStat: TxStat = initialTxStat();\n  private _txErrorStat: TxStat = initialTxStat();\n\n  //\n  // Caching\n  //\n\n  /** This function determines whether resource data can be cached */\n  public readonly finalPredicate: FinalResourceDataPredicate;\n\n  /** Resource data cache, to minimize redundant data rereading from remote db */\n  private readonly resourceDataCache: LRUCache<SignedResourceId, ResourceDataCacheRecord>;\n\n  private constructor(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      finalPredicate?: FinalResourceDataPredicate;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const conf =\n      typeof configOrAddress === \"string\" ? plAddressToConfig(configOrAddress) : configOrAddress;\n\n    // An empty or whitespace-only asUser means \"no impersonation\"; normalize to undefined so a\n    // directly-constructed { asUser: \"\" } does not slip through as an empty login.\n    if (conf.asUser !== undefined && conf.asUser.trim() === \"\") conf.asUser = undefined;\n\n    // asUser (impersonation) and alternativeRoot both repoint the client root, so they cannot be\n    // combined. Validate here, before init() touches the network, so a misconfiguration fails fast.\n    if (conf.asUser !== undefined && conf.alternativeRoot !== undefined)\n      throw new Error(\"PlClient: asUser and alternativeRoot cannot be combined.\");\n\n    this.buildLLPlClient = async (\n      shouldUseGzip: boolean,\n      wireProtocol?: wireProtocol,\n    ): Promise<LLPlClient> => {\n      if (wireProtocol) conf.wireProtocol = wireProtocol;\n      return await LLPlClient.build(conf, { auth, ...ops, shouldUseGzip });\n    };\n\n    this.txDelay = conf.txDelay;\n    this.forceSync = conf.forceSync;\n    this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;\n    this.resourceDataCache = new LRUCache({\n      maxSize: conf.maxCacheBytes,\n      sizeCalculation: (v) => (v.basicData.data?.length ?? 0) + 64,\n    });\n    switch (conf.retryBackoffAlgorithm) {\n      case \"exponential\":\n        this.defaultRetryOptions = {\n          type: \"exponentialBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffMultiplier: conf.retryExponentialBackoffMultiplier,\n          jitter: conf.retryJitter,\n        };\n        break;\n      case \"linear\":\n        this.defaultRetryOptions = {\n          type: \"linearBackoff\",\n          initialDelay: conf.retryInitialDelay,\n          maxAttempts: conf.retryMaxAttempts,\n          backoffStep: conf.retryLinearBackoffStep,\n          jitter: conf.retryJitter,\n        };\n        break;\n      default:\n        assertNever(conf.retryBackoffAlgorithm);\n    }\n  }\n\n  public get txCommittedStat(): TxStat {\n    return { ...this._txCommittedStat };\n  }\n\n  public get txConflictStat(): TxStat {\n    return { ...this._txConflictStat };\n  }\n\n  public get txErrorStat(): TxStat {\n    return { ...this._txErrorStat };\n  }\n\n  public get txTotalStat(): TxStat {\n    return addStat(addStat(this._txCommittedStat, this._txConflictStat), this._txErrorStat);\n  }\n\n  public get allTxStat(): AllTxStat {\n    return {\n      committed: this.txCommittedStat,\n      conflict: this.txConflictStat,\n      error: this.txErrorStat,\n    };\n  }\n\n  public async ping(): Promise<MaintenanceAPI_Ping_Response> {\n    return await this.ll.ping();\n  }\n\n  public async license(): Promise<MaintenanceAPI_License_Response> {\n    return await this.ll.license();\n  }\n\n  /** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */\n  public async listUsers(): Promise<AuthAPI_User[]> {\n    return await this.ll.listUsers();\n  }\n\n  /**\n   * Returns the user root SignedResourceId via ListUserResources.\n   * @param opts.login - target user login; omit for the authenticated user.\n   * @returns SignedResourceId of the user root, or undefined if the server returned no userRoot entry.\n   * @throws if the backend does not implement ListUserResources (callers should catch with isUnimplementedError).\n   */\n  public async getUserRoot(opts: {\n    login?: string;\n    createIfNotExists: true;\n  }): Promise<SignedResourceId>;\n  public async getUserRoot(opts?: {\n    login?: string;\n    createIfNotExists?: boolean;\n  }): Promise<SignedResourceId | undefined>;\n  public async getUserRoot(\n    opts: { login?: string; createIfNotExists?: boolean } = {},\n  ): Promise<SignedResourceId | undefined> {\n    return this.userResources.getUserRoot(opts);\n  }\n\n  public get conf(): PlClientConfig {\n    return this.ll.conf;\n  }\n\n  public get httpDispatcher(): Dispatcher {\n    return this.ll.httpDispatcher;\n  }\n\n  public get connectionOpts(): WireConnection {\n    return this.ll.wireConnection;\n  }\n\n  private get initialized() {\n    return !isNullSignedResourceId(this._clientRoot);\n  }\n\n  private checkInitialized() {\n    if (!this.initialized) throw new Error(\"Client not initialized\");\n  }\n\n  public get clientRoot(): SignedResourceId {\n    this.checkInitialized();\n    return ensureSignedResourceIdNotNull(this._clientRoot);\n  }\n\n  public get serverInfo(): MaintenanceAPI_Ping_Response {\n    this.checkInitialized();\n    return this._ll!.serverInfo;\n  }\n\n  public hasCapability(capability: BackendCapability): boolean {\n    this.checkInitialized();\n    return this._ll!.hasCapability(capability);\n  }\n\n  /** Effective role of the authenticated session, resolved once during init via\n   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)\n   *  connection, or when the backend predates GetSessionInfo. Mirrors\n   *  {@link authUser}'s null contract. */\n  public get currentUserRole(): Role | null {\n    this.checkInitialized();\n    return this._currentUserRole;\n  }\n\n  /** Login of the authenticated user, or `null` for an anonymous connection. */\n  public get authUser(): string | null {\n    this.checkInitialized();\n    return this.userResources.authUser;\n  }\n\n  /**\n   * True if the backend honors per-file `permissions` on workdir fill rules.\n   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.\n   */\n  public get supportsWritableWorkdirFiles(): boolean {\n    this.checkInitialized();\n    return this._ll!.supportsWritableWorkdirFiles;\n  }\n\n  /** User resources index for discovering data libraries and other shared resources. */\n  public get userResources(): UserResources {\n    if (!this._ll) throw new Error(\"Client not initialized\");\n\n    if (!this._userResources) {\n      this._userResources = new UserResources(this._ll, this._withTx.bind(this), this._ll.authUser);\n    }\n\n    return this._userResources;\n  }\n\n  /** Discovers or creates the user's root resource via UserResources,\n   *  then handles alternativeRoot if configured. */\n  private async init() {\n    if (this.initialized) throw new Error(\"Already initialized\");\n\n    // Initial client is created without gzip to perform server ping and detect optimal wire protocol.\n    // LLPlClient.build() internally calls detectOptimalWireProtocol() which starts with default 'grpc',\n    // then retries with 'rest' if ping fails, alternating until a working protocol is found.\n    // We save the detected wireProtocol here because if the server supports gzip compression,\n    // we'll need to reinitialize the client with gzip enabled - passing the already-detected\n    // wireProtocol avoids redundant protocol detection on reinit.\n    this._ll = await this.buildLLPlClient(false);\n    const wireProtocol = this._ll.wireProtocol;\n\n    // LLPlClient.build() guarantees a successful ping; read the cached response instead of pinging again.\n    const info = this._ll.serverInfo;\n    if (info.compression === MaintenanceAPI_Ping_Response_Compression.GZIP) {\n      await this._ll.close();\n      this._ll = await this.buildLLPlClient(true, wireProtocol);\n    }\n\n    // Resolve the client root. Normally the caller's own root; when `asUser` is set (admin impersonation),\n    // the target user's root instead. The backend authorizes impersonation by role and silently returns the\n    // caller's own root for non-admins, so no client-side role gate is needed here.\n    let userRoot: SignedResourceId;\n    if (this.conf.asUser === undefined) {\n      userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });\n    } else {\n      const impersonatedRoot = await this.userResources.getUserRoot({ login: this.conf.asUser });\n      if (impersonatedRoot === undefined)\n        throw new Error(\n          `PlClient: cannot open root of user '${this.conf.asUser}': no root found (the user may have never logged in).`,\n        );\n      userRoot = impersonatedRoot;\n    }\n\n    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,\n    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,\n    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.\n    if (this.userResources.authUser !== null && this._ll.hasCapability(\"publicGrants:v1\")) {\n      this._currentUserRole = (await this._ll.getSessionInfo()).role;\n    }\n\n    if (this.conf.alternativeRoot === undefined) {\n      this._clientRoot = userRoot;\n    } else {\n      this._clientRoot = await this._withTx(\"initialization\", true, userRoot, async (tx) => {\n        const aFId = {\n          resourceId: userRoot,\n          fieldName: alternativeRootFieldName(this.conf.alternativeRoot!),\n        };\n\n        const altRoot = tx.createEphemeral(ClientRoot);\n        tx.lock(altRoot);\n        tx.createField(aFId, \"Dynamic\");\n        tx.setField(aFId, altRoot);\n        await tx.commit();\n\n        return await altRoot.globalId;\n      });\n    }\n  }\n\n  /** Returns true if field existed */\n  public async deleteAlternativeRoot(alternativeRootName: string): Promise<boolean> {\n    this.checkInitialized();\n    if (this.ll.conf.alternativeRoot !== undefined)\n      throw new Error(\"Initialized with alternative root.\");\n    return await this.withWriteTx(\"delete-alternative-root\", async (tx) => {\n      const fId = {\n        resourceId: tx.clientRoot,\n        fieldName: alternativeRootFieldName(alternativeRootName),\n      };\n      const exists = tx.fieldExists(fId);\n      tx.removeField(fId);\n      await tx.commit();\n      return await exists;\n    });\n  }\n\n  private async _withTx<T>(\n    name: string,\n    writable: boolean,\n    clientRoot: OptionalSignedResourceId,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops?: TxOps,\n  ): Promise<T> {\n    // for exponential / linear backoff\n    let retryState = createRetryState(ops?.retryOptions ?? this.defaultRetryOptions);\n\n    while (true) {\n      const release = ops?.lockId ? await advisoryLock(ops.lockId) : () => {};\n\n      try {\n        // opening low-level tx\n        const llTx = this.ll.createTx(writable, ops);\n        // wrapping it into high-level tx (this also asynchronously sends initialization message)\n        const tx = new PlTransaction(\n          llTx,\n          name,\n          writable,\n          clientRoot,\n          this.finalPredicate,\n          this.resourceDataCache,\n        );\n\n        // Auto-set default color proof from the client root's signature.\n        // Skip when backend doesn't implement the `set_default_color` TX request.\n        if (this.ll.supportsResourceSignatures && !isNullSignedResourceId(clientRoot) && writable) {\n          const parsed = parseSignedResourceId(clientRoot);\n          if (parsed.signature) {\n            tx.setDefaultColor(parsed.signature as ColorProof);\n          }\n        }\n\n        let ok = false;\n        let result: T | undefined = undefined;\n        let txId;\n\n        try {\n          // executing transaction body\n          result = await body(tx);\n          // collecting stat\n          this._txCommittedStat = addStat(this._txCommittedStat, tx.stat);\n          ok = true;\n        } catch (e: unknown) {\n          // the only recoverable\n          if (e instanceof TxCommitConflict) {\n            // ignoring\n            // collecting stat\n            this._txConflictStat = addStat(this._txConflictStat, tx.stat);\n          } else {\n            // collecting stat\n            this._txErrorStat = addStat(this._txErrorStat, tx.stat);\n            throw e;\n          }\n        } finally {\n          // close underlying grpc stream, if not yet done\n\n          // even though we can skip two lines below for read-only transactions,\n          // we don't do it to simplify reasoning about what is going on in\n          // concurrent code, especially in significant latency situations\n          await tx.complete();\n          await tx.await();\n\n          txId = await tx.getGlobalTxId();\n        }\n\n        if (ok) {\n          // syncing on transaction if requested\n          if (ops?.sync === undefined ? this.forceSync : ops?.sync) await this.ll.txSync(txId);\n\n          // introducing artificial delay, if requested\n          if (writable && this.txDelay > 0)\n            await tp.setTimeout(this.txDelay, undefined, { signal: ops?.abortSignal });\n\n          return result!;\n        }\n      } finally {\n        release();\n      }\n\n      // we only get here after TxCommitConflict error,\n      // all other errors terminate this loop instantly\n\n      await tp.setTimeout(retryState.nextDelay, undefined, { signal: ops?.abortSignal });\n      retryState = nextRetryStateOrError(retryState);\n    }\n  }\n\n  private async withTx<T>(\n    name: string,\n    writable: boolean,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, writable, this.clientRoot, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withWriteTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, true, body, { ...ops, ...defaultTxOps });\n  }\n\n  /**\n   * Runs a write transaction whose default color is `root`'s signature instead of the client\n   * root's, and whose `tx.clientRoot` is `root`. For admin cross-root operations (e.g. copying a\n   * project into another user's root so the copy is minted in that user's color). The backend\n   * still authorizes the write by role.\n   */\n  public async withWriteTxOnRoot<T>(\n    root: SignedResourceId,\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    this.checkInitialized();\n    return await this._withTx(name, true, root, body, { ...ops, ...defaultTxOps });\n  }\n\n  public async withReadTx<T>(\n    name: string,\n    body: (tx: PlTransaction) => Promise<T>,\n    ops: Partial<TxOps> = {},\n  ): Promise<T> {\n    return await this.withTx(name, false, body, { ...ops, ...defaultTxOps });\n  }\n\n  public getDriver<Drv extends PlDriver>(definition: PlDriverDefinition<Drv>): Drv {\n    const attached = this.drivers.get(definition.name);\n    if (attached !== undefined) return attached as Drv;\n    const driver = definition.init(this, this.ll, this.httpDispatcher);\n    this.drivers.set(definition.name, driver);\n    return driver;\n  }\n\n  /** Closes underlying transport */\n  public async close() {\n    await this.ll.close();\n  }\n\n  public static async init(\n    configOrAddress: PlClientConfig | string,\n    auth: AuthOps,\n    ops: {\n      statusListener?: PlConnectionStatusListener;\n      logger?: MiLogger;\n    } = {},\n  ) {\n    const pl = new PlClient(configOrAddress, auth, ops);\n    await pl.init();\n    return pl;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-client",
-  "version": "3.13.2",
+  "version": "3.14.1",
   "description": "New TS/JS client for Platform API",
   "files": [
     "./dist/**/*",
@@ -31,7 +31,7 @@
     "utility-types": "^3.11.0",
     "yaml": "^2.8.0",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-common": "1.46.4",
+    "@milaboratories/pl-model-common": "1.47.0",
     "@milaboratories/ts-helpers": "1.8.4"
   },
   "devDependencies": {

package/src/core/client.ts

@@ -18,6 +18,7 @@ import type { PlDriver, PlDriverDefinition } from "./driver";
 import type {
   MaintenanceAPI_Ping_Response,
   MaintenanceAPI_License_Response,
+  AuthAPI_User,
 } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import { MaintenanceAPI_Ping_Response_Compression } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import * as tp from "node:timers/promises";
@@ -192,6 +193,11 @@ export class PlClient {
     return await this.ll.license();
   }
 
+  /** Lists the users known to the server (login only on the wire). See {@link LLPlClient.listUsers}. */
+  public async listUsers(): Promise<AuthAPI_User[]> {
+    return await this.ll.listUsers();
+  }
+
   /**
    * Returns the user root SignedResourceId via ListUserResources.
    * @param opts.login - target user login; omit for the authenticated user.