thatcher 1.0.4

package/src/lib/state-protocol.js

@@ -0,0 +1,171 @@
+const MESSAGE_TYPES = {
+  STATE_UPDATE: 'state_update',
+  STATE_SNAPSHOT: 'state_snapshot',
+  STATE_REQUEST: 'state_request',
+  STATE_ACK: 'state_ack',
+  STATE_NACK: 'state_nack',
+  PING: 'ping',
+  PONG: 'pong'
+}
+
+const ERROR_CODES = {
+  INVALID_MESSAGE: 'invalid_message',
+  INVALID_VERSION: 'invalid_version',
+  CONFLICT_DETECTED: 'conflict_detected',
+  RATE_LIMITED: 'rate_limited',
+  VALIDATION_FAILED: 'validation_failed'
+}
+
+class VectorClock {
+  constructor(nodeId) {
+    this.nodeId = nodeId
+    this.clock = { [nodeId]: 0 }
+  }
+
+  increment() {
+    this.clock[this.nodeId] = (this.clock[this.nodeId] || 0) + 1
+    return this.clock[this.nodeId]
+  }
+
+  update(otherClock) {
+    for (const [nodeId, timestamp] of Object.entries(otherClock)) {
+      this.clock[nodeId] = Math.max(this.clock[nodeId] || 0, timestamp)
+    }
+  }
+
+  compare(otherClock) {
+    const keys = new Set([...Object.keys(this.clock), ...Object.keys(otherClock)])
+    let hasGreater = false
+    let hasLess = false
+
+    for (const key of keys) {
+      const mine = this.clock[key] || 0
+      const theirs = otherClock[key] || 0
+      if (mine > theirs) hasGreater = true
+      if (mine < theirs) hasLess = true
+    }
+
+    if (hasGreater && !hasLess) return 1
+    if (hasLess && !hasGreater) return -1
+    if (!hasGreater && !hasLess) return 0
+    return null // Concurrent
+  }
+
+  serialize() {
+    return { ...this.clock }
+  }
+
+  static deserialize(data, nodeId) {
+    const vc = new VectorClock(nodeId)
+    vc.clock = { ...data }
+    return vc
+  }
+}
+
+const MessageSchema = {
+  validate(message) {
+    if (!message || typeof message !== 'object') {
+      return { valid: false, error: 'Message must be an object' }
+    }
+    const validTypes = Object.values(MESSAGE_TYPES)
+    if (!validTypes.includes(message.type)) {
+      return { valid: false, error: 'Invalid message type' }
+    }
+    if (message.type !== MESSAGE_TYPES.PING && message.type !== MESSAGE_TYPES.PONG) {
+      if (!message.version || typeof message.version !== 'object') {
+        return { valid: false, error: 'Missing or invalid version vector' }
+      }
+    }
+    if (message.type === MESSAGE_TYPES.STATE_UPDATE || message.type === MESSAGE_TYPES.STATE_SNAPSHOT) {
+      if (message.data === undefined) {
+        return { valid: false, error: 'Missing data field' }
+      }
+    }
+    return { valid: true }
+  }
+}
+
+function createMessage(type, payload = {}) {
+  return {
+    type,
+    timestamp: Date.now(),
+    ...payload
+  }
+}
+
+function createStateUpdate(vectorClock, data, operations = []) {
+  return createMessage(MESSAGE_TYPES.STATE_UPDATE, {
+    version: vectorClock.serialize(),
+    data,
+    operations
+  })
+}
+
+function createStateSnapshot(vectorClock, data) {
+  return createMessage(MESSAGE_TYPES.STATE_SNAPSHOT, {
+    version: vectorClock.serialize(),
+    data
+  })
+}
+
+function createStateRequest(vectorClock) {
+  return createMessage(MESSAGE_TYPES.STATE_REQUEST, {
+    version: vectorClock.serialize()
+  })
+}
+
+function createStateAck(messageId, vectorClock) {
+  return createMessage(MESSAGE_TYPES.STATE_ACK, {
+    messageId,
+    version: vectorClock.serialize()
+  })
+}
+
+function createStateNack(messageId, error, errorCode) {
+  return createMessage(MESSAGE_TYPES.STATE_NACK, {
+    messageId,
+    error,
+    errorCode
+  })
+}
+
+function createPing() {
+  return createMessage(MESSAGE_TYPES.PING)
+}
+
+function createPong(pingTimestamp) {
+  return createMessage(MESSAGE_TYPES.PONG, { pingTimestamp })
+}
+
+const Protocol = {
+  MESSAGE_TYPES,
+  ERROR_CODES,
+  VectorClock,
+  MessageSchema,
+  createMessage,
+  createStateUpdate,
+  createStateSnapshot,
+  createStateRequest,
+  createStateAck,
+  createStateNack,
+  createPing,
+  createPong
+}
+
+export {
+  MESSAGE_TYPES,
+  ERROR_CODES,
+  VectorClock,
+  MessageSchema,
+  createMessage,
+  createStateUpdate,
+  createStateSnapshot,
+  createStateRequest,
+  createStateAck,
+  createStateNack,
+  createPing,
+  createPong,
+  Protocol
+}
+
+export default Protocol

