pywire 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

pywire/client/src/core/transport-manager.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { TransportManager } from './transport-manager'
+import { WebTransportTransport } from './transports/webtransport'
+import { WebSocketTransport } from './transports/websocket'
+import { HTTPTransport } from './transports/http'
+
+// Create mock classes that can be used in the tests
+class MockWebTransport {
+  static isSupported = vi.fn(() => true)
+  connect = vi.fn().mockResolvedValue(undefined)
+  onMessage = vi.fn()
+  onStatusChange = vi.fn()
+  isConnected = vi.fn(() => false)
+  send = vi.fn()
+  disconnect = vi.fn()
+  name = 'WebTransportTransport'
+}
+
+class MockWebSocket {
+  connect = vi.fn().mockResolvedValue(undefined)
+  onMessage = vi.fn()
+  onStatusChange = vi.fn()
+  isConnected = vi.fn(() => false)
+  send = vi.fn()
+  disconnect = vi.fn()
+  name = 'WebSocketTransport'
+}
+
+class MockHTTP {
+  connect = vi.fn().mockResolvedValue(undefined)
+  onMessage = vi.fn()
+  onStatusChange = vi.fn()
+  isConnected = vi.fn(() => false)
+  send = vi.fn()
+  disconnect = vi.fn()
+  name = 'HTTPTransport'
+}
+
+vi.mock('./transports/webtransport', () => ({
+  WebTransportTransport: vi.fn(),
+}))
+
+vi.mock('./transports/websocket', () => ({
+  WebSocketTransport: vi.fn(),
+}))
+
+vi.mock('./transports/http', () => ({
+  HTTPTransport: vi.fn(),
+}))
+
+type MockedTransportCtor = {
+  mockImplementation: (impl: new (...args: unknown[]) => unknown) => void
+}
+
+type MockedWebTransportCtor = MockedTransportCtor & {
+  isSupported: ReturnType<typeof vi.fn>
+}
+
+const WebTransportMock = WebTransportTransport as unknown as MockedWebTransportCtor
+const WebSocketMock = WebSocketTransport as unknown as MockedTransportCtor
+const HTTPMock = HTTPTransport as unknown as MockedTransportCtor
+
+// Set static properties on the mocked constructors
+WebTransportMock.isSupported = MockWebTransport.isSupported
+Object.defineProperty(WebTransportTransport, 'name', { value: 'WebTransportTransport' })
+Object.defineProperty(WebSocketTransport, 'name', { value: 'WebSocketTransport' })
+Object.defineProperty(HTTPTransport, 'name', { value: 'HTTPTransport' })
+
+describe('TransportManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    // Default mock implementations (successful connect)
+    WebTransportMock.mockImplementation(MockWebTransport)
+    WebSocketMock.mockImplementation(MockWebSocket)
+    HTTPMock.mockImplementation(MockHTTP)
+
+    vi.stubGlobal('location', { protocol: 'https:' })
+    vi.stubGlobal('WebSocket', vi.fn())
+    WebTransportMock.isSupported.mockReturnValue(true)
+  })
+
+  it('should try WebTransport first if supported and on HTTPS', async () => {
+    const manager = new TransportManager()
+    await manager.connect()
+
+    expect(WebTransportTransport).toHaveBeenCalled()
+    expect(manager.getActiveTransport()).toBe('WebTransportTransport')
+  })
+
+  it('should fallback to WebSocket if WebTransport fails', async () => {
+    WebTransportMock.mockImplementation(
+      class extends MockWebTransport {
+        connect = vi.fn().mockRejectedValue(new Error('WT failed'))
+      }
+    )
+
+    const manager = new TransportManager()
+    await manager.connect()
+
+    expect(WebTransportTransport).toHaveBeenCalled()
+    expect(WebSocketTransport).toHaveBeenCalled()
+    expect(manager.getActiveTransport()).toBe('WebSocketTransport')
+  })
+
+  it('should fallback to HTTP if WebSocket fails', async () => {
+    WebTransportMock.mockImplementation(
+      class extends MockWebTransport {
+        connect = vi.fn().mockRejectedValue(new Error('WT failed'))
+      }
+    )
+    WebSocketMock.mockImplementation(
+      class extends MockWebSocket {
+        connect = vi.fn().mockRejectedValue(new Error('WS failed'))
+      }
+    )
+
+    const manager = new TransportManager()
+    await manager.connect()
+
+    expect(HTTPTransport).toHaveBeenCalled()
+    expect(manager.getActiveTransport()).toBe('HTTPTransport')
+  })
+
+  it('should skip WebTransport if not on HTTPS', async () => {
+    vi.stubGlobal('location', { protocol: 'http:' })
+    const manager = new TransportManager()
+    await manager.connect()
+
+    expect(WebTransportTransport).not.toHaveBeenCalled()
+    expect(WebSocketTransport).toHaveBeenCalled()
+  })
+
+  it('should respect config to disable transports', async () => {
+    const manager = new TransportManager({ enableWebTransport: false })
+    await manager.connect()
+
+    expect(WebTransportTransport).not.toHaveBeenCalled()
+    expect(WebSocketTransport).toHaveBeenCalled()
+  })
+
+  it('should throw if all transports fail', async () => {
+    WebTransportMock.mockImplementation(
+      class extends MockWebTransport {
+        connect = vi.fn().mockRejectedValue(new Error('WT failed'))
+      }
+    )
+    WebSocketMock.mockImplementation(
+      class extends MockWebSocket {
+        connect = vi.fn().mockRejectedValue(new Error('WS failed'))
+      }
+    )
+    HTTPMock.mockImplementation(
+      class extends MockHTTP {
+        connect = vi.fn().mockRejectedValue(new Error('HTTP failed'))
+      }
+    )
+
+    const manager = new TransportManager()
+    await expect(manager.connect()).rejects.toThrow('PyWire: All transports failed')
+  })
+
+  it('should forward messages to registered handlers', async () => {
+    const onMessageSpy = vi.fn()
+    WebTransportMock.mockImplementation(
+      class extends MockWebTransport {
+        onMessage = onMessageSpy
+      }
+    )
+
+    const manager = new TransportManager()
+    const handler = vi.fn()
+    manager.onMessage(handler)
+
+    await manager.connect()
+
+    expect(onMessageSpy).toHaveBeenCalledWith(handler)
+  })
+})

