abb-rws-client 0.7.2 → 1.0.0

package/src/WsSubscriber.ts

@@ -0,0 +1,350 @@
+/**
+ * WsSubscriber — WebSocket subscription manager for ABB IRC5 RWS events.
+ *
+ * Flow:
+ *   1. POST /subscription via HttpSession to register resources → get subscription ID
+ *   2. Open WebSocket to ws://{host}/subscription/{id} with robapi2_subscription subprotocol
+ *   3. subscribe() resolves only once the WebSocket is open; if the socket errors or
+ *      closes before opening, subscribe() rejects and best-effort DELETEs the
+ *      registration so the controller-side subscription slot is not leaked
+ *   4. Parse incoming XML event messages → emit typed SubscriptionEvent objects
+ *   5. Auto-reconnect when an established stream drops: max 3 retries, exponential
+ *      backoff 1s/2s/4s
+ *
+ * Always connects through the 'ws' package: the RWS upgrade request must carry the
+ * session Cookie header, and native (undici) WebSocket has no headers option — it
+ * silently ignores the ws-style third constructor argument, so the handshake goes
+ * out unauthenticated. Live-verified 2026-07-08 against IRC5 RW6.16: native WS is
+ * rejected with HTTP 403, 'ws' with the same Cookie opens and delivers events.
+ */
+
+import { createRequire } from 'module';
+import type { HttpSession } from './HttpSession.js';
+import type { SubscriptionResource, SubscriptionEvent } from './types.js';
+import { RwsError } from './types.js';
+import { subscriptions } from './ResourceMapper.js';
+import { parseSubscriptionId } from './ResponseParser.js';
+
+const BACKOFF_MS = [1000, 2000, 4000] as const;
+const MAX_RETRIES = 3;
+
+/** WebSocket constructor shape used by WsSubscriber — ws-style options 3rd arg */
+type WebSocketCtor = new (
+  url: string,
+  protocols: string[],
+  options: { headers: Record<string, string> },
+) => WebSocket;
+
+/**
+ * Resolve the 'ws' package constructor. Never returns native globalThis.WebSocket —
+ * it cannot send the Cookie header the controller requires for WS auth.
+ */
+function resolveWebSocket(): WebSocketCtor {
+  try {
+    const require = createRequire(import.meta.url);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return require('ws') as any;
+  } catch {
+    throw new RwsError(
+      'The "ws" package is required for RWS 1.0 subscriptions but could not be loaded.',
+      'NETWORK_ERROR',
+    );
+  }
+}
+
+// ─── Path builder for subscription resources ─────────────────────────────────
+
+/**
+ * Map a SubscriptionResource to its RWS 1.0 event path (with ;state suffix where needed).
+ * Paths are NOT percent-encoded — semicolons must be literal in the subscription body.
+ */
+function resourceToPath(resource: SubscriptionResource): string {
+  if (resource === 'execution')     return '/rw/rapid/execution;ctrlexecstate';
+  if (resource === 'controllerstate') return '/rw/panel/ctrlstate;ctrlstate';
+  if (resource === 'operationmode') return '/rw/panel/opmode;opmode';
+  if (resource === 'speedratio')    return '/rw/panel/speedratio;speedratio';
+  if (resource === 'coldetstate')   return '/rw/panel/coldetstate;coldetstate';
+  if (resource === 'uiinstr')       return '/rw/rapid/uiinstr;uievent';
+  if (resource.type === 'signal') {
+    // Convention: name can be 'network/device/signalname' (3 parts) for a physical signal,
+    // or just 'signalname' for virtual/flat signals.
+    return `/rw/iosystem/signals/${resource.name};state`;
+  }
+  if (resource.type === 'persvar') {
+    // RAPID persistent variable subscription path (full path: RAPID/task/module/symbol)
+    return `/rw/rapid/symbol/data/${resource.name};value`;
+  }
+  if (resource.type === 'taskchange') {
+    return `/rw/rapid/tasks/${encodeURIComponent(resource.task)};taskchange`;
+  }
+  if (resource.type === 'execycle') {
+    return '/rw/rapid/execution;rapidexeccycle';
+  }
+  if (resource.type === 'elog') {
+    return `/rw/elog/${resource.domain}`;
+  }
+  // TypeScript exhaustiveness check
+  const _: never = resource;
+  void _;
+  throw new RwsError('Unknown subscription resource type', 'UNKNOWN');
+}
+
+/**
+ * Build the application/x-www-form-urlencoded body for POST /subscription.
+ * Paths are NOT percent-encoded; the semicolons are literal as expected by RWS.
+ */
+function buildSubscriptionBody(resources: SubscriptionResource[]): string {
+  const parts: string[] = [`resources=${resources.length}`];
+  resources.forEach((resource, index) => {
+    const i = index + 1;
+    const path = resourceToPath(resource);
+    // Do NOT encodeURIComponent the path — RWS expects literal semicolons
+    parts.push(`${i}=${path}&${i}-p=1`);
+  });
+  return parts.join('&');
+}
+
+// ─── XML event parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse an incoming RWS WebSocket XML event message.
+ * Expected structure (simplified):
+ *   <html><body><div class="bind-data"><ul>
+ *     <li class="..."><a href="/rw/rapid/execution;state">...</a>
+ *       <span class="excstate">running</span>
+ *     </li>
+ *   </ul></div></body></html>
+ */
+function parseWsMessage(data: string): SubscriptionEvent[] {
+  const events: SubscriptionEvent[] = [];
+
+  // Extract all <li> blocks in the message
+  const liPattern = /<li[^>]*>(.*?)<\/li>/gis;
+  let liMatch: RegExpExecArray | null;
+
+  while ((liMatch = liPattern.exec(data)) !== null) {
+    const block = liMatch[1];
+
+    // Extract resource URL from the <a href="..."> anchor
+    const hrefMatch = block.match(/<a[^>]*href="([^"]+)"/i);
+    if (!hrefMatch) continue;
+    const resource = hrefMatch[1];
+
+    // Extract value from the first <span> in this block
+    const spanMatch = block.match(/<span[^>]*>(.*?)<\/span>/is);
+    const value = spanMatch ? spanMatch[1].trim() : '';
+
+    events.push({ resource, value, timestamp: new Date() });
+  }
+
+  return events;
+}
+
+// ─── WsSubscriber ─────────────────────────────────────────────────────────────
+
+interface ActiveSubscription {
+  id: string;
+  wsUrl: string;
+  deleteUrl: string;  // HTTP URL used to DELETE the subscription on close
+  ws: WebSocket | null;
+  handler: (event: SubscriptionEvent) => void;
+  retryCount: number;
+  closed: boolean;
+}
+
+export class WsSubscriber {
+  private readonly session: HttpSession;
+  private readonly host: string;
+  private readonly port: number;
+  private readonly wsCtor: WebSocketCtor | undefined;
+  private subscriptions: Map<string, ActiveSubscription> = new Map();
+
+  constructor(session: HttpSession, host: string, port: number, wsCtor?: WebSocketCtor) {
+    this.session = session;
+    this.host = host;
+    this.port = port;
+    this.wsCtor = wsCtor;
+  }
+
+  /**
+   * Subscribe to one or more RWS resources. Returns an unsubscribe function.
+   *
+   * Resolves only once the event WebSocket is open. If the socket fails before
+   * opening (refused connection, failed upgrade), rejects with RwsError after
+   * best-effort deleting the subscription registered by the POST — otherwise the
+   * caller believes it has live events while the controller streams to nobody.
+   *
+   * @param resources - Array of resources to subscribe to
+   * @param handler   - Called for each incoming event
+   * @returns         - Async function that cancels the subscription and closes the WebSocket
+   */
+  async subscribe(
+    resources: SubscriptionResource[],
+    handler: (event: SubscriptionEvent) => void,
+  ): Promise<() => Promise<void>> {
+    // Step 1: POST /subscription to register resources
+    const body = buildSubscriptionBody(resources);
+    const response = await this.session.post(subscriptions(), body);
+
+    if (response.status !== 201) {
+      throw new RwsError(
+        `Subscription POST returned ${response.status}, expected 201`,
+        'UNKNOWN',
+        response.status,
+      );
+    }
+
+    const locationHeader = response.headers.get('location');
+    if (!locationHeader) {
+      throw new RwsError('Subscription POST missing Location header', 'UNKNOWN');
+    }
+
+    const subscriptionId = parseSubscriptionId(locationHeader);
+
+    // Step 2: Derive WebSocket URL and HTTP delete URL from Location header.
+    // IRC5 may return ws://host/poll/{id} or http://host/subscription/{id} or a path.
+    let wsUrl: string;
+    let deleteUrl: string;
+    if (locationHeader.startsWith('ws://') || locationHeader.startsWith('wss://')) {
+      wsUrl = locationHeader;
+      deleteUrl = locationHeader.replace(/^ws:/, 'http:').replace(/^wss:/, 'https:');
+    } else if (locationHeader.startsWith('http://') || locationHeader.startsWith('https://')) {
+      wsUrl = locationHeader.replace(/^http:/, 'ws:').replace(/^https:/, 'wss:');
+      deleteUrl = locationHeader;
+    } else {
+      wsUrl = `ws://${this.host}:${this.port}${locationHeader}`;
+      deleteUrl = `http://${this.host}:${this.port}${locationHeader}`;
+    }
+
+    const sub: ActiveSubscription = {
+      id: subscriptionId,
+      wsUrl,
+      deleteUrl,
+      ws: null,
+      handler,
+      retryCount: 0,
+      closed: false,
+    };
+
+    this.subscriptions.set(subscriptionId, sub);
+
+    // Step 3: open the WebSocket and wait for it — a subscription without a live
+    // event stream is worse than no subscription (silent staleness).
+    try {
+      await this.openWebSocket(sub);
+    } catch (err) {
+      sub.closed = true;
+      sub.ws = null;
+      this.subscriptions.delete(subscriptionId);
+      // Free the controller-side slot registered by the POST — best-effort
+      await this.session.delete(sub.deleteUrl).catch(() => undefined);
+      throw err;
+    }
+
+    // Return unsubscribe function
+    return async () => {
+      sub.closed = true;
+      if (sub.ws) {
+        sub.ws.close();
+        sub.ws = null;
+      }
+      this.subscriptions.delete(subscriptionId);
+      // Best-effort DELETE — ignore errors (controller may have already cleaned up)
+      await this.session.delete(sub.deleteUrl).catch(() => undefined);
+    };
+  }
+
+  /** Close all active subscriptions */
+  async closeAll(): Promise<void> {
+    const promises: Promise<void>[] = [];
+    for (const sub of this.subscriptions.values()) {
+      sub.closed = true;
+      if (sub.ws) {
+        sub.ws.close();
+        sub.ws = null;
+      }
+      promises.push(
+        this.session.delete(sub.deleteUrl).then(() => undefined).catch(() => undefined),
+      );
+    }
+    this.subscriptions.clear();
+    await Promise.allSettled(promises);
+  }
+
+  // ─── WebSocket lifecycle ────────────────────────────────────────────────────
+
+  /**
+   * Open the event WebSocket for a subscription. Resolves once the socket is
+   * open; rejects if it errors or closes before ever opening (refused connection,
+   * rejected upgrade). Reconnect handling for established streams lives in the
+   * close handler, so callers of reconnect attempts must catch rejections.
+   */
+  private openWebSocket(sub: ActiveSubscription): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const cookieHeader = this.session.getCookieHeader();
+      const WS = this.wsCtor ?? resolveWebSocket();
+      const ws = new WS(sub.wsUrl, ['robapi2_subscription'], {
+        headers: { Cookie: cookieHeader },
+      });
+
+      sub.ws = ws;
+      let opened = false;
+
+      const failBeforeOpen = (): void => {
+        reject(new RwsError(
+          `WebSocket for subscription ${sub.id} failed before opening`,
+          'NETWORK_ERROR',
+        ));
+      };
+
+      ws.onopen = (): void => {
+        opened = true;
+        sub.retryCount = 0;
+        resolve();
+      };
+
+      ws.onmessage = (event: MessageEvent): void => {
+        try {
+          const data = typeof event.data === 'string' ? event.data : String(event.data);
+          const events = parseWsMessage(data);
+          for (const e of events) {
+            sub.handler(e);
+          }
+        } catch {
+          // Silently discard unparseable messages — don't crash the subscriber
+        }
+      };
+
+      ws.onerror = (): void => {
+        // Post-open errors are followed by onclose; reconnect logic lives there
+        if (!opened) failBeforeOpen();
+      };
+
+      ws.onclose = (event: Event & { wasClean?: boolean }): void => {
+        if (!opened) {
+          // Never established — reject and let the caller decide (subscribe
+          // deletes the registration; reconnect attempts consume a retry)
+          failBeforeOpen();
+          return;
+        }
+        if (sub.closed) return; // intentional close — do not reconnect
+
+        if (!event.wasClean) {
+          this.scheduleReconnect(sub);
+        }
+      };
+    });
+  }
+
+  /** Reconnect a lost (previously open) stream with backoff; gives up after MAX_RETRIES. */
+  private scheduleReconnect(sub: ActiveSubscription): void {
+    if (sub.closed || sub.retryCount >= MAX_RETRIES) return;
+    const delay = BACKOFF_MS[sub.retryCount] ?? BACKOFF_MS[BACKOFF_MS.length - 1];
+    sub.retryCount++;
+    setTimeout(() => {
+      if (sub.closed) return;
+      // A reconnect attempt that fails before opening consumes a retry and tries again
+      this.openWebSocket(sub).catch(() => this.scheduleReconnect(sub));
+    }, delay);
+  }
+}