package/src/lib/state-transport-client.js

@@ -0,0 +1,169 @@
+import Protocol from './state-protocol.js'
+import { CONFIG, ReconnectManager } from './state-transport-reconnect.js'
+
+class StateTransportClient {
+  constructor(config = {}) {
+    this.config = { ...CONFIG, ...config }
+    this.ws = null
+    this.state = 'disconnected'
+    this.listeners = new Map()
+    this.messageQueue = []
+    this.connectionTimeoutTimer = null
+
+    this.reconnect = new ReconnectManager(this.config, {
+      onReconnecting: (data) => { this.emit('reconnecting', data); this.connect() },
+      onFallback: (msg) => this.emit('fallback', msg),
+      onPollStart: () => this.emit('poll_start'),
+      onPollSuccess: (result) => this.emit('poll_success', result),
+      onPollError: (error) => this.emit('poll_error', error)
+    })
+  }
+
+  connect(url) {
+    this.url = url || this.url
+    if (!this.url) {
+      this.emit('error', new Error('No URL provided for connection'))
+      return
+    }
+    this.reconnect.wsUrl = this.url
+
+    if (this.state === 'connecting' || this.state === 'connected') return
+
+    this.state = 'connecting'
+    this.emit('connecting')
+
+    try {
+      this.ws = new WebSocket(this.url)
+
+      this.connectionTimeoutTimer = setTimeout(() => {
+        if (this.state === 'connecting') this.handleConnectionTimeout()
+      }, this.config.connectionTimeout)
+
+      this.ws.onopen = () => this.handleOpen()
+      this.ws.onclose = (event) => this.handleClose(event)
+      this.ws.onerror = (error) => this.handleError(error)
+      this.ws.onmessage = (event) => this.handleMessage(event)
+    } catch (error) {
+      this.handleConnectionFailure(error)
+    }
+  }
+
+  handleOpen() {
+    clearTimeout(this.connectionTimeoutTimer)
+    this.state = 'connected'
+    this.reconnect.resetAttempts()
+    this.emit('connected')
+    this.reconnect.startPingInterval(
+      (msg) => this.send(msg),
+      () => this.ws.close()
+    )
+    this.flushMessageQueue()
+    this.reconnect.stopPolling()
+  }
+
+  handleClose(event) {
+    clearTimeout(this.connectionTimeoutTimer)
+    this.state = 'disconnected'
+    this.reconnect.stopPingInterval()
+    this.emit('disconnected', { code: event.code, reason: event.reason })
+    this.reconnect.scheduleReconnect()
+  }
+
+  handleError(error) {
+    this.emit('error', error)
+  }
+
+  handleConnectionTimeout() {
+    if (this.ws) this.ws.close()
+    this.handleConnectionFailure(new Error('Connection timeout'))
+  }
+
+  handleConnectionFailure(error) {
+    this.emit('error', error)
+    this.state = 'disconnected'
+
+    if (this.reconnect.shouldFallback) {
+      this.reconnect.activateFallback()
+    } else {
+      this.reconnect.scheduleReconnect()
+    }
+  }
+
+  handleMessage(event) {
+    try {
+      const message = JSON.parse(event.data)
+      if (message.type === Protocol.MESSAGE_TYPES.PONG) {
+        this.reconnect.recordPong()
+        return
+      }
+      this.emit('message', message)
+    } catch (error) {
+      this.emit('error', { error, phase: 'message_parsing', data: event.data })
+    }
+  }
+
+  send(message) {
+    if (this.state === 'connected' && this.ws && this.ws.readyState === WebSocket.OPEN) {
+      try {
+        this.ws.send(JSON.stringify(message))
+        return true
+      } catch (error) {
+        this.emit('error', { error, phase: 'send' })
+        this.messageQueue.push(message)
+        return false
+      }
+    }
+    this.messageQueue.push(message)
+    return false
+  }
+
+  flushMessageQueue() {
+    while (this.messageQueue.length > 0 && this.state === 'connected') {
+      const message = this.messageQueue.shift()
+      this.send(message)
+    }
+  }
+
+  disconnect() {
+    this.reconnect.cleanup()
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+    this.state = 'disconnected'
+  }
+
+  on(event, handler) {
+    if (!this.listeners.has(event)) this.listeners.set(event, [])
+    this.listeners.get(event).push(handler)
+  }
+
+  off(event, handler) {
+    if (!this.listeners.has(event)) return
+    const handlers = this.listeners.get(event)
+    const index = handlers.indexOf(handler)
+    if (index > -1) handlers.splice(index, 1)
+  }
+
+  emit(event, data) {
+    if (!this.listeners.has(event)) return
+    for (const handler of this.listeners.get(event)) {
+      try {
+        handler(data)
+      } catch (error) {
+        console.error(`Error in event handler for ${event}:`, error)
+      }
+    }
+  }
+
+  getState() {
+    return this.state
+  }
+
+  isConnected() {
+    return this.state === 'connected'
+  }
+}
+
+export { StateTransportClient }
+export default StateTransportClient

