@gohcltech/edge-print-client 1.0.29-develop → 2.0.40-develop

package/src/edge-print.ts

@@ -212,6 +212,14 @@ export interface ConnectOptions {
    * any other requests are accepted.
    */
   token: string
+  /**
+   * Name shown for this application in the agent's Clients tab and in the
+   * approval prompt the user sees when connecting with an unapproved token.
+   *
+   * Strongly recommended: without it the user is asked to trust an
+   * "Unknown client", which is not much of a decision.
+   */
+  clientName?: string
   /**
    * Maximum number of additional connection attempts after the first failure.
    * @default 3
@@ -249,6 +257,21 @@ type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void }
 export class EdgePrintClient {
   private ws: WebSocket | null = null
   private pending = new Map<string, Pending>()
+  /** Rejects the connect currently waiting on `onopen`, if there is one. */
+  private pendingOpen: ((e: Error) => void) | null = null
+  /** Bumped per connect, so a superseded one can tell it is no longer current. */
+  private connectGeneration = 0
+  /**
+   * Whether a connection currently exists from the application's point of view:
+   * a socket that opened *and* authenticated, and has not since gone away.
+   *
+   * Distinct from `authenticated`, which tracks one socket. This tracks whether
+   * there is anything for `onClose` to report the loss of, and is the single
+   * rule every teardown path consults — the alternative was each path deciding
+   * for itself, which is how the same event came to be announced in one place
+   * and swallowed in another.
+   */
+  private established = false
   private authenticated = false
   private closeListeners: Array<() => void> = []
 
@@ -259,6 +282,13 @@ export class EdgePrintClient {
    * waiting `options.retryDelay` ms (default 1 000) between attempts. If all
    * attempts fail the last error is re-thrown.
    *
+   * Calling this on an already-connected client **replaces** the connection:
+   * the existing socket is torn down before the new one is attempted, and its
+   * in-flight requests reject. If the new attempt then fails there is no
+   * connection left, and close listeners are notified. Guard a
+   * connect-on-demand helper with {@link EdgePrintClient.isConnected} rather
+   * than reconnecting unconditionally.
+   *
    * @throws {Error} If the agent is unreachable or the token is rejected after
    *   all retries are exhausted.
    *
@@ -278,18 +308,51 @@ export class EdgePrintClient {
       host = '127.0.0.1',
       port = 8181,
       token,
+      clientName,
       retries = 3,
       retryDelay = 1000,
     } = options
 
-    for (let attempt = 0; attempt <= retries; attempt++) {
+    // A negative count would skip the loop altogether and resolve without ever
+    // opening a socket, leaving the caller believing it is connected while
+    // every later call rejects with "Not connected".
+    const attempts = Math.max(0, retries)
+
+    const generation = ++this.connectGeneration
+
+    for (let attempt = 0; attempt <= attempts; attempt++) {
+      // Checked before every attempt, not only after a failed one. A connect
+      // sleeping between retries would otherwise wake and open a socket —
+      // discarding whatever connection was established while it slept, and
+      // reconnecting after an explicit disconnect.
+      if (this.connectGeneration !== generation) {
+        throw new Error('Connection superseded')
+      }
+
       try {
         await this.openSocket(`wss://${host}:${port}`)
-        await this.request('auth', { token })
+        // Omitted entirely when unset, rather than sent as undefined/null —
+        // the agent treats a missing key as "no name given".
+        await this.request('auth', clientName ? { token, clientName } : { token })
         this.authenticated = true
+        this.established = true
         return
       } catch (err) {
-        if (attempt === retries) throw err
+        // A newer connect has taken over since this attempt began. Its socket
+        // is not this attempt's to tear down.
+        if (this.connectGeneration !== generation) throw err
+
+        this.discardSocket(new Error('Connection closed'))
+
+        // Every failure retries, including a refused token. The agent answers a
+        // token still awaiting approval with the same "Invalid token" it gives
+        // a bad one, so the client cannot tell them apart — and retrying while
+        // someone clicks Approve is the documented flow. Repeat attempts only
+        // bump a counter on the pending entry; the notification fires once.
+        if (attempt === attempts) {
+          this.markClosed()
+          throw err
+        }
         await sleep(retryDelay)
       }
     }
@@ -331,7 +394,28 @@ export class EdgePrintClient {
    * @param data - One or more content items to print (pages, labels, …).
    * @returns The job ID assigned by the agent.
    *
-   * @throws {Error} If not connected, or if the agent rejects the job.
+   * @throws {Error} If not connected, if the agent rejects the job, or if the
+   *   job fails on the way to the spooler.
+   *
+   * A resolved promise means the job was handed to the OS print spooler — not
+   * that paper came out. A printer that is offline, jammed or out of paper
+   * after the spooler accepts the job still resolves.
+   *
+   * A rejection is also not proof that nothing printed: a request that exceeds
+   * the client's 30 s timeout rejects while the agent may still be spooling it.
+   * Do not resubmit a print automatically on rejection.
+   *
+   * When the agent had already created a job before it failed, the thrown error
+   * carries a `jobId` property matching the entry in the agent's job history —
+   * useful when surfacing a failure someone has to chase:
+   *
+   * ```ts
+   * try {
+   *   await ep.print(config, data)
+   * } catch (err) {
+   *   const jobId = (err as Error & { jobId?: string }).jobId
+   * }
+   * ```
    *
    * @example Print a PDF
    * ```ts
@@ -361,9 +445,17 @@ export class EdgePrintClient {
    * disconnected.
    */
   disconnect(): void {
-    this.ws?.close()
-    this.ws = null
-    this.authenticated = false
+    // Routed through the same teardown as a replacement: nulling the reference
+    // alone leaves the socket's handlers attached, and its close then arrives
+    // later and tears down whatever connection has taken its place.
+    // Invalidates any connect still running, so a retry cannot wake up after
+    // this and quietly reconnect.
+    this.connectGeneration++
+
+    this.discardSocket(new Error('Disconnected'))
+    // Detaching the handlers means the socket's own close never arrives, so
+    // without this the loss would go unannounced.
+    this.markClosed()
   }
 
   /**
@@ -382,31 +474,113 @@ export class EdgePrintClient {
    *
    * Multiple listeners can be registered; all are called in registration order.
    *
+   * @returns A function that removes this listener. Registering inside a
+   *   reconnect path without unsubscribing stacks a duplicate listener on every
+   *   attempt, so hold onto this if the caller can register more than once.
+   *
    * @example
    * ```ts
-   * ep.onClose(() => {
+   * const stop = ep.onClose(() => {
    *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
    *   reconnect()
    * })
+   *
+   * // later, e.g. when the component unmounts
+   * stop()
    * ```
    */
-  onClose(fn: () => void): void {
+  onClose(fn: () => void): () => void {
     this.closeListeners.push(fn)
+    return () => {
+      const i = this.closeListeners.indexOf(fn)
+      if (i !== -1) this.closeListeners.splice(i, 1)
+    }
   }
 
   // ── internals ────────────────────────────────────────────────────────────
 
+  /**
+   * Announces the loss of an established connection, exactly once.
+   *
+   * A socket that never authenticated was never a connection, so its going
+   * away is not something `onClose` reports — announcing it would have an
+   * onClose-driven reconnect racing the retry loop already running.
+   */
+  private markClosed(): void {
+    if (!this.established) return
+    this.established = false
+    // Copied: a listener may remove itself via the function onClose returns,
+    // and splicing the live array mid-iteration skips the next one.
+    ;[...this.closeListeners].forEach(fn => fn())
+  }
+
+  /**
+   * Tears down the current socket so it cannot reach this client again.
+   *
+   * Handlers are detached before closing, because the close event arrives in a
+   * later task — by which time the socket may have been replaced, and its
+   * `onclose` would otherwise report the *replacement* as disconnected.
+   *
+   * Detaching means the teardown that handler would have done has to happen
+   * here instead: clearing `authenticated`, settling in-flight requests, and
+   * settling a connect still waiting on `onopen`. That last one is easy to
+   * miss — a connect whose handlers are removed before either fires has
+   * nothing left to settle it, and `request()`'s timeout does not cover it, so
+   * it would wait forever.
+   *
+   * Close listeners are not fired from here. Whether a caller hears about a
+   * lost connection is `markClosed`'s decision, because only it knows whether
+   * there was an established connection to lose.
+   */
+  private discardSocket(reason: Error): void {
+    const ws = this.ws
+    const settleOpen = this.pendingOpen
+    this.ws = null
+    this.pendingOpen = null
+    this.authenticated = false
+
+    if (ws) {
+      ws.onopen = null
+      ws.onmessage = null
+      ws.onclose = null
+      ws.onerror = null
+      try { ws.close() } catch { /* already closing or closed */ }
+    }
+
+    settleOpen?.(reason)
+    this.rejectPending(reason)
+  }
+
   private openSocket(url: string): Promise<void> {
     return new Promise((resolve, reject) => {
+      // Never hold two sockets. This covers a retry, a reconnect on a live
+      // client, and a second connect racing the first.
+      this.discardSocket(new Error('Connection superseded'))
+
       const ws = new WebSocket(url)
-      ws.onopen = () => { this.ws = ws; resolve() }
-      ws.onerror = () => reject(new Error(`Cannot reach Edge Printing agent at ${url}`))
+      this.ws = ws
+      this.pendingOpen = reject
+
+      const settled = () => { this.pendingOpen = null }
+      ws.onopen = () => { settled(); resolve() }
+      ws.onerror = () => {
+        settled()
+        reject(new Error(`Cannot reach Edge Printing agent at ${url}`))
+      }
       ws.onmessage = (ev) => this.handleMessage(String(ev.data))
       ws.onclose = () => {
+        // A socket can close during the handshake, before either onopen or
+        // onerror fires. Clearing the pending open without settling it would
+        // leave this connect waiting forever — request()'s timeout does not
+        // cover the open.
+        const openWaiting = this.pendingOpen
+        settled()
+        openWaiting?.(new Error(`Cannot reach Edge Printing agent at ${url}`))
+
         this.ws = null
         this.authenticated = false
         this.rejectPending(new Error('Connection closed'))
-        this.closeListeners.forEach(fn => fn())
+        this.markClosed()
       }
     })
   }
@@ -421,8 +595,26 @@ export class EdgePrintClient {
     const { resolve, reject } = this.pending.get(id)!
     this.pending.delete(id)
 
-    if (msg['type'] === 'error') {
-      reject(new Error((msg['message'] as string) ?? 'Unknown error'))
+    // `error` means the request never became a job. `print_error` means a job
+    // was created and then failed — it carries a real jobId, which is why
+    // matching only on `error` let failed prints resolve as successes.
+    // Matched by suffix so error types added later reject by default rather
+    // than silently resolving.
+    const type = String(msg['type'] ?? '')
+    if (type === 'error' || type.endsWith('_error')) {
+      const failure = new Error((msg['message'] as string) ?? 'Unknown error')
+
+      // `print_error` carries the id of the job the agent created and then
+      // failed, which is the handle a caller needs to find it in the agent's
+      // job history. Attached rather than given an exported error type: the
+      // typed client error that formalises this arrives later, and a second
+      // error shape now would only have to be reconciled with it.
+      const jobId = msg['jobId']
+      if (typeof jobId === 'string' && jobId.length > 0) {
+        Object.assign(failure, { jobId })
+      }
+
+      reject(failure)
     } else {
       resolve(msg)
     }
@@ -435,23 +627,32 @@ export class EdgePrintClient {
         return
       }
       const id = crypto.randomUUID()
-      this.pending.set(id, { resolve, reject })
 
       const timeout = setTimeout(() => {
-        if (this.pending.has(id)) {
-          this.pending.delete(id)
+        if (this.pending.delete(id)) {
           reject(new Error(`Request "${type}" timed out`))
         }
       }, 30_000)
 
-      this.ws.send(JSON.stringify({ type, id, ...payload }))
-
-      // Wrap resolve/reject to also clear the timeout.
-      const original = this.pending.get(id)!
+      // Registered once, already wrapped. The previous version inserted the
+      // raw handlers, sent, then replaced the entry with wrapped ones that
+      // closed over what it read back out of the map. A close in that window
+      // made rejectPending clear the map first, so the replacement re-inserted
+      // an entry whose captured handlers were undefined — poisoning the map for
+      // the next rejectPending, which then threw mid-loop and left every later
+      // request unsettled.
       this.pending.set(id, {
-        resolve: (v) => { clearTimeout(timeout); original.resolve(v) },
-        reject: (e) => { clearTimeout(timeout); original.reject(e) },
+        resolve: (v) => { clearTimeout(timeout); resolve(v) },
+        reject: (e) => { clearTimeout(timeout); reject(e) },
       })
+
+      try {
+        this.ws.send(JSON.stringify({ type, id, ...payload }))
+      } catch (err) {
+        clearTimeout(timeout)
+        this.pending.delete(id)
+        reject(err instanceof Error ? err : new Error(String(err)))
+      }
     })
   }
 

package/tsconfig.json

@@ -9,5 +9,6 @@
     "strict": true,
     "lib": ["ES2020", "DOM"]
   },
-  "include": ["src/**/*.ts"]
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
 }

package/tsconfig.test.json

@@ -0,0 +1,16 @@
+// Typechecks the test suite, which the build config deliberately excludes so
+// test files never reach dist/. `vitest run` strips types without checking
+// them, so without this pass a signature change would neither fail the build
+// nor fail the tests.
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    // Skips vitest's and vite's own .d.ts files, which expect Node types this
+    // browser-targeted package does not carry. Only declaration files are
+    // skipped — the test is still checked in full against edge-print.ts.
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": []
+}