package/src/XhtmlParser.ts

@@ -0,0 +1,53 @@
+/**
+ * Lightweight regex-based XHTML parser for ABB RWS 2.0 responses.
+ * RWS 2.0 returns application/xhtml+xml;v=2.0 for all endpoints.
+ * Data lives in <li class="TYPE"> elements containing <span class="FIELD">VALUE</span> nodes.
+ */
+export class XhtmlParser {
+  constructor(private readonly html: string) {}
+
+  /** Returns span-value map from the first <li class="liClass"> in the document. */
+  getState(liClass: string): Record<string, string> {
+    return this.getAllStates(liClass)[0] ?? {};
+  }
+
+  /** Returns an array of span-value maps, one per <li class="liClass"> in the document. */
+  getAllStates(liClass: string): Array<Record<string, string>> {
+    const results: Array<Record<string, string>> = [];
+    const liRe = new RegExp(`<li class="${liClass}"([^>]*)>([\\s\\S]*?)</li>`, 'g');
+    for (const m of this.html.matchAll(liRe)) {
+      const attrs = m[1];
+      const inner = m[2];
+      const fields: Record<string, string> = {};
+
+      const titleM = attrs.match(/title="([^"]*)"/);
+      if (titleM) { fields['_title'] = titleM[1]; }
+
+      // href with rel="self" — stores the resource path (used for signal network/device)
+      const hrefM = inner.match(/href="([^"]*?)" rel="self"/);
+      if (hrefM) { fields['_href'] = hrefM[1]; }
+
+      for (const [, cls, val] of inner.matchAll(/<span class="([^"]+)">([^<]*)<\/span>/g)) {
+        fields[cls] = val;
+      }
+      results.push(fields);
+    }
+    return results;
+  }
+
+  /** Extracts a single span value from anywhere in the document. */
+  get(spanClass: string): string | undefined {
+    return this.html.match(new RegExp(`<span class="${spanClass}">([^<]*)<\\/span>`))?.[1];
+  }
+
+  /**
+   * Returns error details if the response contains an ABB error status block.
+   * Error pattern: <span class="code">-1073445862</span><span class="msg">...</span>
+   */
+  getError(): { code: string; msg: string } | null {
+    const codeM = this.html.match(/<span class="code">(-\d+)<\/span>/);
+    if (!codeM) { return null; }
+    const msgM = this.html.match(/<span class="msg">([^<]*)<\/span>/);
+    return { code: codeM[1], msg: msgM?.[1] ?? '' };
+  }
+}