package/src/lib/state-transport-reconnect.js

@@ -0,0 +1,121 @@
+import Protocol from './state-protocol.js'
+
+const CONFIG = {
+  reconnectInitialDelay: 1000,
+  reconnectMaxDelay: 30000,
+  reconnectBackoffFactor: 2,
+  pingInterval: 25000,
+  connectionTimeout: 10000,
+  pollingInterval: 5000,
+  pollingFallbackDelay: 3000
+}
+
+class ReconnectManager {
+  constructor(config, callbacks) {
+    this.config = config
+    this.callbacks = callbacks
+    this.reconnectAttempts = 0
+    this.reconnectTimer = null
+    this.pingTimer = null
+    this.pollingTimer = null
+    this.lastPongTime = 0
+    this.useFallback = false
+    this.wsUrl = null
+  }
+
+  get shouldFallback() {
+    return this.reconnectAttempts >= 3 && !this.useFallback
+  }
+
+  resetAttempts() {
+    this.reconnectAttempts = 0
+    this.useFallback = false
+  }
+
+  recordPong() {
+    this.lastPongTime = Date.now()
+  }
+
+  scheduleReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+    }
+
+    const delay = Math.min(
+      this.config.reconnectInitialDelay * Math.pow(this.config.reconnectBackoffFactor, this.reconnectAttempts),
+      this.config.reconnectMaxDelay
+    )
+
+    const jitter = Math.random() * 1000
+    this.reconnectAttempts++
+
+    this.reconnectTimer = setTimeout(() => {
+      this.callbacks.onReconnecting({ attempt: this.reconnectAttempts })
+    }, delay + jitter)
+  }
+
+  activateFallback() {
+    this.useFallback = true
+    this.callbacks.onFallback('Switching to polling mode')
+    this.startPolling()
+  }
+
+  startPolling() {
+    if (this.pollingTimer) return
+
+    this.pollingTimer = setInterval(async () => {
+      try {
+        this.callbacks.onPollStart()
+        const result = await this.pollState()
+        this.callbacks.onPollSuccess(result)
+      } catch (error) {
+        this.callbacks.onPollError(error)
+      }
+    }, this.config.pollingInterval)
+  }
+
+  async pollState() {
+    const httpUrl = this.wsUrl.replace('ws://', 'http://').replace('wss://', 'https://')
+    const response = await fetch(`${httpUrl}/poll`)
+    if (!response.ok) {
+      throw new Error(`Polling failed: ${response.status}`)
+    }
+    return await response.json()
+  }
+
+  startPingInterval(sendFn, closeFn) {
+    this.pingTimer = setInterval(() => {
+      sendFn(Protocol.createPing())
+      const timeSinceLastPong = Date.now() - this.lastPongTime
+      if (timeSinceLastPong > this.config.pingInterval * 2) {
+        closeFn()
+      }
+    }, this.config.pingInterval)
+  }
+
+  stopPingInterval() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer)
+      this.pingTimer = null
+    }
+  }
+
+  stopPolling() {
+    if (this.pollingTimer) {
+      clearInterval(this.pollingTimer)
+      this.pollingTimer = null
+    }
+  }
+
+  cleanup() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    this.stopPolling()
+    this.stopPingInterval()
+  }
+}
+
+export { CONFIG, ReconnectManager }
+export default ReconnectManager

package/src/lib/state-transport-server.js

