@milaboratories/pl-client 2.16.13 → 2.16.15

package/src/core/client.ts

@@ -1,4 +1,4 @@
-import type { AuthOps, PlClientConfig, PlConnectionStatusListener } from './config';
+import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from './config';
 import type { PlCallOps } from './ll_client';
 import { LLPlClient } from './ll_client';
 import type { AnyResourceRef } from './transaction';
@@ -22,6 +22,7 @@ import type { AllTxStat, TxStat } from './stat';
 import { addStat, initialTxStat } from './stat';
 import type { WireConnection } from './wire';
 import { advisoryLock } from './advisory_locks';
+import { plAddressToConfig } from './config';
 
 export type TxOps = PlCallOps & {
   sync?: boolean;
@@ -54,8 +55,16 @@ export class PlClient {
   /** Last resort measure to solve complicated race conditions in pl. */
   private readonly defaultRetryOptions: RetryOptions;
 
-  private readonly buildLLPlClient: (shouldUseGzip: boolean) => LLPlClient;
-  private _ll: LLPlClient;
+  private readonly buildLLPlClient: (shouldUseGzip: boolean, wireProtocol?: wireProtocol) => Promise<LLPlClient>;
+  private _ll?: LLPlClient;
+
+  private get ll(): LLPlClient {
+    if (this._ll === undefined) {
+      throw new Error('LLPlClient not initialized');
+    }
+    return this._ll;
+  }
+
   /** Stores client root (this abstraction is intended for future implementation of the security model) */
   private _clientRoot: OptionalResourceId = NullResourceId;
 
@@ -83,12 +92,13 @@ export class PlClient {
       finalPredicate?: FinalResourceDataPredicate;
     } = {},
   ) {
-    // Will reinitialize client after getting available feature from server.
-    this.buildLLPlClient = (shouldUseGzip: boolean) => {
-      return new LLPlClient(configOrAddress, { auth, ...ops, shouldUseGzip });
+    const conf = typeof configOrAddress === 'string' ? plAddressToConfig(configOrAddress) : configOrAddress;
+
+    this.buildLLPlClient = async (shouldUseGzip: boolean, wireProtocol?: wireProtocol): Promise<LLPlClient> => {
+      if (wireProtocol) conf.wireProtocol = wireProtocol;
+      return await LLPlClient.build(conf, { auth, ...ops, shouldUseGzip });
     };
-    this._ll = this.buildLLPlClient(false);
-    const conf = this._ll.conf;
+
     this.txDelay = conf.txDelay;
     this.forceSync = conf.forceSync;
     this.finalPredicate = ops.finalPredicate ?? DefaultFinalResourceDataPredicate;
@@ -145,23 +155,23 @@ export class PlClient {
   }
 
   public async ping(): Promise<MaintenanceAPI_Ping_Response> {
-    return await this._ll.ping();
+    return await this.ll.ping();
   }
 
   public async license(): Promise<MaintenanceAPI_License_Response> {
-    return await this._ll.license();
+    return await this.ll.license();
   }
 
   public get conf(): PlClientConfig {
-    return this._ll.conf;
+    return this.ll.conf;
   }
 
   public get httpDispatcher(): Dispatcher {
-    return this._ll.httpDispatcher;
+    return this.ll.httpDispatcher;
   }
 
   public get connectionOpts(): WireConnection {
-    return this._ll.wireConnection;
+    return this.ll.wireConnection;
   }
 
   private get initialized() {
@@ -183,18 +193,27 @@ export class PlClient {
   }
 
   /** Currently implements custom logic to emulate future behaviour with single root. */
-  public async init() {
+  private async init() {
     if (this.initialized) throw new Error('Already initialized');
 
+    // Initial client is created without gzip to perform server ping and detect optimal wire protocol.
+    // LLPlClient.build() internally calls detectOptimalWireProtocol() which starts with default 'grpc',
+    // then retries with 'rest' if ping fails, alternating until a working protocol is found.
+    // We save the detected wireProtocol here because if the server supports gzip compression,
+    // we'll need to reinitialize the client with gzip enabled - passing the already-detected
+    // wireProtocol avoids redundant protocol detection on reinit.
+    this._ll = await this.buildLLPlClient(false);
+    const wireProtocol = this._ll.wireProtocol;
+
     // calculating reproducible root name from the username
     const user = this._ll.authUser;
     const mainRootName
-      = user === null ? AnonymousClientRoot : createHash('sha256').update(user).digest('hex');
+       = user === null ? AnonymousClientRoot : createHash('sha256').update(user).digest('hex');
 
     this._serverInfo = await this.ping();
     if (this._serverInfo.compression === MaintenanceAPI_Ping_Response_Compression.GZIP) {
       await this._ll.close();
-      this._ll = this.buildLLPlClient(true);
+      this._ll = await this.buildLLPlClient(true, wireProtocol);
     }
 
     this._clientRoot = await this._withTx('initialization', true, NullResourceId, async (tx) => {
@@ -230,7 +249,7 @@ export class PlClient {
   /** Returns true if field existed */
   public async deleteAlternativeRoot(alternativeRootName: string): Promise<boolean> {
     this.checkInitialized();
-    if (this._ll.conf.alternativeRoot !== undefined)
+    if (this.ll.conf.alternativeRoot !== undefined)
       throw new Error('Initialized with alternative root.');
     return await this.withWriteTx('delete-alternative-root', async (tx) => {
       const fId = {
@@ -259,7 +278,7 @@ export class PlClient {
 
       try {
         // opening low-level tx
-        const llTx = this._ll.createTx(writable, ops);
+        const llTx = this.ll.createTx(writable, ops);
         // wrapping it into high-level tx (this also asynchronously sends initialization message)
         const tx = new PlTransaction(
           llTx,
@@ -306,7 +325,7 @@ export class PlClient {
         if (ok) {
           // syncing on transaction if requested
           if (ops?.sync === undefined ? this.forceSync : ops?.sync)
-            await this._ll.txSync(txId);
+            await this.ll.txSync(txId);
 
           // introducing artificial delay, if requested
           if (writable && this.txDelay > 0)
@@ -355,14 +374,14 @@ export class PlClient {
   public getDriver<Drv extends PlDriver>(definition: PlDriverDefinition<Drv>): Drv {
     const attached = this.drivers.get(definition.name);
     if (attached !== undefined) return attached as Drv;
-    const driver = definition.init(this, this._ll, this.httpDispatcher);
+    const driver = definition.init(this, this.ll, this.httpDispatcher);
     this.drivers.set(definition.name, driver);
     return driver;
   }
 
   /** Closes underlying transport */
   public async close() {
-    await this._ll.close();
+    await this.ll.close();
   }
 
   public static async init(

package/src/core/default_client.ts

@@ -130,7 +130,7 @@ export async function defaultPlClient(): Promise<PlClient> {
   }
 
   if (authInformation === undefined) {
-    const client = new UnauthenticatedPlClient(config);
+    const client = await UnauthenticatedPlClient.build(config);
 
     if (await client.requireAuth()) {
       if (config.user === undefined || config.password === undefined)

package/src/core/errors.ts

@@ -5,47 +5,65 @@ import { Code } from '../proto-grpc/google/rpc/code';
 export function isConnectionProblem(err: unknown, nested: boolean = false): boolean {
   if (err instanceof DisconnectedError) return true;
   if ((err as any).name == 'RpcError' && (err as any).code == 'UNAVAILABLE') return true;
-  if ((err as any).code == Code.UNAVAILABLE) return true;
-  if ((err as any).cause !== undefined && !nested)
-    // nested limits the depth of search
-    return isConnectionProblem((err as any).cause, true);
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.UNAVAILABLE) return true;
+  if ((err as any).cause !== undefined && !nested) return isConnectionProblem((err as any).cause, true);
   return false;
 }
 
 export function isUnauthenticated(err: unknown, nested: boolean = false): boolean {
   if (err instanceof UnauthenticatedError) return true;
   if ((err as any).name == 'RpcError' && (err as any).code == 'UNAUTHENTICATED') return true;
-  if ((err as any).code == Code.UNAUTHENTICATED) return true;
-  if ((err as any).cause !== undefined && !nested)
-    // nested limits the depth of search
-    return isUnauthenticated((err as any).cause, true);
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.UNAUTHENTICATED) return true;
+  if ((err as any).cause !== undefined && !nested) return isUnauthenticated((err as any).cause, true);
   return false;
 }
 
-export function isTimeoutOrCancelError(err: unknown, nested: boolean = false): boolean {
-  if (err instanceof Aborted || (err as any).name == 'AbortError') return true;
+export function isTimeoutError(err: unknown, nested: boolean = false): boolean {
   if ((err as any).name == 'TimeoutError') return true;
+  if ((err as any).name == 'RpcError' && (err as any).code == 'DEADLINE_EXCEEDED') return true;
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.DEADLINE_EXCEEDED) return true;
+  if ((err as any).cause !== undefined && !nested) return isTimeoutError((err as any).cause, true);
+  return false;
+}
+
+export function isCancelError(err: unknown, nested: boolean = false): boolean {
+  if ((err as any).name == 'RpcError' && (err as any).code == 'CANCELLED') return true;
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.CANCELLED) return true;
+  if ((err as any).cause !== undefined && !nested) return isCancelError((err as any).cause, true);
+  return false;
+}
+
+export function isAbortedError(err: unknown, nested: boolean = false): boolean {
+  if (err instanceof Aborted || (err as any).name == 'AbortError') return true;
   if ((err as any).code == 'ABORT_ERR') return true;
-  if ((err as any).code == Code.ABORTED) return true;
-  if (
-    (err as any).name == 'RpcError'
-    && ((err as any).code == 'CANCELLED' || (err as any).code == 'DEADLINE_EXCEEDED')
-  )
-    return true;
-  if ((err as any).code == Code.CANCELLED || (err as any).code == Code.DEADLINE_EXCEEDED)
-    return true;
-  if ((err as any).cause !== undefined && !nested)
-    // nested limits the depth of search
-    return isTimeoutOrCancelError((err as any).cause, true);
+  if (err instanceof DOMException && err.code === DOMException.ABORT_ERR) return true; // WebSocket error
+  if ((err as any).name == 'RpcError' && (err as any).code == 'ABORTED') return true;
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.ABORTED) return true;
+  if ((err as any).cause !== undefined && !nested) isAbortedError((err as any).cause, true);
   return false;
 }
 
-export const PlErrorCodeNotFound = 5;
+export function isTimeoutOrCancelError(err: unknown, nested: boolean = false): boolean {
+  if (isAbortedError(err, true)) return true;
+  if (isTimeoutError(err, true)) return true;
+  if (isCancelError(err, true)) return true;
+  if ((err as any).cause !== undefined && !nested) return isTimeoutOrCancelError((err as any).cause, true);
+  return false;
+}
+
+export function isNotFoundError(err: unknown, nested: boolean = false): boolean {
+  if ((err as any).name == 'RpcError' && (err as any).code == 'NOT_FOUND') return true;
+  if ((err as any).name == 'RESTError' && (err as any).status.code == Code.NOT_FOUND) return true;
+  if ((err as any).cause !== undefined && !nested) return isNotFoundError((err as any).cause, true);
+  return err instanceof RecoverablePlError && err.status.code === PlErrorCodeNotFound;
+}
+
+export const PlErrorCodeNotFound: number = Code.NOT_FOUND;
 
 export class PlError extends Error {
   name = 'PlError';
-  constructor(public readonly status: Status) {
-    super(`code=${status.code} ${status.message}`);
+  constructor(public readonly status: Status, opts?: ErrorOptions) {
+    super(`code=${status.code} ${status.message}`, opts);
   }
 }
 
@@ -67,12 +85,6 @@ export class UnrecoverablePlError extends PlError {
   }
 }
 
-export function isNotFoundError(err: unknown, nested: boolean = false): boolean {
-  if ((err as any).name == 'RpcError' && (err as any).code == 'NOT_FOUND') return true;
-  if ((err as any).cause !== undefined && !nested) return isNotFoundError((err as any).cause, true);
-  return err instanceof RecoverablePlError && err.status.code === PlErrorCodeNotFound;
-}
-
 export class UnauthenticatedError extends Error {
   name = 'UnauthenticatedError';
   constructor(message: string) {
@@ -87,10 +99,25 @@ export class DisconnectedError extends Error {
   }
 }
 
+export class RESTError extends PlError {
+  name = 'RESTError';
+  constructor(status: Status, opts?: ErrorOptions) {
+    super(status, opts);
+  }
+}
+
 export function rethrowMeaningfulError(error: any, wrapIfUnknown: boolean = false): never {
-  if (isUnauthenticated(error)) throw new UnauthenticatedError(error.message);
-  if (isConnectionProblem(error)) throw new DisconnectedError(error.message);
+  if (isUnauthenticated(error)) {
+    if (error instanceof UnauthenticatedError) throw error;
+    throw new UnauthenticatedError(error.message);
+  }
+  if (isConnectionProblem(error)) {
+    if (error instanceof DisconnectedError) throw error;
+    throw new DisconnectedError(error.message);
+  }
   if (isTimeoutOrCancelError(error)) throw new Aborted(error);
-  if (wrapIfUnknown) throw new Error(error.message, { cause: error });
-  else throw error;
+  if (wrapIfUnknown) {
+    const message = error.message || String(error) || 'Unknown error';
+    throw new Error(message, { cause: error });
+  } else throw error;
 }

package/src/core/ll_client.test.ts

@@ -1,5 +1,5 @@
 import { LLPlClient } from './ll_client';
-import { getTestConfig, getTestLLClient, getTestClientConf } from '../test/test_config';
+import { getTestConfig, plAddressToTestConfig, getTestLLClient, getTestClientConf } from '../test/test_config';
 import { TxAPI_Open_Request_WritableTx } from '../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api';
 import { request } from 'undici';
 import * as tp from 'node:timers/promises';
@@ -7,6 +7,15 @@ import { test, expect } from 'vitest';
 
 import { UnauthenticatedError } from './errors';
 
+test('wire protocol detection', async () => {
+  const { conf, auth } = await getTestClientConf();
+  const expectedWireProtocol = conf.wireProtocol ?? 'grpc';
+  conf.wireProtocol = undefined;
+
+  const client = await LLPlClient.build(conf, { auth });
+  expect(client.wireProtocol).toBe(expectedWireProtocol);
+});
+
 test('authenticated instance test', async () => {
   const client = await getTestLLClient();
   const tx = client.createTx(true);
@@ -29,7 +38,7 @@ test('unauthenticated status change', async () => {
     return;
   }
 
-  const client = new LLPlClient(cfg.address);
+  const client = await LLPlClient.build(plAddressToTestConfig(cfg.address));
   expect(client.status).toBe('OK');
 
   const tx = client.createTx(true);
@@ -54,10 +63,16 @@ test('unauthenticated status change', async () => {
 });
 
 test('automatic token update', async () => {
+  const cfg = getTestConfig();
+  if (cfg.test_password === undefined) {
+    console.log("skipping test because target server doesn't support authentication");
+    return;
+  }
+
   const { conf, auth } = await getTestClientConf();
   conf.authMaxRefreshSeconds = 1;
   let numberOfAuthUpdates = 0;
-  const client = new LLPlClient(conf, {
+  const client = await LLPlClient.build(conf, {
     auth: {
       authInformation: auth.authInformation,
       onUpdate: (auth) => {

package/src/core/ll_client.ts

@@ -26,7 +26,7 @@ import type { WireClientProvider, WireClientProviderFactory, WireConnection } fr
 import { parseHttpAuth } from '@milaboratories/pl-model-common';
 import type * as grpcTypes from '../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api';
 import { type PlApiPaths, type PlRestClientType, createClient, parseResponseError } from '../proto-rest';
-import { notEmpty } from '@milaboratories/ts-helpers';
+import { notEmpty, retry, withTimeout, type RetryOptions } from '@milaboratories/ts-helpers';
 import { Code } from '../proto-grpc/google/rpc/code';
 import { WebSocketBiDiStream } from './websocket_stream';
 import { TxAPI_ClientMessage, TxAPI_ServerMessage } from '../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api';
@@ -54,8 +54,6 @@ class WireClientProviderImpl<Client> implements WireClientProvider<Client> {
 
 /** Abstract out low level networking and authorization details */
 export class LLPlClient implements WireClientProviderFactory {
-  public readonly conf: PlClientConfig;
-
   /** Initial authorization information */
   private authInformation?: AuthInformation;
   /** Will be executed by the client when it is required */
@@ -70,7 +68,7 @@ export class LLPlClient implements WireClientProviderFactory {
   private _status: PlConnectionStatus = 'OK';
   private readonly statusListener?: PlConnectionStatusListener;
 
-  private _wireProto: wireProtocol | undefined = undefined;
+  private _wireProto: wireProtocol = 'grpc';
   private _wireConn!: WireConnection;
 
   private readonly _restInterceptors: Dispatcher.DispatcherComposeInterceptor[];
@@ -82,18 +80,29 @@ export class LLPlClient implements WireClientProviderFactory {
 
   public readonly httpDispatcher: Dispatcher;
 
-  constructor(
+  public static async build(
     configOrAddress: PlClientConfig | string,
-    private readonly ops: {
+    ops: {
       auth?: AuthOps;
       statusListener?: PlConnectionStatusListener;
       shouldUseGzip?: boolean;
     } = {},
   ) {
-    this.conf = typeof configOrAddress === 'string'
-      ? plAddressToConfig(configOrAddress)
-      : configOrAddress;
+    const conf = typeof configOrAddress === 'string' ? plAddressToConfig(configOrAddress) : configOrAddress;
+
+    const pl = new LLPlClient(conf, ops);
+    await pl.detectOptimalWireProtocol();
+    return pl;
+  }
 
+  private constructor(
+    public readonly conf: PlClientConfig,
+    private readonly ops: {
+      auth?: AuthOps;
+      statusListener?: PlConnectionStatusListener;
+      shouldUseGzip?: boolean;
+    } = {},
+  ) {
     const { auth, statusListener } = ops;
 
     if (auth !== undefined) {
@@ -120,8 +129,11 @@ export class LLPlClient implements WireClientProviderFactory {
     this._grpcInterceptors.push(this.createGrpcErrorInterceptor());
 
     this.httpDispatcher = defaultHttpDispatcher(this.conf.httpProxy);
+    if (this.conf.wireProtocol) {
+      this._wireProto = this.conf.wireProtocol;
+    }
 
-    this.initWireConnection();
+    this.initWireConnection(this._wireProto);
 
     if (statusListener !== undefined) {
       this.statusListener = statusListener;
@@ -142,13 +154,8 @@ export class LLPlClient implements WireClientProviderFactory {
     });
   }
 
-  private initWireConnection() {
-    if (this._wireProto === undefined) {
-      // TODO: implement automatic server mode detection
-      this._wireProto = this.conf.wireProtocol ?? 'grpc';
-    }
-
-    switch (this._wireProto) {
+  private initWireConnection(protocol: wireProtocol) {
+    switch (protocol) {
       case 'rest':
         this.initRestConnection();
         return;
@@ -158,7 +165,7 @@ export class LLPlClient implements WireClientProviderFactory {
       default:
         ((v: never) => {
           throw new Error(`Unsupported wire protocol '${v as string}'. Use one of: ${SUPPORTED_WIRE_PROTOCOLS.join(', ')}`);
-        })(this._wireProto);
+        })(protocol);
     }
   }
 
@@ -221,6 +228,7 @@ export class LLPlClient implements WireClientProviderFactory {
   private _replaceWireConnection(newConn: WireConnection): void {
     const oldConn = this._wireConn;
     this._wireConn = newConn;
+    this._wireProto = newConn.type;
 
     // Reset all providers to let them reinitialize their clients
     for (let i = 0; i < this.providers.length; i++) {
@@ -269,6 +277,10 @@ export class LLPlClient implements WireClientProviderFactory {
     return this._wireConn;
   }
 
+  public get wireProtocol(): wireProtocol | undefined {
+    return this._wireProto;
+  }
+
   /** Returns true if client is authenticated. Even with anonymous auth information
    * connection is considered authenticated. Unauthenticated clients are used for
    * login and similar tasks, see {@link UnauthenticatedPlClient}. */
@@ -431,7 +443,7 @@ export class LLPlClient implements WireClientProviderFactory {
         body: { expiration: `${ttlSeconds}s` },
         headers,
       });
-      return notEmpty((await resp).data).token;
+      return notEmpty((await resp).data, 'REST: empty response for JWT token request').token;
     }
   }
 
@@ -440,8 +452,37 @@ export class LLPlClient implements WireClientProviderFactory {
     if (cl instanceof GrpcPlApiClient) {
       return (await cl.ping({})).response;
     } else {
-      return notEmpty((await cl.GET('/v1/ping')).data);
+      return notEmpty((await cl.GET('/v1/ping')).data, 'REST: empty response for ping request');
+    }
+  }
+
+  /**
+   * Detects the best available wire protocol.
+   * If wireProtocol is explicitly configured, does nothing.
+   * Otherwise probes the current protocol via ping; if it fails, switches to the alternative.
+   */
+  private async detectOptimalWireProtocol() {
+    if (this.conf.wireProtocol) {
+      return;
     }
+
+    const retryOptions: RetryOptions = {
+      type: 'exponentialBackoff',
+      maxAttempts: 80,
+      initialDelay: 30,
+      backoffMultiplier: 1.3,
+      jitter: 0.2,
+      maxDelay: 500,
+    };
+
+    await retry(
+      () => withTimeout(this.ping(), 500),
+      retryOptions,
+      () => {
+        const protocol = this._wireProto === 'grpc' ? 'rest' : 'grpc';
+        this.initWireConnection(protocol);
+        return true;
+      });
   }
 
   public async license(): Promise<grpcTypes.MaintenanceAPI_License_Response> {
@@ -449,7 +490,7 @@ export class LLPlClient implements WireClientProviderFactory {
     if (cl instanceof GrpcPlApiClient) {
       return (await cl.license({})).response;
     } else {
-      const resp = notEmpty((await cl.GET('/v1/license')).data);
+      const resp = notEmpty((await cl.GET('/v1/license')).data, 'REST: empty response for license request');
       return {
         status: resp.status,
         isOk: resp.isOk,
@@ -463,7 +504,7 @@ export class LLPlClient implements WireClientProviderFactory {
     if (cl instanceof GrpcPlApiClient) {
       return (await cl.authMethods({})).response;
     } else {
-      return notEmpty((await cl.GET('/v1/auth/methods')).data);
+      return notEmpty((await cl.GET('/v1/auth/methods')).data, 'REST: empty response for auth methods request');
     }
   }
 

package/src/core/unauth_client.test.ts

@@ -1,16 +1,16 @@
 import { UnauthenticatedPlClient } from './unauth_client';
-import { getTestConfig } from '../test/test_config';
+import { getTestConfig, plAddressToTestConfig } from '../test/test_config';
 import { UnauthenticatedError } from './errors';
 import { test, expect } from 'vitest';
 
 test('ping test', async () => {
-  const client = new UnauthenticatedPlClient(getTestConfig().address);
+  const client = await UnauthenticatedPlClient.build(plAddressToTestConfig(getTestConfig().address));
   const response = await client.ping();
   expect(response).toHaveProperty('coreVersion');
 });
 
 test('get auth methods', async () => {
-  const client = new UnauthenticatedPlClient(getTestConfig().address);
+  const client = await UnauthenticatedPlClient.build(plAddressToTestConfig(getTestConfig().address));
   const response = await client.authMethods();
   expect(response).toHaveProperty('methods');
 });
@@ -21,7 +21,7 @@ test('wrong login', async () => {
     console.log('skipped');
     return;
   }
-  const client = new UnauthenticatedPlClient(testConfig.address);
+  const client = await UnauthenticatedPlClient.build(plAddressToTestConfig(testConfig.address));
   await expect(client.login(testConfig.test_user, testConfig.test_password + 'A')).rejects.toThrow(
     UnauthenticatedError
   );

package/src/core/unauth_client.ts

@@ -11,8 +11,13 @@ import { UnauthenticatedError } from './errors';
 export class UnauthenticatedPlClient {
   public readonly ll: LLPlClient;
 
-  constructor(configOrAddress: PlClientConfig | string) {
-    this.ll = new LLPlClient(configOrAddress);
+  private constructor(ll: LLPlClient) {
+    this.ll = ll;
+  }
+
+  public static async build(configOrAddress: PlClientConfig | string): Promise<UnauthenticatedPlClient> {
+    const ll = await LLPlClient.build(configOrAddress);
+    return new UnauthenticatedPlClient(ll);
   }
 
   public async ping(): Promise<MaintenanceAPI_Ping_Response> {

package/src/core/websocket_stream.ts

@@ -3,6 +3,7 @@ import type { BiDiStream } from './abstract_stream';
 import Denque from 'denque';
 import type { RetryConfig } from '../helpers/retry_strategy';
 import { RetryStrategy } from '../helpers/retry_strategy';
+import { DisconnectedError } from './errors';
 
 interface QueuedMessage<InType extends object> {
   message: InType;
@@ -183,6 +184,18 @@ export class WebSocketBiDiStream<ClientMsg extends object, ServerMsg extends obj
   private onClose(): void {
     this.progressConnectionState(ConnectionState.CLOSED);
 
+    // If abort signal was triggered, use that as the error source
+    if (this.options.abortSignal?.aborted && !this.lastError) {
+      const reason = this.options.abortSignal.reason;
+      if (reason instanceof Error) {
+        this.lastError = reason;
+      } else if (reason !== undefined) {
+        this.lastError = new Error(String(reason), { cause: reason });
+      } else {
+        this.lastError = this.createStreamClosedError();
+      }
+    }
+
     if (!this.lastError) {
       this.rejectAllSendOperations(this.createStreamClosedError());
       this.resolveAllPendingResponses(); // unblock active async iterator
@@ -380,7 +393,15 @@ export class WebSocketBiDiStream<ClientMsg extends object, ServerMsg extends obj
 
   private toError(error: unknown): Error {
     if (error instanceof Error) return error;
-    if (error instanceof ErrorEvent) return error.error;
+    if (error instanceof ErrorEvent) {
+      const err = error.error;
+      // undici WebSocket throws TypeError with empty message on socket close
+      // (e.g., when connection is lost or server disconnects)
+      if (err instanceof TypeError && !err.message) {
+        return new DisconnectedError('WebSocket connection closed unexpectedly');
+      }
+      return err instanceof Error ? err : new Error('WebSocket error', { cause: error });
+    }
     return new Error(String(error));
   }
 

package/src/proto-rest/index.ts

@@ -7,7 +7,7 @@
 import type { paths as PlApiPaths } from './plapi';
 import { default as createOpenApiClient, type Middleware, type Client } from 'openapi-fetch';
 import { Dispatcher, fetch as undiciFetch } from 'undici';
-import { rethrowMeaningfulError } from '../core/errors';
+import { RESTError, rethrowMeaningfulError } from '../core/errors';
 import { Code } from '../proto-grpc/google/rpc/code';
 
 export { PlApiPaths };
@@ -92,7 +92,7 @@ function errorHandlerMiddleware(): Middleware {
         throw new Error(respErr.error);
       }
 
-      rethrowMeaningfulError(respErr.error);
+      rethrowMeaningfulError(new RESTError(respErr.error));
     },
   };
 }