pywire/client/src/core/transport-manager.ts

@@ -0,0 +1,159 @@
+import { Transport, ServerMessage } from './transports'
+import { WebTransportTransport } from './transports/webtransport'
+import { WebSocketTransport } from './transports/websocket'
+import { HTTPTransport } from './transports/http'
+
+export interface TransportConfig {
+  /** Enable WebTransport (requires HTTPS and HTTP/3 server) */
+  enableWebTransport?: boolean
+  /** Enable WebSocket */
+  enableWebSocket?: boolean
+  /** Enable HTTP polling fallback */
+  enableHTTP?: boolean
+  /** Custom WebTransport URL */
+  webTransportUrl?: string
+  /** Custom WebSocket URL */
+  webSocketUrl?: string
+  /** Custom HTTP base URL */
+  httpUrl?: string
+}
+
+const DEFAULT_CONFIG: TransportConfig = {
+  enableWebTransport: true,
+  enableWebSocket: true,
+  enableHTTP: true,
+}
+
+/**
+ * Manages transport selection with automatic fallback.
+ * Tries transports in order: WebTransport → WebSocket → HTTP
+ */
+export class TransportManager {
+  private transport: Transport | null = null
+  private config: TransportConfig
+  private messageHandlers: ((msg: ServerMessage) => void)[] = []
+  private statusHandlers: ((connected: boolean) => void)[] = []
+
+  constructor(config: Partial<TransportConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  /**
+   * Connect using the best available transport with fallback.
+   */
+  async connect(): Promise<void> {
+    const transports = this.getTransportPriority()
+
+    for (const TransportClass of transports) {
+      try {
+        console.log(`PyWire: Trying ${TransportClass.name}...`)
+        this.transport = new TransportClass()
+
+        // Forward message handlers
+        for (const handler of this.messageHandlers) {
+          this.transport.onMessage(handler)
+        }
+
+        // Forward status changes
+        this.transport.onStatusChange((connected) => {
+          this.notifyStatusHandlers(connected)
+        })
+
+        await this.transport.connect()
+        console.log(`PyWire: Connected via ${this.transport.name}`)
+        return
+      } catch (e) {
+        console.warn(`PyWire: ${TransportClass.name} failed, trying next...`, e)
+        this.transport = null
+      }
+    }
+
+    throw new Error('PyWire: All transports failed')
+  }
+
+  /**
+   * Get transport classes in priority order based on config and browser support.
+   */
+  private getTransportPriority(): (new (...args: unknown[]) => Transport)[] {
+    const transports: (new (...args: unknown[]) => Transport)[] = []
+
+    // WebTransport - only if supported and enabled
+    if (this.config.enableWebTransport && WebTransportTransport.isSupported()) {
+      // Also check if we're on HTTPS (required for WebTransport)
+      if (window.location.protocol === 'https:') {
+        transports.push(WebTransportTransport as unknown as new (...args: unknown[]) => Transport)
+      }
+    }
+
+    // WebSocket
+    if (this.config.enableWebSocket && typeof WebSocket !== 'undefined') {
+      transports.push(WebSocketTransport as unknown as new (...args: unknown[]) => Transport)
+    }
+
+    // HTTP (always available as final fallback)
+    if (this.config.enableHTTP) {
+      transports.push(HTTPTransport as unknown as new (...args: unknown[]) => Transport)
+    }
+
+    return transports
+  }
+
+  /**
+   * Send a message through the active transport.
+   */
+  send(message: object): void {
+    if (this.transport) {
+      this.transport.send(message)
+    } else {
+      console.warn('PyWire: No active transport')
+    }
+  }
+
+  /**
+   * Register a message handler.
+   */
+  onMessage(handler: (msg: ServerMessage) => void): void {
+    this.messageHandlers.push(handler)
+    if (this.transport) {
+      this.transport.onMessage(handler)
+    }
+  }
+
+  /**
+   * Register a connection status change handler.
+   */
+  onStatusChange(handler: (connected: boolean) => void): void {
+    this.statusHandlers.push(handler)
+  }
+
+  private notifyStatusHandlers(connected: boolean): void {
+    for (const handler of this.statusHandlers) {
+      handler(connected)
+    }
+  }
+
+  /**
+   * Disconnect the active transport.
+   */
+  disconnect(): void {
+    if (this.transport) {
+      this.transport.disconnect()
+      this.transport = null
+      this.notifyStatusHandlers(false)
+    }
+  }
+
+  /**
+   * Get the name of the active transport.
+   */
+  getActiveTransport(): string | null {
+    return this.transport?.name || null
+  }
+
+  /**
+   * Check if connected.
+   */
+  isConnected(): boolean {
+    return this.transport?.isConnected() || false
+  }
+}

pywire/client/src/core/transports/base.ts

@@ -0,0 +1,122 @@
+/**
+ * Base transport interface for all transport implementations.
+ */
+export interface Transport {
+  /** Connect to the server */
+  connect(): Promise<void>
+
+  /** Send a message to the server */
+  send(message: object): void
+
+  /** Register a message handler */
+  onMessage(handler: MessageHandler): void
+
+  /** Register a status change handler */
+  onStatusChange(handler: (connected: boolean) => void): void
+
+  /** Disconnect from the server */
+  disconnect(): void
+
+  /** Check if connected */
+  isConnected(): boolean
+
+  /** Transport name for debugging */
+  readonly name: string
+}
+
+export type MessageHandler = (message: ServerMessage) => void
+
+export interface StackFrame {
+  filename: string
+  lineno: number
+  name: string
+  line: string
+  colno?: number // Python 3.11+ column start
+  end_colno?: number // Python 3.11+ column end
+}
+
+export interface ServerMessage {
+  type: 'update' | 'reload' | 'error' | 'console' | 'error_trace'
+  html?: string
+  regions?: Array<{ region: string; html: string }>
+  error?: string
+  level?: 'info' | 'warn' | 'error'
+  lines?: string[]
+  trace?: StackFrame[]
+}
+
+export interface ConsoleMessage {
+  type: 'console'
+  level: 'info' | 'warn' | 'error'
+  lines: string[]
+}
+
+export type ClientMessage = EventMessage | RelocateMessage
+
+export interface EventMessage {
+  type: 'event'
+  handler: string
+  path: string
+  data: EventData
+}
+
+export interface RelocateMessage {
+  type: 'relocate'
+  path: string
+}
+
+export interface EventData {
+  type: string
+  id?: string
+  value?: string
+  args?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/**
+ * Abstract base class providing common transport functionality.
+ */
+export abstract class BaseTransport implements Transport {
+  protected messageHandlers: MessageHandler[] = []
+  protected statusHandlers: ((connected: boolean) => void)[] = []
+  protected connected = false
+
+  abstract readonly name: string
+  abstract connect(): Promise<void>
+  abstract send(message: object): void
+  abstract disconnect(): void
+
+  onMessage(handler: MessageHandler): void {
+    this.messageHandlers.push(handler)
+  }
+
+  onStatusChange(handler: (connected: boolean) => void): void {
+    this.statusHandlers.push(handler)
+  }
+
+  isConnected(): boolean {
+    return this.connected
+  }
+
+  protected notifyHandlers(message: ServerMessage): void {
+    for (const handler of this.messageHandlers) {
+      try {
+        handler(message)
+      } catch (e) {
+        console.error('PyWire: Error in message handler', e)
+      }
+    }
+  }
+
+  protected notifyStatus(connected: boolean): void {
+    if (this.connected === connected) return
+    this.connected = connected
+    for (const handler of this.statusHandlers) {
+      try {
+        handler(connected)
+      } catch (e) {
+        console.error('PyWire: Error in status handler', e)
+      }
+    }
+  }
+}

pywire/client/src/core/transports/http.ts

@@ -0,0 +1,142 @@
+import { BaseTransport, ServerMessage } from './base'
+import { encode, decode } from '@msgpack/msgpack'
+
+/**
+ * HTTP polling transport as a fallback when WebTransport and WebSocket are unavailable.
+ * Uses long-polling for receiving updates and POST for sending events.
+ */
+export class HTTPTransport extends BaseTransport {
+  readonly name = 'HTTP'
+
+  private polling = false
+  private pollAbortController: AbortController | null = null
+  private readonly baseUrl: string
+  private sessionId: string | null = null
+
+  constructor(baseUrl?: string) {
+    super()
+    this.baseUrl = baseUrl || `${window.location.origin}/_pywire`
+  }
+
+  async connect(): Promise<void> {
+    try {
+      // Initialize session with the server
+      const response = await fetch(`${this.baseUrl}/session`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-msgpack',
+          Accept: 'application/x-msgpack',
+        },
+        body: encode({ path: window.location.pathname + window.location.search }),
+      })
+
+      if (!response.ok) {
+        throw new Error(`HTTP session init failed: ${response.status}`)
+      }
+
+      const buffer = await response.arrayBuffer()
+      const data = decode(buffer) as { sessionId: string }
+      this.sessionId = data.sessionId
+
+      console.log('PyWire: HTTP transport connected')
+      this.notifyStatus(true)
+
+      // Start polling for updates
+      this.startPolling()
+    } catch (e) {
+      console.error('PyWire: HTTP transport connection failed', e)
+      throw e
+    }
+  }
+
+  private async startPolling(): Promise<void> {
+    if (this.polling) return
+    this.polling = true
+
+    while (this.polling && this.connected) {
+      try {
+        this.pollAbortController = new AbortController()
+
+        const response = await fetch(`${this.baseUrl}/poll?session=${this.sessionId}`, {
+          method: 'GET',
+          signal: this.pollAbortController.signal,
+          headers: {
+            Accept: 'application/x-msgpack',
+          },
+        })
+
+        if (!response.ok) {
+          if (response.status === 404) {
+            // Session expired, try to reconnect
+            console.warn('PyWire: HTTP session expired, reconnecting...')
+            this.notifyStatus(false)
+            await this.connect()
+            return
+          }
+          throw new Error(`Poll failed: ${response.status}`)
+        }
+
+        const buffer = await response.arrayBuffer()
+        const messages = decode(buffer) as ServerMessage[]
+
+        for (const msg of messages) {
+          this.notifyHandlers(msg)
+        }
+      } catch (e) {
+        if (e instanceof Error && e.name === 'AbortError') {
+          // Polling was aborted intentionally
+          break
+        }
+        console.error('PyWire: HTTP poll error', e)
+        // Wait a bit before retrying
+        await this.sleep(1000)
+      }
+    }
+  }
+
+  async send(message: object): Promise<void> {
+    if (!this.connected || !this.sessionId) {
+      console.warn('PyWire: Cannot send message, HTTP transport not connected')
+      return
+    }
+
+    try {
+      const response = await fetch(`${this.baseUrl}/event`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-msgpack',
+          Accept: 'application/x-msgpack',
+          'X-PyWire-Session': this.sessionId,
+        },
+        body: encode(message),
+      })
+
+      if (!response.ok) {
+        throw new Error(`Event send failed: ${response.status}`)
+      }
+
+      // The response contains the updated HTML
+      const buffer = await response.arrayBuffer()
+      const result = decode(buffer) as ServerMessage
+      this.notifyHandlers(result)
+    } catch (e) {
+      console.error('PyWire: HTTP send error', e)
+    }
+  }
+
+  disconnect(): void {
+    this.polling = false
+    this.notifyStatus(false)
+
+    if (this.pollAbortController) {
+      this.pollAbortController.abort()
+      this.pollAbortController = null
+    }
+
+    this.sessionId = null
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}