@@ -0,0 +1,181 @@
+import { WebSocketServer } from 'ws'
+import { EventEmitter } from 'events'
+import Protocol from '@/lib/state-protocol.js'
+import ConnectionGuard from '@/lib/connection-guard.js'
+
+const CONFIG = {
+  pingInterval: 30000,
+  connectionTimeout: 60000,
+  maxConnectionsPerIP: 10,
+  messageRateLimit: 100
+}
+
+class StateTransportServer extends EventEmitter {
+  constructor(server, config = {}) {
+    super()
+    this.config = { ...CONFIG, ...config }
+    this.wss = null
+    this.clients = new Map()
+    this.server = server
+    this.guard = new ConnectionGuard(this.config)
+    this.setupServer()
+  }
+
+  setupServer() {
+    try {
+      this.wss = new WebSocketServer({ server: this.server, path: '/state-sync' })
+      this.wss.on('connection', (ws, req) => this.handleConnection(ws, req))
+      this.wss.on('error', (error) => this.handleError(error))
+      this.guard.startPingInterval(this.clients, (id) => this.handleClose(id))
+      this.emit('ready')
+    } catch (error) {
+      this.emit('error', error)
+      setTimeout(() => this.setupServer(), 5000)
+    }
+  }
+
+  handleConnection(ws, req) {
+    const clientId = this.guard.generateClientId()
+    const ip = req.socket.remoteAddress
+
+    if (!this.guard.checkConnectionLimit(ip)) {
+      ws.close(1008, 'Too many connections from this IP')
+      return
+    }
+
+    const client = {
+      id: clientId,
+      ws,
+      ip,
+      alive: true,
+      connectedAt: Date.now(),
+      messageCount: 0
+    }
+
+    this.clients.set(clientId, client)
+    this.guard.trackIPConnection(ip)
+
+    ws.on('message', (data) => this.handleMessage(clientId, data))
+    ws.on('close', () => this.handleClose(clientId))
+    ws.on('error', (error) => this.handleClientError(clientId, error))
+    ws.on('pong', () => { client.alive = true })
+
+    this.emit('client_connected', clientId)
+  }
+
+  handleMessage(clientId, data) {
+    try {
+      const client = this.clients.get(clientId)
+      if (!client) return
+
+      if (!this.guard.checkRateLimit(clientId)) {
+        this.sendMessage(clientId, Protocol.createStateNack(
+          null,
+          'Rate limit exceeded',
+          Protocol.ERROR_CODES.RATE_LIMITED
+        ))
+        return
+      }
+
+      const message = JSON.parse(data.toString())
+      const validation = Protocol.MessageSchema.validate(message)
+
+      if (!validation.valid) {
+        this.sendMessage(clientId, Protocol.createStateNack(
+          message.id,
+          validation.error,
+          Protocol.ERROR_CODES.INVALID_MESSAGE
+        ))
+        return
+      }
+
+      client.messageCount++
+      this.emit('message', clientId, message)
+
+      if (message.type === Protocol.MESSAGE_TYPES.PING) {
+        this.sendMessage(clientId, Protocol.createPong(message.timestamp))
+      }
+    } catch (error) {
+      this.emit('error', { clientId, error, phase: 'message_handling' })
+    }
+  }
+
+  handleClose(clientId) {
+    const client = this.clients.get(clientId)
+    if (client) {
+      this.guard.untrackIPConnection(client.ip)
+      this.clients.delete(clientId)
+      this.guard.clearRateLimit(clientId)
+      this.emit('client_disconnected', clientId)
+    }
+  }
+
+  handleClientError(clientId, error) {
+    this.emit('error', { clientId, error, phase: 'client_error' })
+  }
+
+  handleError(error) {
+    this.emit('error', { error, phase: 'server_error' })
+  }
+
+  sendMessage(clientId, message) {
+    try {
+      const client = this.clients.get(clientId)
+      if (client && client.ws.readyState === 1) {
+        client.ws.send(JSON.stringify(message))
+        return true
+      }
+      return false
+    } catch (error) {
+      this.emit('error', { clientId, error, phase: 'send_message' })
+      return false
+    }
+  }
+
+  broadcast(message, excludeClientId = null) {
+    const results = { sent: 0, failed: 0 }
+    for (const [clientId] of this.clients) {
+      if (clientId === excludeClientId) continue
+      if (this.sendMessage(clientId, message)) {
+        results.sent++
+      } else {
+        results.failed++
+      }
+    }
+    return results
+  }
+
+  getClientCount() {
+    return this.clients.size
+  }
+
+  getClient(clientId) {
+    return this.clients.get(clientId)
+  }
+
+  close() {
+    this.guard.destroy()
+    for (const client of this.clients.values()) {
+      client.ws.close()
+    }
+    this.clients.clear()
+    if (this.wss) {
+      this.wss.close()
+    }
+  }
+}
+
+if (!global.stateTransportServer) {
+  global.stateTransportServer = null
+}
+
+export function createStateTransportServer(server, config) {
+  if (global.stateTransportServer) {
+    global.stateTransportServer.close()
+  }
+  global.stateTransportServer = new StateTransportServer(server, config)
+  return global.stateTransportServer
+}
+
+export { StateTransportServer }
+export default StateTransportServer