@tapicker/bridge 1.0.0 → 1.1.0

package/src/workflow-watch.ts

@@ -1,364 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { WebSocket } from 'ws'
-import { DEFAULT_WORKFLOW_WATCH_WS_PATH } from './constants.js'
-import { BridgeError } from './errors.js'
-import { SafeResultSchema, WorkflowStatusEventSchema, createEnvelope, parseEnvelope } from './protocol/schema.js'
-import type { WorkflowStatusEvent } from './protocol/schema.js'
-
-export type WorkflowWatchInput = {
-  clientId?: string
-  workflowId: string
-  timeoutMs?: number
-}
-
-export type WorkflowWatchResult = WorkflowStatusEvent & {
-  timedOut: boolean
-}
-
-export type WorkflowWatchConnection = {
-  clientId: string
-  workflowId: string
-  onStatus: (listener: (event: WorkflowStatusEvent) => void) => () => void
-  onClose: (listener: (error: BridgeError) => void) => () => void
-  close: () => void
-}
-
-type WaitForWorkflowStatusOptions = {
-  clientId: string
-  workflowId: string
-  subscribe: (onStatus: (event: WorkflowStatusEvent) => void, onClose: (error: BridgeError) => void) => () => void
-  readStatus: () => Promise<WorkflowStatusEvent>
-  onStatus?: (event: WorkflowStatusEvent) => void
-  timeoutMs?: number
-  signal?: AbortSignal
-}
-
-const terminalStates = new Set(['completed', 'stopped', 'failed'])
-
-export function workflowWatchWebSocketUrl(bridgeUrl: URL) {
-  const url = new URL(DEFAULT_WORKFLOW_WATCH_WS_PATH, bridgeUrl)
-  url.protocol = bridgeUrl.protocol === 'https:' ? 'wss:' : 'ws:'
-  return url
-}
-
-export function connectWorkflowWatch(
-  url: string | URL,
-  input: Omit<WorkflowWatchInput, 'timeoutMs'>,
-  token?: string,
-  signal?: AbortSignal,
-): Promise<WorkflowWatchConnection> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }))
-      return
-    }
-
-    const headers = token ? { Authorization: `Bearer ${token}` } : undefined
-    const socket = new WebSocket(url, headers ? { headers } : undefined)
-    const requestId = randomUUID()
-    const statusListeners = new Set<(event: WorkflowStatusEvent) => void>()
-    const closeListeners = new Set<(error: BridgeError) => void>()
-    const pendingStatusEvents: WorkflowStatusEvent[] = []
-    let acceptedClientId: string | undefined
-    let settled = false
-    let intentionalClose = false
-    let closedError: BridgeError | undefined
-    let abortListener: (() => void) | undefined
-
-    const cleanupAbortListener = () => {
-      if (abortListener) signal?.removeEventListener('abort', abortListener)
-      abortListener = undefined
-    }
-
-    const failBeforeAccept = (error: BridgeError) => {
-      if (settled) return
-      settled = true
-      cleanupAbortListener()
-      socket.terminate()
-      reject(error)
-    }
-
-    const notifyClose = (error: BridgeError) => {
-      closedError = error
-      cleanupAbortListener()
-      for (const listener of closeListeners) {
-        try {
-          listener(error)
-        } catch {
-          // A consumer callback must not escape the WebSocket event handler.
-        }
-      }
-      closeListeners.clear()
-    }
-
-    const close = (reason?: BridgeError) => {
-      intentionalClose = true
-      cleanupAbortListener()
-      if (socket.readyState === WebSocket.OPEN) {
-        socket.close(1000, 'Workflow watch closed')
-      } else if (socket.readyState === WebSocket.CONNECTING) {
-        socket.terminate()
-      }
-      if (acceptedClientId) {
-        notifyClose(
-          reason ?? new BridgeError('WorkflowWatchClosed', 'Workflow watch was closed by the client', { status: 499 }),
-        )
-      }
-    }
-
-    abortListener = () => {
-      const error = new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 })
-      if (!acceptedClientId) {
-        failBeforeAccept(error)
-      } else {
-        close(error)
-      }
-    }
-    signal?.addEventListener('abort', abortListener, { once: true })
-
-    socket.once('open', () => {
-      socket.send(
-        JSON.stringify(
-          createEnvelope(
-            'workflow.watch',
-            {
-              clientId: input.clientId,
-              input: { workflowId: input.workflowId },
-            },
-            { id: requestId },
-          ),
-        ),
-      )
-    })
-
-    socket.on('message', (raw) => {
-      const parsedEnvelope = parseEnvelope(raw)
-      if (!parsedEnvelope.success) {
-        const error = new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow watch message', {
-          status: 502,
-          cause: parsedEnvelope.error,
-        })
-        if (!acceptedClientId) failBeforeAccept(error)
-        else {
-          socket.close(1007, 'Invalid Workflow watch message')
-          notifyClose(error)
-        }
-        return
-      }
-
-      const message = parsedEnvelope.data
-      if (message.type === 'workflow.watch:res' && message.id === requestId && !acceptedClientId) {
-        const result = SafeResultSchema.safeParse(message.data)
-        if (!result.success) {
-          failBeforeAccept(
-            new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow watch response', {
-              status: 502,
-            }),
-          )
-          return
-        }
-        if (!result.data.ok) {
-          failBeforeAccept(
-            new BridgeError(result.data.error.code, result.data.error.message, {
-              status: 409,
-              details: result.data.error.details,
-            }),
-          )
-          return
-        }
-
-        const accepted = WorkflowStatusEventSchema.pick({ clientId: true, workflowId: true }).safeParse(
-          result.data.data,
-        )
-        if (!accepted.success || accepted.data.workflowId !== input.workflowId) {
-          failBeforeAccept(
-            new BridgeError('InvalidBridgeResponse', 'Bridge accepted a different Workflow watch target', {
-              status: 502,
-            }),
-          )
-          return
-        }
-
-        acceptedClientId = accepted.data.clientId
-        settled = true
-        const connection: WorkflowWatchConnection = {
-          clientId: accepted.data.clientId,
-          workflowId: accepted.data.workflowId,
-          onStatus(listener) {
-            statusListeners.add(listener)
-            for (const event of pendingStatusEvents.splice(0)) listener(event)
-            return () => statusListeners.delete(listener)
-          },
-          onClose(listener) {
-            if (closedError) {
-              listener(closedError)
-              return () => undefined
-            }
-            closeListeners.add(listener)
-            return () => closeListeners.delete(listener)
-          },
-          close,
-        }
-        resolve(connection)
-        return
-      }
-
-      if (message.type !== 'workflow.status' || !acceptedClientId) return
-      const event = WorkflowStatusEventSchema.safeParse(message.data)
-      if (!event.success) return
-      if (event.data.clientId !== acceptedClientId || event.data.workflowId !== input.workflowId) return
-      if (statusListeners.size === 0) {
-        if (pendingStatusEvents.length >= 128) pendingStatusEvents.shift()
-        pendingStatusEvents.push(event.data)
-      } else {
-        for (const listener of statusListeners) {
-          try {
-            listener(event.data)
-          } catch {
-            // A consumer callback must not escape the WebSocket event handler.
-          }
-        }
-      }
-    })
-
-    socket.once('unexpected-response', (_request, response) => {
-      const chunks: Buffer[] = []
-      response.on('data', (chunk: Buffer) => chunks.push(Buffer.from(chunk)))
-      response.once('end', () => {
-        const body = Buffer.concat(chunks).toString('utf8')
-        let errorCode = 'BridgeRequestFailed'
-        let errorMessage = response.statusMessage || 'Bridge rejected the Workflow watch connection'
-        let details: unknown
-        try {
-          const parsed = JSON.parse(body) as { error?: { code?: string; message?: string; details?: unknown } }
-          errorCode = parsed.error?.code || errorCode
-          errorMessage = parsed.error?.message || errorMessage
-          details = parsed.error?.details
-        } catch {
-          // Keep the HTTP status text when the response is not Bridge JSON.
-        }
-        failBeforeAccept(new BridgeError(errorCode, errorMessage, { status: response.statusCode || 503, details }))
-      })
-    })
-
-    socket.on('error', (cause) => {
-      const error = new BridgeError('BridgeUnavailable', 'Unable to connect to Tapicker Bridge Workflow watch', {
-        status: 503,
-        cause,
-      })
-      if (!acceptedClientId) failBeforeAccept(error)
-      else notifyClose(error)
-    })
-
-    socket.once('close', (code, reason) => {
-      cleanupAbortListener()
-      if (!acceptedClientId) {
-        failBeforeAccept(
-          new BridgeError('WorkflowWatchClosed', 'Bridge closed the Workflow watch connection before accepting it', {
-            status: 503,
-            details: { code, reason: reason.toString() },
-          }),
-        )
-      } else if (!intentionalClose) {
-        notifyClose(
-          new BridgeError('WorkflowWatchClosed', 'Bridge closed the Workflow watch connection', {
-            status: 503,
-            details: { code, reason: reason.toString() },
-          }),
-        )
-      }
-    })
-  })
-}
-
-export function waitForWorkflowStatus(options: WaitForWorkflowStatusOptions): Promise<WorkflowWatchResult> {
-  return new Promise((resolve, reject) => {
-    let settled = false
-    let latestStatus: WorkflowStatusEvent | undefined
-    let timer: ReturnType<typeof setTimeout> | undefined
-    let unsubscribe: () => void = () => {}
-    let abortListener: (() => void) | undefined
-
-    const cleanup = () => {
-      unsubscribe()
-      if (timer) clearTimeout(timer)
-      if (abortListener) options.signal?.removeEventListener('abort', abortListener)
-    }
-
-    const finish = (status: WorkflowStatusEvent, timedOut = false) => {
-      if (settled) return
-      settled = true
-      cleanup()
-      resolve({ ...status, timedOut })
-    }
-
-    const fail = (error: unknown) => {
-      if (settled) return
-      settled = true
-      cleanup()
-      reject(error)
-    }
-
-    const publish = (status: WorkflowStatusEvent) => {
-      if (settled) return
-      if (status.clientId !== options.clientId || status.workflowId !== options.workflowId) return
-      if (latestStatus && sameStatus(latestStatus, status)) return
-      latestStatus = status
-      try {
-        options.onStatus?.(status)
-      } catch (error) {
-        fail(error)
-        return
-      }
-      if (terminalStates.has(status.state)) finish(status)
-    }
-
-    if (options.signal?.aborted) {
-      fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }))
-      return
-    }
-
-    unsubscribe = options.subscribe(publish, fail)
-    if (settled) {
-      unsubscribe()
-      return
-    }
-    if (options.signal) {
-      abortListener = () =>
-        fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }))
-      options.signal.addEventListener('abort', abortListener, { once: true })
-    }
-    if (options.timeoutMs !== undefined) {
-      timer = setTimeout(() => {
-        if (latestStatus) finish(latestStatus, true)
-        else
-          fail(
-            new BridgeError('WorkflowWatchTimeout', 'Timed out before receiving Workflow status', {
-              status: 504,
-              details: { timeoutMs: options.timeoutMs },
-            }),
-          )
-      }, options.timeoutMs)
-    }
-
-    void options
-      .readStatus()
-      .then((snapshot) => {
-        if (settled) return
-        const snapshotIsAtLeastAsNew =
-          latestStatus !== undefined && Date.parse(snapshot.updatedAt) >= Date.parse(latestStatus.updatedAt)
-        if (
-          !latestStatus ||
-          snapshotIsAtLeastAsNew ||
-          (terminalStates.has(snapshot.state) && !terminalStates.has(latestStatus.state))
-        ) {
-          publish(snapshot)
-        }
-      })
-      .catch(fail)
-  })
-}
-
-function sameStatus(left: WorkflowStatusEvent, right: WorkflowStatusEvent) {
-  return left.state === right.state && left.updatedAt === right.updatedAt
-}