package/src/detect.ts

@@ -0,0 +1,261 @@
+import * as https from 'https';
+import * as http from 'http';
+import { RwsClient } from './RwsClient.js';
+import { RwsClient2 } from './RwsClient2.js';
+import { RWS1Adapter } from './RWS1Adapter.js';
+import { RWS2Adapter } from './RWS2Adapter.js';
+import { RwsError } from './types.js';
+import type { IRWSAdapter } from './IRWSAdapter.js';
+
+export type AnyClient = RwsClient | RwsClient2;
+export type Protocol = 'rws1' | 'rws2';
+
+export interface ConnectOptions {
+  /** Hostname or IP, e.g. '192.168.125.1' or '127.0.0.1'. */
+  host: string;
+  /** TCP port. If omitted, common ports are probed (5466, 9403, 443 https; 80, 11811 http). */
+  port?: number;
+  /** Force the transport scheme. If omitted, inferred from port (443, 5466, 9403 → https). */
+  https?: boolean;
+  /** Default 'Admin'. */
+  username?: string;
+  /** Default 'robotics'. */
+  password?: string;
+  /** Per-request timeout in ms. Default 5000. */
+  timeout?: number;
+  /**
+   * Verify TLS certificates. Default false — ABB controllers (virtual and
+   * real) ship self-signed certs, so verification stays off unless the
+   * deployment has a CA-signed cert on the controller. Applies to the probe
+   * requests and to the RWS 2.0 client this factory constructs.
+   * Live-verified 2026-07-09: strict probe rejects the OmniCore VC's
+   * self-signed cert (RW7.21); default detects it; plain-HTTP IRC5 unaffected.
+   */
+  strictTls?: boolean;
+}
+
+export interface ProbeResult {
+  protocol: Protocol;
+  port: number;
+  https: boolean;
+}
+
+/**
+ * Probe a single host:port and return which RWS protocol it speaks, or null if
+ * neither. Reads the WWW-Authenticate header on a 401:
+ *   - "Digest …"  → RWS 1.0
+ *   - "Basic …"   → RWS 2.0
+ */
+export async function probeProtocol(
+  host: string,
+  port: number,
+  useHttps: boolean,
+  timeoutMs = 3000,
+  strictTls = false,
+): Promise<Protocol | null> {
+  return new Promise(resolve => {
+    const insecure = useHttps && !strictTls;
+    const agent = insecure ? new https.Agent({ rejectUnauthorized: false }) : undefined;
+    const options: http.RequestOptions & { agent?: https.Agent; rejectUnauthorized?: boolean } = {
+      method: 'GET',
+      hostname: host,
+      port,
+      path: '/rw/system',
+      headers: { Accept: 'application/xhtml+xml;v=2.0' },
+      agent,
+      // Per-request as well as on the agent: agent-swapping hosts (VS Code extension
+      // host on non-localhost targets) otherwise re-enable TLS verification (issue #2).
+      // Under strictTls neither is set, so certs verify normally.
+      ...(insecure ? { rejectUnauthorized: false } : {}),
+    };
+    const transport = useHttps ? https : http;
+    const req = (transport as typeof https).request(options as https.RequestOptions, res => {
+      const auth = (res.headers['www-authenticate'] || '').toString().toLowerCase();
+      // Drain the body so the socket can return to the pool.
+      res.on('data', () => {});
+      res.on('end', () => {
+        if (auth.startsWith('digest ')) { resolve('rws1'); return; }
+        if (auth.startsWith('basic '))  { resolve('rws2'); return; }
+        // No Digest/Basic challenge → not an RWS controller. Anything else that
+        // answers /rw/system (Bearer-protected services, random web servers,
+        // captive portals) used to be misreported as rws2, sending connect
+        // attempts at hosts that will never speak the protocol. Controllers
+        // always challenge an unauthenticated probe, so there is no legitimate
+        // challenge-less case to allow.
+        resolve(null);
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+/**
+ * Probe common RWS ports on a host and return the first one that answers.
+ * Order favors known defaults: 5466 (OmniCore VC HTTPS), 9403 (alt OmniCore),
+ * 443 (real OmniCore), 80 (real IRC5 HTTP), 11811 (legacy IRC5 VC).
+ */
+export async function probeHost(host: string, timeoutMs = 1500, strictTls = false): Promise<ProbeResult | null> {
+  const candidates: Array<[number, boolean]> = [
+    [5466,  true ],
+    [9403,  true ],
+    [443,   true ],
+    [80,    false],
+    [11811, false],
+  ];
+  for (const [port, https] of candidates) {
+    const proto = await probeProtocol(host, port, https, timeoutMs, strictTls);
+    if (proto) { return { protocol: proto, port, https }; }
+  }
+  return null;
+}
+
+/**
+ * True when the failure is a credential rejection, in either protocol's flavor:
+ * RwsClient throws RwsError code='AUTH_FAILED' (message has no "401"), RwsClient2
+ * throws a plain Error with the HTTP status in the message.
+ */
+function isAuthRejection(err: unknown): boolean {
+  if (err instanceof RwsError) { return err.code === 'AUTH_FAILED'; }
+  return /401|unauthor/i.test(String(err));
+}
+
+/**
+ * Probe a controller's auth scheme and return the matching protocol-level client,
+ * already connected. The returned client is either an `RwsClient` (RWS 1.0) or
+ * `RwsClient2` (RWS 2.0); use `client instanceof RwsClient2` (or check `protocol`)
+ * to narrow if you need protocol-specific behavior.
+ *
+ * @throws RwsError code='PROTOCOL_DETECT_FAILED' when neither auth scheme is detected.
+ */
+export async function createClient(opts: ConnectOptions): Promise<AnyClient> {
+  const { host, username = 'Admin', password = 'robotics', timeout = 5000 } = opts;
+  const strictTls = opts.strictTls === true;
+
+  let port = opts.port;
+  let useHttps = opts.https;
+  let protocol: Protocol;
+
+  if (port === undefined) {
+    const probe = await probeHost(host, opts.timeout, strictTls);
+    if (!probe) {
+      throw new RwsError(`No RWS endpoint found on ${host} — tried ports 5466, 9403, 443, 80, 11811`, 'PROTOCOL_DETECT_FAILED');
+    }
+    port = probe.port;
+    useHttps = probe.https;
+    protocol = probe.protocol;
+  } else {
+    if (useHttps === undefined) { useHttps = port === 443 || port === 5466 || port === 9403; }
+    const detected = await probeProtocol(host, port, useHttps, opts.timeout, strictTls);
+    if (!detected) {
+      throw new RwsError(`No RWS auth challenge from ${host}:${port} — controller may be off, wrong port, or non-RWS service`, 'PROTOCOL_DETECT_FAILED');
+    }
+    protocol = detected;
+  }
+
+  // RWS 1.0 (IRC5) ships with `Default User`; `Admin` may not exist or have
+  // different password. RWS 2.0 (OmniCore) typically has both. So when the
+  // caller didn't pin a username and connect fails on `Admin`, transparently
+  // retry with `Default User` so cross-controller code "just works."
+  const fallbackUser = opts.username === undefined && username === 'Admin'
+    ? 'Default User'
+    : null;
+
+  if (protocol === 'rws1') {
+    try {
+      const c = new RwsClient({ host, port, username, password, timeout });
+      await c.connect();
+      return c;
+    } catch (err) {
+      if (fallbackUser && isAuthRejection(err)) {
+        const c = new RwsClient({ host, port, username: fallbackUser, password, timeout });
+        await c.connect();
+        return c;
+      }
+      throw err;
+    }
+  } else {
+    const scheme = useHttps ? 'https' : 'http';
+    const clientOpts = { timeout, rejectUnauthorized: strictTls };
+    try {
+      const c = new RwsClient2(`${scheme}://${host}:${port}`, username, password, clientOpts);
+      await c.connect();
+      return c;
+    } catch (err) {
+      if (fallbackUser && isAuthRejection(err)) {
+        const c = new RwsClient2(`${scheme}://${host}:${port}`, fallbackUser, password, clientOpts);
+        await c.connect();
+        return c;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Like `createClient` but returns the unified-interface adapter (`IRWSAdapter`).
+ * Use this when you want to hold a single typed reference across both protocols
+ * — e.g. if you write code that calls `.getControllerState()` etc. without
+ * caring whether the underlying transport is 1.0 or 2.0.
+ */
+export async function createAdapter(opts: ConnectOptions): Promise<IRWSAdapter> {
+  const { host, username = 'Admin', password = 'robotics', timeout = 5000 } = opts;
+  const strictTls = opts.strictTls === true;
+
+  let port = opts.port;
+  let useHttps = opts.https;
+  let protocol: Protocol;
+
+  if (port === undefined) {
+    const probe = await probeHost(host, opts.timeout, strictTls);
+    if (!probe) {
+      throw new RwsError(`No RWS endpoint found on ${host}`, 'PROTOCOL_DETECT_FAILED');
+    }
+    port = probe.port;
+    useHttps = probe.https;
+    protocol = probe.protocol;
+  } else {
+    if (useHttps === undefined) { useHttps = port === 443 || port === 5466 || port === 9403; }
+    const detected = await probeProtocol(host, port, useHttps, opts.timeout, strictTls);
+    if (!detected) {
+      throw new RwsError(`No RWS auth challenge from ${host}:${port}`, 'PROTOCOL_DETECT_FAILED');
+    }
+    protocol = detected;
+  }
+
+  // Same `Default User` retry as createClient — see the comment there.
+  const fallbackUser = opts.username === undefined && username === 'Admin'
+    ? 'Default User'
+    : null;
+
+  if (protocol === 'rws1') {
+    try {
+      const inner = new RwsClient({ host, port, username, password, timeout });
+      await inner.connect();
+      return new RWS1Adapter(inner, { host, port, username, password });
+    } catch (err) {
+      if (fallbackUser && isAuthRejection(err)) {
+        const inner = new RwsClient({ host, port, username: fallbackUser, password, timeout });
+        await inner.connect();
+        return new RWS1Adapter(inner, { host, port, username: fallbackUser, password });
+      }
+      throw err;
+    }
+  } else {
+    const scheme = useHttps ? 'https' : 'http';
+    const clientOpts = { timeout, rejectUnauthorized: strictTls };
+    try {
+      const a = new RWS2Adapter(`${scheme}://${host}:${port}`, username, password, clientOpts);
+      await a.connect();
+      return a;
+    } catch (err) {
+      if (fallbackUser && isAuthRejection(err)) {
+        const a = new RWS2Adapter(`${scheme}://${host}:${port}`, fallbackUser, password, clientOpts);
+        await a.connect();
+        return a;
+      }
+      throw err;
+    }
+  }
+}