@tapicker/bridge 1.0.0

package/src/server.ts

@@ -0,0 +1,623 @@
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server as HttpServer,
+  type ServerResponse,
+} from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
+import { readFileSync } from 'node:fs'
+import { randomInt, randomUUID, timingSafeEqual } from 'node:crypto'
+import { URL } from 'node:url'
+import { join, resolve } from 'node:path'
+import { WebSocketServer } from 'ws'
+import type { WebSocket } from 'ws'
+import { createMcpHandler } from '@modelcontextprotocol/server'
+import type { McpHttpHandler } from '@modelcontextprotocol/server'
+import { localhostHostValidation, toNodeHandler } from '@modelcontextprotocol/node'
+import type { NodeMcpRequestHandler } from '@modelcontextprotocol/node'
+import {
+  DEFAULT_HOST,
+  DEFAULT_MCP_PATH,
+  DEFAULT_PORT,
+  DEFAULT_PORT_MAX,
+  DEFAULT_WS_PATH,
+  DEFAULT_WORKFLOW_WATCH_WS_PATH,
+  PROTOCOL_VERSION,
+  VERSION,
+} from './constants.js'
+import { BridgeService } from './bridge/bridge-service.js'
+import type { BridgeWorkflowStatusEvent } from './bridge/bridge-service.js'
+import { PairingStateFile } from './bridge/pairing-state.js'
+import { getCommandCapabilities, dispatchCommand } from './commands.js'
+import { BridgeError, safeError, safeSuccess, toBridgeError } from './errors.js'
+import { createBridgeMcpApi, createTapickerMcpServer } from './mcp.js'
+import { WorkflowWatchRequestSchema, createEnvelope, parseEnvelope } from './protocol/schema.js'
+
+const DEFAULT_CORS_ORIGINS = ['*']
+const CORS_ALLOWED_METHODS = 'GET, POST, DELETE, OPTIONS'
+const CORS_ALLOWED_HEADERS = 'Accept, Authorization, Content-Type, Last-Event-ID, MCP-Protocol-Version, Mcp-Session-Id'
+const CORS_EXPOSED_HEADERS = 'MCP-Protocol-Version, Mcp-Session-Id'
+
+export type BridgeTlsOptions = {
+  key: string
+  cert: string
+}
+
+export type BridgeServerOptions = {
+  host?: string
+  port?: number
+  portMax?: number
+  token?: string
+  corsOrigins?: string[]
+  tls?: BridgeTlsOptions
+  pairingCode?: string
+  dataDir?: string
+}
+
+type NodeServer = HttpServer
+
+type WorkflowSubscription = {
+  clientId: string
+  workflowId: string
+}
+
+export class BridgeServer {
+  readonly bridgeId = randomUUID()
+  readonly bridge: BridgeService
+
+  private readonly host: string
+  private readonly requestedPort?: number
+  private readonly portMax: number
+  private readonly token?: string
+  private readonly corsOrigins: string[]
+  private readonly tls?: BridgeTlsOptions
+  private readonly mcpHandler: McpHttpHandler
+  private readonly mcpNodeHandler: NodeMcpRequestHandler
+  private readonly validateLocalMcpHost = localhostHostValidation()
+  private server: NodeServer | undefined
+  private webSocketServer: WebSocketServer | undefined
+  private port: number | undefined
+  private readonly workflowSubscriptions = new Map<WebSocket, WorkflowSubscription>()
+
+  constructor(options: BridgeServerOptions = {}) {
+    this.host = options.host ?? DEFAULT_HOST
+    this.requestedPort = options.port
+    this.portMax = options.portMax ?? DEFAULT_PORT_MAX
+    this.token = options.token
+    this.corsOrigins = normalizeCorsOrigins(options.corsOrigins ?? DEFAULT_CORS_ORIGINS)
+    this.tls = options.tls
+    const pairingState = options.dataDir
+      ? new PairingStateFile(join(resolve(options.dataDir), 'paired-clients.json'))
+      : undefined
+    this.bridge = new BridgeService({
+      pairingCode: options.pairingCode ?? String(randomInt(0, 10_000)).padStart(4, '0'),
+      capabilities: [
+        'workflow.start',
+        'workflow.pause',
+        'workflow.resume',
+        'workflow.stop',
+        'workflow.status',
+        'workflow.status.get',
+        'data.get',
+        'data.delete',
+      ],
+      pairingState,
+    })
+    this.mcpHandler = createMcpHandler(() => createTapickerMcpServer(createBridgeMcpApi(this.bridge)))
+    this.mcpNodeHandler = toNodeHandler(this.mcpHandler, {
+      onerror: (error) => console.error('Tapicker Bridge MCP request failed:', error),
+    })
+    this.bridge.on('workflow.status', (event: BridgeWorkflowStatusEvent) => this.publishWorkflowStatus(event))
+  }
+
+  getPairingCode() {
+    return this.bridge.getPairingCode()
+  }
+
+  refreshPairingCode() {
+    return this.bridge.refreshPairingCode()
+  }
+
+  async start() {
+    if (this.server && this.port !== undefined) {
+      return this.getAddress()
+    }
+
+    await this.bridge.initialize()
+
+    const ports = this.getPorts()
+    let lastError: unknown
+
+    for (const port of ports) {
+      const runtime = this.createRuntime()
+
+      try {
+        const actualPort = await listen(runtime.server, this.host, port)
+        this.server = runtime.server
+        this.webSocketServer = runtime.webSocketServer
+        this.port = actualPort
+        return this.getAddress()
+      } catch (error) {
+        await closeServer(runtime.server)
+        runtime.webSocketServer.close()
+
+        if (isAddressInUseError(error) && this.requestedPort === undefined) {
+          lastError = error
+          continue
+        }
+
+        throw error
+      }
+    }
+
+    throw toBridgeError(lastError, 'PortUnavailable', 503)
+  }
+
+  async close() {
+    this.bridge.close()
+    this.workflowSubscriptions.clear()
+    await this.mcpHandler.close()
+    this.webSocketServer?.clients.forEach((client) => client.terminate())
+    await closeWebSocketServer(this.webSocketServer)
+    await closeServer(this.server)
+    this.server = undefined
+    this.webSocketServer = undefined
+    this.port = undefined
+  }
+
+  getAddress() {
+    if (!this.port) {
+      throw new BridgeError('BridgeNotStarted', 'Bridge server has not started', { status: 500 })
+    }
+
+    const secure = Boolean(this.tls)
+    const protocol = secure ? 'https' : 'http'
+    const webSocketProtocol = secure ? 'wss' : 'ws'
+    const displayHost = this.host === '0.0.0.0' || this.host === '::' ? '127.0.0.1' : this.host
+
+    return {
+      host: this.host,
+      port: this.port,
+      httpUrl: `${protocol}://${displayHost}:${this.port}`,
+      wsUrl: `${webSocketProtocol}://${displayHost}:${this.port}${DEFAULT_WS_PATH}`,
+      workflowWatchWsUrl: `${webSocketProtocol}://${displayHost}:${this.port}${DEFAULT_WORKFLOW_WATCH_WS_PATH}`,
+      mcpUrl: `${protocol}://${displayHost}:${this.port}${DEFAULT_MCP_PATH}`,
+    }
+  }
+
+  private getPorts() {
+    if (this.requestedPort !== undefined) {
+      return [this.requestedPort]
+    }
+
+    return Array.from({ length: this.portMax - DEFAULT_PORT + 1 }, (_, index) => DEFAULT_PORT + index)
+  }
+
+  private createRuntime() {
+    const requestHandler = (request: IncomingMessage, response: ServerResponse) => {
+      void this.handleRequest(request, response)
+    }
+
+    const server = this.tls
+      ? createHttpsServer(
+          {
+            key: readFileSync(this.tls.key),
+            cert: readFileSync(this.tls.cert),
+          },
+          requestHandler,
+        )
+      : createHttpServer(requestHandler)
+
+    const webSocketServer = new WebSocketServer({ noServer: true })
+
+    server.on('upgrade', (request, socket, head) => {
+      const requestUrl = new URL(request.url || '/', this.getOrigin(request))
+      if (requestUrl.pathname === DEFAULT_WORKFLOW_WATCH_WS_PATH) {
+        try {
+          this.assertAuthorized(request)
+        } catch (error) {
+          rejectUpgrade(socket, toBridgeError(error))
+          return
+        }
+
+        webSocketServer.handleUpgrade(request, socket, head, (client) => this.attachWorkflowWatcher(client))
+        return
+      }
+
+      if (requestUrl.pathname !== DEFAULT_WS_PATH) {
+        socket.destroy()
+        return
+      }
+
+      webSocketServer.handleUpgrade(request, socket, head, (client) => {
+        this.bridge.attachExtension(client, request.socket.remoteAddress)
+      })
+    })
+
+    return { server, webSocketServer }
+  }
+
+  private async handleRequest(request: IncomingMessage, response: ServerResponse) {
+    try {
+      const requestUrl = new URL(request.url || '/', this.getOrigin(request))
+      const method = request.method || 'GET'
+
+      if (!this.applyCors(request, response)) {
+        this.sendJson(
+          response,
+          403,
+          safeError(
+            new BridgeError('CorsOriginNotAllowed', 'Cross-origin requests from this Origin are not allowed', {
+              status: 403,
+            }),
+          ),
+        )
+        return
+      }
+
+      if (method === 'OPTIONS') {
+        response.statusCode = 204
+        response.end()
+        return
+      }
+
+      if (requestUrl.pathname === DEFAULT_MCP_PATH) {
+        if (isLoopbackHost(this.host) && !this.validateLocalMcpHost(request, response)) {
+          return
+        }
+
+        this.assertAuthorized(request)
+        await this.mcpNodeHandler(request, response)
+        return
+      }
+
+      if (method === 'GET' && requestUrl.pathname === '/v1/health') {
+        this.sendJson(response, 200, {
+          ok: true,
+          service: 'tapicker-bridge',
+          version: VERSION,
+          protocolVersion: PROTOCOL_VERSION,
+          bridgeId: this.bridgeId,
+        })
+        return
+      }
+
+      if (method === 'GET' && requestUrl.pathname === '/v1/discovery') {
+        this.sendJson(response, 200, {
+          service: 'tapicker-bridge',
+          version: VERSION,
+          protocolVersion: PROTOCOL_VERSION,
+          bridgeId: this.bridgeId,
+          wsPath: DEFAULT_WS_PATH,
+          workflowWatchPath: DEFAULT_WORKFLOW_WATCH_WS_PATH,
+          requiresAuthentication: Boolean(this.token),
+        })
+        return
+      }
+
+      if (method === 'GET' && requestUrl.pathname === '/v1/capabilities') {
+        this.sendJson(response, 200, {
+          protocolVersion: PROTOCOL_VERSION,
+          commands: getCommandCapabilities(),
+        })
+        return
+      }
+
+      if (method === 'GET' && requestUrl.pathname === '/v1/extensions') {
+        this.assertAuthorized(request)
+        this.sendJson(response, 200, {
+          extensions: this.bridge.getExtensionStatuses(),
+        })
+        return
+      }
+
+      if (requestUrl.pathname === DEFAULT_WORKFLOW_WATCH_WS_PATH) {
+        this.assertAuthorized(request)
+        this.sendJson(
+          response,
+          405,
+          safeError(
+            new BridgeError('WebSocketRequired', 'workflow.watch requires a WebSocket connection', { status: 405 }),
+          ),
+        )
+        return
+      }
+
+      if (method === 'POST' && requestUrl.pathname.startsWith('/v1/commands/')) {
+        this.assertAuthorized(request)
+        const commandName = decodeURIComponent(requestUrl.pathname.slice('/v1/commands/'.length))
+        const body = await readJson(request)
+        const data = await dispatchCommand(commandName, body, { bridge: this.bridge })
+        this.sendJson(response, 200, safeSuccess(data))
+        return
+      }
+
+      this.sendJson(response, 404, safeError(new BridgeError('NotFound', 'Route not found', { status: 404 })))
+    } catch (error) {
+      const bridgeError = toBridgeError(error)
+      this.sendJson(response, bridgeError.status, safeError(bridgeError))
+    }
+  }
+
+  private assertAuthorized(request: IncomingMessage) {
+    if (!this.token) {
+      return
+    }
+
+    const authorization = request.headers.authorization
+    const provided = authorization?.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined
+
+    if (!provided || !constantTimeEqual(provided, this.token)) {
+      throw new BridgeError('Unauthorized', 'Bridge authentication is required', { status: 401 })
+    }
+  }
+
+  private attachWorkflowWatcher(socket: WebSocket) {
+    const remove = () => this.workflowSubscriptions.delete(socket)
+    socket.on('close', remove)
+    socket.on('error', remove)
+    socket.on('message', (raw) => {
+      const parsedEnvelope = parseEnvelope(raw)
+      if (!parsedEnvelope.success) {
+        socket.close(1007, 'Invalid Workflow watch message')
+        return
+      }
+
+      const request = parsedEnvelope.data
+      if (request.type !== 'workflow.watch') {
+        this.sendWorkflowWatchResult(
+          socket,
+          request.id,
+          safeError(
+            new BridgeError('UnsupportedMessage', 'Only workflow.watch is supported on this socket', {
+              status: 400,
+            }),
+          ),
+        )
+        return
+      }
+
+      const parsedRequest = WorkflowWatchRequestSchema.safeParse(request.data)
+      if (!parsedRequest.success) {
+        this.sendWorkflowWatchResult(
+          socket,
+          request.id,
+          safeError(
+            new BridgeError('InvalidArguments', 'Invalid Workflow watch arguments', {
+              status: 400,
+              details: parsedRequest.error.issues,
+            }),
+          ),
+        )
+        return
+      }
+
+      if (this.workflowSubscriptions.has(socket)) {
+        this.sendWorkflowWatchResult(
+          socket,
+          request.id,
+          safeError(
+            new BridgeError('WorkflowWatchAlreadyStarted', 'This socket is already watching a Workflow', {
+              status: 409,
+            }),
+          ),
+        )
+        return
+      }
+
+      const watchRequest = parsedRequest.data
+      try {
+        const clientId = this.bridge.resolveCommandClientId('workflow.status', watchRequest.clientId)
+        const subscription = { clientId, workflowId: watchRequest.input.workflowId }
+        this.workflowSubscriptions.set(socket, subscription)
+        this.sendWorkflowWatchResult(socket, request.id, safeSuccess(subscription))
+      } catch (error) {
+        this.sendWorkflowWatchResult(socket, request.id, safeError(error))
+      }
+    })
+  }
+
+  private sendWorkflowWatchResult(socket: WebSocket, id: string, data: unknown) {
+    if (socket.readyState === socket.OPEN) {
+      try {
+        socket.send(JSON.stringify(createEnvelope('workflow.watch:res', data, { id, callback: false })))
+      } catch {
+        this.workflowSubscriptions.delete(socket)
+      }
+    }
+  }
+
+  private publishWorkflowStatus(event: BridgeWorkflowStatusEvent) {
+    const envelope = JSON.stringify(createEnvelope('workflow.status', event, { callback: false }))
+    for (const [socket, subscription] of this.workflowSubscriptions) {
+      if (socket.readyState === socket.OPEN && subscriptionKey(subscription) === subscriptionKey(event)) {
+        try {
+          socket.send(envelope)
+        } catch {
+          this.workflowSubscriptions.delete(socket)
+        }
+      }
+    }
+  }
+
+  private getOrigin(request: IncomingMessage) {
+    const host = request.headers.host || `${this.host}:${this.port || DEFAULT_PORT}`
+    return `${this.tls ? 'https' : 'http'}://${host}`
+  }
+
+  private applyCors(request: IncomingMessage, response: ServerResponse) {
+    const origin = request.headers.origin
+    if (!origin) return true
+
+    const allowsAnyOrigin = this.corsOrigins.includes('*')
+    let allowedOrigin: string
+    if (allowsAnyOrigin) {
+      allowedOrigin = '*'
+    } else {
+      try {
+        allowedOrigin = normalizeCorsOrigin(origin)
+      } catch {
+        return false
+      }
+      if (!this.corsOrigins.includes(allowedOrigin)) return false
+      appendVaryOrigin(response)
+    }
+
+    response.setHeader('Access-Control-Allow-Origin', allowedOrigin)
+    response.setHeader('Access-Control-Allow-Methods', CORS_ALLOWED_METHODS)
+    response.setHeader('Access-Control-Allow-Headers', CORS_ALLOWED_HEADERS)
+    response.setHeader('Access-Control-Expose-Headers', CORS_EXPOSED_HEADERS)
+    response.setHeader('Access-Control-Max-Age', '600')
+    return true
+  }
+
+  private sendJson(response: ServerResponse, status: number, body: unknown) {
+    const payload = JSON.stringify(body)
+    response.statusCode = status
+    response.setHeader('Content-Type', 'application/json; charset=utf-8')
+    response.setHeader('Content-Length', Buffer.byteLength(payload))
+    response.end(payload)
+  }
+}
+
+function normalizeCorsOrigins(origins: string[]) {
+  const normalized = [...new Set(origins.map(normalizeCorsOrigin))]
+  return normalized.includes('*') ? ['*'] : normalized
+}
+
+function normalizeCorsOrigin(origin: string) {
+  const value = origin.trim()
+  if (value === '*') return value
+
+  try {
+    const url = new URL(value)
+    if (!url.protocol || !url.host || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+      throw new Error('Expected an origin without a path, query, or fragment')
+    }
+    return url.origin === 'null' ? `${url.protocol}//${url.host}` : url.origin
+  } catch (error) {
+    throw new BridgeError('InvalidCorsOrigin', `Invalid CORS origin: ${origin}`, {
+      status: 400,
+      cause: error,
+    })
+  }
+}
+
+function appendVaryOrigin(response: ServerResponse) {
+  const existing = response.getHeader('Vary')
+  const values = (Array.isArray(existing) ? existing.join(',') : existing?.toString() || '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean)
+  if (!values.some((value) => value.toLowerCase() === 'origin')) {
+    values.push('Origin')
+  }
+  response.setHeader('Vary', values.join(', '))
+}
+
+function subscriptionKey(subscription: WorkflowSubscription | BridgeWorkflowStatusEvent) {
+  return `${subscription.clientId}\u0000${subscription.workflowId}`
+}
+
+function rejectUpgrade(socket: import('node:stream').Duplex, error: BridgeError) {
+  const body = JSON.stringify(safeError(error))
+  const statusMessage = error.status === 401 ? 'Unauthorized' : 'Forbidden'
+  socket.write(
+    `HTTP/1.1 ${error.status} ${statusMessage}\r\nConnection: close\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`,
+  )
+  socket.destroy()
+}
+
+function listen(server: NodeServer, host: string, port: number) {
+  return new Promise<number>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off('listening', onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      server.off('error', onError)
+      const address = server.address()
+      if (!address || typeof address === 'string') {
+        reject(new BridgeError('InvalidServerAddress', 'Cannot read the Bridge server address', { status: 500 }))
+        return
+      }
+      resolve(address.port)
+    }
+
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(port, host)
+  })
+}
+
+function closeServer(server: NodeServer | undefined) {
+  if (!server || !server.listening) {
+    return Promise.resolve()
+  }
+
+  return new Promise<void>((resolve) => {
+    server.close(() => resolve())
+  })
+}
+
+function closeWebSocketServer(server: WebSocketServer | undefined) {
+  if (!server) {
+    return Promise.resolve()
+  }
+
+  return new Promise<void>((resolve) => {
+    server.close(() => resolve())
+  })
+}
+
+function isAddressInUseError(error: unknown): error is NodeJS.ErrnoException {
+  return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EADDRINUSE')
+}
+
+function isLoopbackHost(host: string) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1'
+}
+
+function constantTimeEqual(left: string, right: string) {
+  const leftBuffer = Buffer.from(left)
+  const rightBuffer = Buffer.from(right)
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer)
+}
+
+async function readJson(request: IncomingMessage) {
+  const body = await readBody(request)
+
+  try {
+    return JSON.parse(body) as unknown
+  } catch (error) {
+    throw new BridgeError('InvalidJson', 'Request body is not valid JSON', {
+      status: 400,
+      cause: error,
+    })
+  }
+}
+
+function readBody(request: IncomingMessage) {
+  const maxBytes = 1_048_576
+
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let totalBytes = 0
+
+    request.on('data', (chunk: Buffer | string) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      totalBytes += buffer.length
+      if (totalBytes > maxBytes) {
+        reject(new BridgeError('RequestTooLarge', 'Request body exceeds 1 MiB', { status: 413 }))
+        request.destroy()
+        return
+      }
+      chunks.push(buffer)
+    })
+    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    request.on('error', reject)
+  })
+}