pywire/client/src/core/transports/index.ts

@@ -0,0 +1,13 @@
+export {
+  Transport,
+  MessageHandler,
+  ServerMessage,
+  ClientMessage,
+  EventMessage,
+  RelocateMessage,
+  EventData,
+  StackFrame,
+} from './base'
+export { WebSocketTransport } from './websocket'
+export { WebTransportTransport } from './webtransport'
+export { HTTPTransport } from './http'

pywire/client/src/core/transports/websocket.ts

@@ -0,0 +1,97 @@
+import { BaseTransport, ServerMessage } from './base'
+import { encode, decode } from '@msgpack/msgpack'
+
+/**
+ * WebSocket transport implementation.
+ */
+export class WebSocketTransport extends BaseTransport {
+  readonly name = 'WebSocket'
+
+  private socket: WebSocket | null = null
+  private reconnectAttempts = 0
+  private maxReconnectDelay = 5000
+  private shouldReconnect = true
+  private readonly url: string
+
+  constructor(url?: string) {
+    super()
+    this.url = url || this.getDefaultUrl()
+  }
+
+  private getDefaultUrl(): string {
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+    return `${protocol}//${window.location.host}/_pywire/ws`
+  }
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.socket = new WebSocket(this.url)
+        this.socket.binaryType = 'arraybuffer'
+
+        this.socket.onopen = () => {
+          console.log('PyWire: WebSocket connected')
+          this.notifyStatus(true)
+          this.reconnectAttempts = 0
+          resolve()
+        }
+
+        this.socket.onmessage = (event: MessageEvent) => {
+          try {
+            const msg = decode(event.data) as ServerMessage
+            this.notifyHandlers(msg)
+          } catch (e) {
+            console.error('PyWire: Error parsing WebSocket message', e)
+          }
+        }
+
+        this.socket.onclose = () => {
+          console.log('PyWire: WebSocket disconnected')
+          this.notifyStatus(false)
+          if (this.shouldReconnect) {
+            this.scheduleReconnect()
+          }
+        }
+
+        this.socket.onerror = (error) => {
+          console.error('PyWire: WebSocket error', error)
+          if (!this.connected) {
+            reject(new Error('WebSocket connection failed'))
+          }
+        }
+      } catch (e) {
+        reject(e)
+      }
+    })
+  }
+
+  send(message: object): void {
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(encode(message))
+    } else {
+      console.warn('PyWire: Cannot send message, WebSocket not open')
+    }
+  }
+
+  disconnect(): void {
+    this.shouldReconnect = false
+    if (this.socket) {
+      this.socket.close()
+      this.socket = null
+    }
+    this.notifyStatus(false)
+  }
+
+  private scheduleReconnect(): void {
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay)
+
+    console.log(`PyWire: Reconnecting in ${delay}ms...`)
+
+    setTimeout(() => {
+      this.reconnectAttempts++
+      this.connect().catch(() => {
+        // Reconnect will be scheduled again on close
+      })
+    }, delay)
+  }
+}