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

package/src/edge-print.test.ts

@@ -0,0 +1,680 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { EdgePrintClient, type ConnectOptions, type PrintData } from './edge-print'
+
+/**
+ * Minimal stand-in for the browser WebSocket.
+ *
+ * Only the surface the client actually touches: the four handler properties,
+ * `send`, and the static `OPEN`. `onopen` fires in a microtask so the client
+ * has assigned its handlers by the time it runs, matching the real ordering.
+ */
+class FakeWebSocket {
+  static OPEN = 1
+  static instances: FakeWebSocket[] = []
+
+  readyState = FakeWebSocket.OPEN
+  sent: string[] = []
+
+  onopen: (() => void) | null = null
+  onmessage: ((ev: { data: string }) => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: (() => void) | null = null
+
+  /**
+   * Fires `onclose` re-entrantly from inside `send`.
+   *
+   * A real WebSocket never does this — `send` returns synchronously and close
+   * is dispatched in a later task — so this is a deliberately synthetic worst
+   * case. It exists to pin the invariant that a close arriving at any point
+   * around a send settles the request and leaves the pending map empty, rather
+   * than to reproduce a browser-reachable ordering.
+   */
+  closeOnSend = false
+  /** Called with each parsed outbound frame, so a test can answer it. */
+  onSend: ((frame: Record<string, unknown>) => void) | null = null
+  /**
+   * Answers frames on every socket, including ones a retry has not created
+   * yet. A per-instance handler has to be attached after the socket exists,
+   * which races the frame it is meant to answer.
+   */
+  static answer: ((frame: Record<string, unknown>, ws: FakeWebSocket) => void) | null = null
+
+  /** When set, every socket fires `onerror` instead of `onopen` — an agent
+   *  that cannot be reached at all, as opposed to one that refuses a token. */
+  static failToOpen = false
+  /** When set, sockets neither open nor fail, so a connect stays in flight. */
+  static stayConnecting = false
+
+  constructor(public url: string) {
+    FakeWebSocket.instances.push(this)
+    if (FakeWebSocket.stayConnecting) return
+    if (FakeWebSocket.failToOpen) {
+      queueMicrotask(() => this.onerror?.())
+    } else {
+      queueMicrotask(() => this.onopen?.())
+    }
+  }
+
+  /** Fires the open that `stayConnecting` withheld. */
+  openNow(): void {
+    this.onopen?.()
+  }
+
+  send(raw: string): void {
+    this.sent.push(raw)
+    const frame = JSON.parse(raw) as Record<string, unknown>
+    if (this.closeOnSend) {
+      this.onclose?.()
+      return
+    }
+    this.onSend?.(frame)
+    FakeWebSocket.answer?.(frame, this)
+  }
+
+  close(): void {
+    this.onclose?.()
+  }
+}
+
+function socket(): FakeWebSocket {
+  // Index rather than `.at(-1)`: this package targets ES2020, and the test is
+  // held to the same library level as the code it guards.
+  const ws = FakeWebSocket.instances[FakeWebSocket.instances.length - 1]
+  if (!ws) throw new Error('no socket was opened')
+  return ws
+}
+
+function deliver(msg: Record<string, unknown>): void {
+  socket().onmessage?.({ data: JSON.stringify(msg) })
+}
+
+function frames(): Array<Record<string, unknown>> {
+  return socket().sent.map(s => JSON.parse(s) as Record<string, unknown>)
+}
+
+/** The client's in-flight request map, which has no public accessor. */
+function pendingSize(client: EdgePrintClient): number {
+  return (client as unknown as { pending: Map<string, unknown> }).pending.size
+}
+
+/** Connects a client, answering the auth handshake. */
+async function connected(options: Partial<ConnectOptions> = {}): Promise<EdgePrintClient> {
+  const client = new EdgePrintClient()
+  const promise = client.connect({ token: 'tok', ...options })
+  await Promise.resolve()
+  socket().onSend = frame => {
+    if (frame['type'] === 'auth') deliver({ type: 'auth_ok', id: frame['id'] })
+  }
+  await promise
+  return client
+}
+
+// Deliberately typed rather than cast: the suite doubles as a signature guard,
+// so a breaking change to PrintConfig or PrintData fails the typecheck here.
+const PDF: PrintData[] = [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: 'x' }]
+
+beforeEach(() => {
+  FakeWebSocket.instances = []
+  FakeWebSocket.failToOpen = false
+  FakeWebSocket.stayConnecting = false
+  FakeWebSocket.answer = null
+  ;(globalThis as { WebSocket?: unknown }).WebSocket = FakeWebSocket
+})
+
+afterEach(() => {
+  delete (globalThis as { WebSocket?: unknown }).WebSocket
+})
+
+describe('print() failure reporting', () => {
+  it('rejects when the agent reports the job failed after accepting it', async () => {
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({
+          type: 'print_error',
+          id: frame['id'],
+          jobId: 'job-1',
+          message: 'Printer offline',
+        })
+      }
+    }
+
+    await expect(client.print({ printer: 'Nope' }, PDF))
+      .rejects.toThrow('Printer offline')
+  })
+
+  it('carries the job id on the thrown error so a failure can be chased', async () => {
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({
+          type: 'print_error',
+          id: frame['id'],
+          jobId: 'job-7',
+          message: 'Printer offline',
+        })
+      }
+    }
+
+    const failure = await client
+      .print({ printer: 'Nope' }, PDF)
+      .then(() => null, (e: unknown) => e as Error & { jobId?: string })
+
+    expect(failure?.message).toBe('Printer offline')
+    expect(failure?.jobId).toBe('job-7')
+  })
+
+  it('leaves the job id off an error raised before a job existed', async () => {
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({ type: 'error', id: frame['id'], message: 'Printer not found' })
+      }
+    }
+
+    const failure = await client
+      .print({ printer: 'Ghost' }, PDF)
+      .then(() => null, (e: unknown) => e as Error & { jobId?: string })
+
+    expect(failure?.jobId).toBeUndefined()
+  })
+
+  it('resolves with the job id when the job completes', async () => {
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({ type: 'print_complete', id: frame['id'], jobId: 'job-2' })
+      }
+    }
+
+    await expect(client.print({ printer: 'Office Laser' }, PDF))
+      .resolves.toBe('job-2')
+  })
+
+  it('rejects on an error type it has never seen before', async () => {
+    // Matching is by `_error` suffix precisely so error types added to the
+    // protocol later reject by default instead of resolving as successes.
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({ type: 'validation_error', id: frame['id'], message: 'Unknown tray' })
+      }
+    }
+
+    await expect(client.print({ printer: 'Office Laser' }, PDF))
+      .rejects.toThrow('Unknown tray')
+  })
+
+  it('rejects before a job exists when the request itself is refused', async () => {
+    const client = await connected()
+    socket().onSend = frame => {
+      if (frame['type'] === 'print') {
+        deliver({ type: 'error', id: frame['id'], message: 'Printer not found' })
+      }
+    }
+
+    await expect(client.print({ printer: 'Ghost' }, PDF))
+      .rejects.toThrow('Printer not found')
+  })
+})
+
+describe('connect() identifies the application', () => {
+  it('sends clientName when one is given', async () => {
+    await connected({ clientName: 'Warehouse App' })
+    const auth = frames().find(f => f['type'] === 'auth')
+    expect(auth?.['clientName']).toBe('Warehouse App')
+  })
+
+  it('omits the key entirely when no name is given', async () => {
+    await connected()
+    const auth = frames().find(f => f['type'] === 'auth')
+    expect(auth && 'clientName' in auth).toBe(false)
+  })
+})
+
+describe('pending request bookkeeping', () => {
+  it('leaves nothing in the pending map when the socket closes mid-send', async () => {
+    const client = await connected()
+    socket().closeOnSend = true
+
+    await expect(client.print({ printer: 'Office Laser' }, PDF))
+      .rejects.toThrow('Connection closed')
+
+    // Guards the single-insert structure: the entry used to be inserted raw and
+    // then replaced by one closing over a value read back out of the map, which
+    // only holds together if nothing observes the map in between.
+    expect(pendingSize(client)).toBe(0)
+  })
+
+  it('still rejects later requests cleanly after a close during send', async () => {
+    // Under the old structure a half-built entry made the next rejectPending
+    // throw partway through its loop, stranding every other in-flight request.
+    // Synthetic ordering (see closeOnSend), but the invariant is worth holding.
+    const client = await connected()
+    socket().closeOnSend = true
+    await expect(client.print({ printer: 'A' }, PDF)).rejects.toThrow()
+
+    const again = await connected()
+    socket().closeOnSend = true
+    await expect(again.print({ printer: 'B' }, PDF))
+      .rejects.toThrow('Connection closed')
+    expect(pendingSize(again)).toBe(0)
+  })
+
+  it('stops calling a close listener once it unsubscribes', async () => {
+    const client = await connected()
+    const seen: string[] = []
+    client.onClose(() => seen.push('kept'))
+    const stop = client.onClose(() => seen.push('removed'))
+
+    stop()
+    socket().close()
+
+    expect(seen).toEqual(['kept'])
+  })
+
+  it('still runs later listeners when one removes itself mid-close', async () => {
+    // The unsubscribe splices the array onclose is iterating, so iterating the
+    // live array would skip whichever listener followed the one that removed
+    // itself — and removing yourself from a close handler is the natural shape
+    // of a one-shot reconnect.
+    const client = await connected()
+    const seen: string[] = []
+    const stopFirst = client.onClose(() => { seen.push('first'); stopFirst() })
+    client.onClose(() => seen.push('second'))
+
+    socket().close()
+
+    expect(seen).toEqual(['first', 'second'])
+  })
+
+  it('rejects in-flight requests when the socket closes normally', async () => {
+    const client = await connected()
+    socket().onSend = null
+
+    const inFlight = client.printers()
+    socket().close()
+
+    await expect(inFlight).rejects.toThrow('Connection closed')
+    expect(pendingSize(client)).toBe(0)
+  })
+})
+
+describe('connection lifecycle', () => {
+  /** Answers the auth handshake on whichever socket is current. */
+  function acceptAuth() {
+    socket().onSend = frame => {
+      if (frame['type'] === 'auth') deliver({ type: 'auth_ok', id: frame['id'] })
+    }
+  }
+
+  /** Refuses the auth handshake the way the agent does — an error response on
+   *  a socket it deliberately leaves open. */
+  function refuseAuth() {
+    socket().onSend = frame => {
+      if (frame['type'] === 'auth') {
+        deliver({ type: 'error', id: frame['id'], message: 'Invalid token' })
+      }
+    }
+  }
+
+  /// The agent answers a token awaiting approval with the same "Invalid token"
+  /// it gives a genuinely bad one, so the client cannot tell them apart — and
+  /// the documented flow is to keep retrying while someone clicks Approve.
+  /// Repeat attempts cost one counter increment on the pending entry; only the
+  /// first raises a notification.
+  it('keeps retrying a refused token, since approval may still be coming', async () => {
+    FakeWebSocket.answer = (frame, ws) => {
+      if (frame['type'] === 'auth') {
+        ws.onmessage?.({
+          data: JSON.stringify({ type: 'error', id: frame['id'], message: 'Invalid token' }),
+        })
+      }
+    }
+
+    const client = new EdgePrintClient()
+    await expect(
+      client.connect({ token: 'pending', retries: 2, retryDelay: 1 }),
+    ).rejects.toThrow('Invalid token')
+
+    expect(FakeWebSocket.instances.length).toBe(3)
+  })
+
+  /// Approval landing mid-retry is the whole point of retrying.
+  it('connects when approval arrives between attempts', async () => {
+    let approved = false
+    FakeWebSocket.answer = (frame, ws) => {
+      if (frame['type'] !== 'auth') return
+      const id = frame['id']
+      // Refused twice, then the user clicks Approve.
+      const reply = approved
+        ? { type: 'auth_ok', id }
+        : { type: 'error', id, message: 'Invalid token' }
+      approved = true
+      ws.onmessage?.({ data: JSON.stringify(reply) })
+    }
+
+    const client = new EdgePrintClient()
+    await client.connect({ token: 'pending', retries: 3, retryDelay: 1 })
+
+    expect(client.isConnected()).toBe(true)
+    expect(FakeWebSocket.instances.length).toBe(2)
+  })
+
+  it('still retries when the agent cannot be reached', async () => {
+    FakeWebSocket.failToOpen = true
+    const client = new EdgePrintClient()
+
+    await expect(
+      client.connect({ token: 'tok', retries: 2, retryDelay: 1 }),
+    ).rejects.toThrow('Cannot reach')
+
+    // One initial attempt plus two retries — reachability can change between
+    // attempts, unlike a refusal.
+    expect(FakeWebSocket.instances.length).toBe(3)
+  })
+
+  it('leaves no socket behind when a connect is refused', async () => {
+    const client = new EdgePrintClient()
+    const promise = client.connect({ token: 'refused', retries: 0 })
+    await Promise.resolve()
+    refuseAuth()
+    await expect(promise).rejects.toThrow()
+
+    const orphan = socket()
+    let closes = 0
+    client.onClose(() => closes++)
+
+    // Reconnect successfully, then let the refused attempt's socket drop.
+    const second = client.connect({ token: 'tok' })
+    await Promise.resolve()
+    acceptAuth()
+    await second
+
+    orphan.close()
+
+    expect(closes).toBe(0)
+    expect(client.isConnected()).toBe(true)
+  })
+
+  it('does not strand the previous socket when connect is called on a live client', async () => {
+    const client = await connected()
+    const first = socket()
+
+    const again = client.connect({ token: 'tok' })
+    await Promise.resolve()
+    acceptAuth()
+    await again
+    expect(socket()).not.toBe(first)
+
+    let closes = 0
+    client.onClose(() => closes++)
+    first.close()
+
+    expect(closes).toBe(0)
+    expect(client.isConnected()).toBe(true)
+  })
+
+  /// onClose documents that it fires on "a network drop, an agent restart, or
+  /// an explicit disconnect() call". Routing disconnect through the same
+  /// teardown as a socket replacement detaches the handlers, so the socket's
+  /// own close never arrives and the listener has to be called here instead —
+  /// a silent disconnect leaves an app that tracks connectivity through
+  /// onClose believing it is still connected.
+  it('tells close listeners about an explicit disconnect', async () => {
+    const client = await connected()
+    let closes = 0
+    client.onClose(() => closes++)
+
+    client.disconnect()
+
+    expect(closes).toBe(1)
+    expect(client.isConnected()).toBe(false)
+  })
+
+  it('says nothing when disconnect is called on an idle client', async () => {
+    const client = new EdgePrintClient()
+    let closes = 0
+    client.onClose(() => closes++)
+
+    client.disconnect()
+
+    expect(closes).toBe(0)
+  })
+
+  /// A reconnect that fails has destroyed the live connection and put nothing
+  /// in its place, so the app is disconnected and has to be told — otherwise
+  /// anything tracking connectivity through onClose believes it is still up.
+  it('tells listeners when a reconnect fails and takes the live connection with it', async () => {
+    const client = await connected()
+    let closes = 0
+    client.onClose(() => closes++)
+
+    const doomed = client.connect({ token: 'refused', retries: 0 })
+    const outcome = doomed.then(() => 'resolved', () => 'rejected')
+    await Promise.resolve()
+    refuseAuth()
+    await new Promise(r => setTimeout(r, 5))
+
+    expect(await outcome).toBe('rejected')
+    expect(client.isConnected()).toBe(false)
+    expect(closes).toBe(1)
+  })
+
+  /// A socket that dropped before authenticating was never a connection, so
+  /// announcing one would have an onClose-driven reconnect racing the retry
+  /// loop that is already running.
+  it('says nothing when a socket drops before it ever authenticated', async () => {
+    const client = new EdgePrintClient()
+    const attempt = client.connect({ token: 'tok', retries: 0 })
+    const outcome = attempt.then(() => 'resolved', () => 'rejected')
+    await Promise.resolve()
+
+    let closes = 0
+    client.onClose(() => closes++)
+    socket().close()
+
+    await outcome
+    expect(closes).toBe(0)
+  })
+
+  it('does not let a disconnected socket tear down the next connection', async () => {
+    const client = await connected()
+    const first = socket()
+    client.disconnect()
+
+    const again = client.connect({ token: 'tok' })
+    await Promise.resolve()
+    acceptAuth()
+    await again
+
+    let closes = 0
+    client.onClose(() => closes++)
+    // The browser dispatches the close for the disconnected socket later.
+    first.close()
+
+    expect(closes).toBe(0)
+    expect(client.isConnected()).toBe(true)
+  })
+
+  /// The regression that killed an earlier attempt at this: discarding a socket
+  /// detaches its handlers, so a connect still waiting on `onopen` had nothing
+  /// left to settle it and hung forever with no timeout to rescue it.
+  it('settles an in-flight connect when a second one supersedes it', async () => {
+    FakeWebSocket.stayConnecting = true
+    const client = new EdgePrintClient()
+
+    const first = client.connect({ token: 'tok', retries: 0 })
+    const firstOutcome = first.then(() => 'resolved').catch(() => 'rejected')
+    await Promise.resolve()
+
+    FakeWebSocket.stayConnecting = false
+    const second = client.connect({ token: 'tok', retries: 0 })
+    await Promise.resolve()
+    acceptAuth()
+    await second
+
+    const settled = await Promise.race([
+      firstOutcome,
+      new Promise(r => setTimeout(() => r('HUNG'), 50)),
+    ])
+    expect(settled).toBe('rejected')
+  })
+
+  it('rejects in-flight requests when a connect supersedes the socket', async () => {
+    const client = await connected()
+    socket().onSend = null
+    const inFlight = client.printers()
+
+    const again = client.connect({ token: 'tok' })
+    await Promise.resolve()
+    acceptAuth()
+    await again
+
+    await expect(inFlight).rejects.toThrow()
+  })
+})
+
+describe('connection lifecycle — supersession and cancellation', () => {
+  function acceptAuth() {
+    socket().onSend = frame => {
+      if (frame['type'] === 'auth') deliver({ type: 'auth_ok', id: frame['id'] })
+    }
+  }
+
+  /// A connect that failed and is sleeping before its next attempt must not
+  /// wake up and tear down a connection someone else established in the
+  /// meantime. The generation is checked when an attempt fails; it has to be
+  /// checked again before the next one starts.
+  it('a sleeping retry does not discard a newer live connection', async () => {
+    FakeWebSocket.failToOpen = true
+    const client = new EdgePrintClient()
+
+    const stale = client.connect({ token: 'tok', retries: 3, retryDelay: 20 })
+    const staleOutcome = stale.then(() => 'resolved', () => 'rejected')
+    await new Promise(r => setTimeout(r, 5))
+
+    // A second connect succeeds while the first is between attempts.
+    FakeWebSocket.failToOpen = false
+    const fresh = client.connect({ token: 'tok', retries: 0 })
+    await Promise.resolve()
+    acceptAuth()
+    await fresh
+    const live = socket()
+
+    live.onSend = frame => {
+      if (frame['type'] === 'get_printers') {
+        deliver({ type: 'printers', id: frame['id'], printers: [] })
+      }
+    }
+    const inFlight = client.printers()
+
+    // Let the stale attempt's sleep elapse.
+    await new Promise(r => setTimeout(r, 60))
+
+    expect(await staleOutcome).toBe('rejected')
+    expect(client.isConnected()).toBe(true)
+    expect(socket()).toBe(live)
+    await expect(inFlight).resolves.toBeDefined()
+  })
+
+  /// Disconnect has to stop a connect that is still retrying, or the client
+  /// quietly reconnects a second later while the app believes it is closed.
+  it('disconnect cancels a connect that is still retrying', async () => {
+    FakeWebSocket.failToOpen = true
+    const client = new EdgePrintClient()
+
+    const attempt = client.connect({ token: 'tok', retries: 3, retryDelay: 20 })
+    const outcome = attempt.then(() => 'resolved', () => 'rejected')
+    await new Promise(r => setTimeout(r, 5))
+
+    const socketsBefore = FakeWebSocket.instances.length
+    client.disconnect()
+    FakeWebSocket.failToOpen = false
+
+    await new Promise(r => setTimeout(r, 60))
+
+    expect(await outcome).toBe('rejected')
+    expect(client.isConnected()).toBe(false)
+    expect(FakeWebSocket.instances.length).toBe(socketsBefore)
+  })
+
+  /// A socket that closes during the handshake never fires onopen or onerror,
+  /// so the connect has nothing to settle it and no timeout covers it.
+  /// A caller computing `retries: maxAttempts - 1` from config can reach a
+  /// negative value. Skipping the loop would resolve connect() without ever
+  /// opening a socket, so the caller believes it is connected and every later
+  /// call rejects with "Not connected" for no visible reason.
+  it('still makes one attempt when given a negative retry count', async () => {
+    FakeWebSocket.failToOpen = true
+    const client = new EdgePrintClient()
+
+    await expect(
+      client.connect({ token: 'tok', retries: -1 }),
+    ).rejects.toThrow('Cannot reach')
+
+    expect(FakeWebSocket.instances.length).toBe(1)
+    expect(client.isConnected()).toBe(false)
+  })
+
+  it('settles a connect whose socket closes before it opens', async () => {
+    FakeWebSocket.stayConnecting = true
+    const client = new EdgePrintClient()
+
+    const attempt = client.connect({ token: 'tok', retries: 0 })
+    const outcome = attempt.then(() => 'resolved', () => 'rejected')
+    await Promise.resolve()
+
+    socket().close()
+
+    const settled = await Promise.race([
+      outcome,
+      new Promise(r => setTimeout(() => r('HUNG'), 50)),
+    ])
+    expect(settled).toBe('rejected')
+  })
+
+  /// onClose documents a *connection* closing. A connect that never opened was
+  /// never a connection, so announcing one would report a drop that never
+  /// happened to an app using onClose as its connectivity signal.
+  it('says nothing when disconnecting a socket that never opened', async () => {
+    FakeWebSocket.stayConnecting = true
+    const client = new EdgePrintClient()
+
+    const attempt = client.connect({ token: 'tok', retries: 0 })
+    const outcome = attempt.then(() => 'resolved', () => 'rejected')
+    await Promise.resolve()
+
+    let closes = 0
+    client.onClose(() => closes++)
+    client.disconnect()
+    await outcome
+
+    expect(closes).toBe(0)
+  })
+
+  /// An agent that opens the socket and then never answers is stalled, not
+  /// refusing — the transient condition retries exist for. Only a response
+  /// counts as a definitive answer.
+  it('retries when the agent opens the socket but never answers', async () => {
+    vi.useFakeTimers()
+    try {
+      const client = new EdgePrintClient()
+      // Never answers the auth frame, so the request falls to its own timeout.
+      const attempt = client.connect({ token: 'tok', retries: 1, retryDelay: 1 })
+      const outcome = attempt.then(() => 'resolved', () => 'rejected')
+
+      // Each attempt: let the socket open, then run out the request timeout
+      // and the retry delay.
+      for (let i = 0; i < 2; i++) {
+        await Promise.resolve()
+        await vi.advanceTimersByTimeAsync(31_000)
+      }
+
+      expect(await outcome).toBe('rejected')
+      expect(FakeWebSocket.instances.length).toBe(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})