pywire 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,149 @@
+import { BaseTransport, ServerMessage } from './base'
+
+/**
+ * WebTransport implementation using the browser's native WebTransport API.
+ * WebTransport provides lower latency than WebSocket via HTTP/3 and QUIC.
+ */
+export class WebTransportTransport extends BaseTransport {
+  readonly name = 'WebTransport'
+
+  private transport: WebTransport | null = null
+  private writer: WritableStreamDefaultWriter<Uint8Array> | null = null
+  private readonly url: string
+  private encoder = new TextEncoder()
+  private decoder = new TextDecoder()
+
+  constructor(url?: string) {
+    super()
+    this.url = url || this.getDefaultUrl()
+  }
+
+  private getDefaultUrl(): string {
+    // WebTransport requires HTTPS
+    return `https://${window.location.host}/_pywire/webtransport`
+  }
+
+  /**
+   * Check if WebTransport is available in this browser.
+   */
+  static isSupported(): boolean {
+    return typeof WebTransport !== 'undefined'
+  }
+
+  async connect(): Promise<void> {
+    if (!WebTransportTransport.isSupported()) {
+      throw new Error('WebTransport not supported in this browser')
+    }
+
+    try {
+      // Check for self-signed cert hash (Dev Mode)
+      const options: WebTransportOptions = {}
+      const certHash = (window as Window & { PYWIRE_CERT_HASH?: number[] }).PYWIRE_CERT_HASH
+      if (certHash && Array.isArray(certHash)) {
+        options.serverCertificateHashes = [
+          {
+            algorithm: 'sha-256',
+            value: new Uint8Array(certHash).buffer,
+          },
+        ]
+        console.log('PyWire: Using explicit certificate hash for WebTransport')
+      }
+
+      this.transport = new WebTransport(this.url, options)
+
+      // Wait for the connection to be ready
+      await this.transport.ready
+
+      console.log('PyWire: WebTransport ready')
+      this.connected = true
+
+      // Start reading incoming streams
+      this.startReading()
+    } catch (e) {
+      this.handleDisconnect()
+      throw e
+    }
+  }
+
+  private async startReading(): Promise<void> {
+    if (!this.transport) return
+
+    // Read from bidirectional streams
+    const reader = this.transport.incomingBidirectionalStreams.getReader()
+
+    try {
+      while (true) {
+        const { value: stream, done } = await reader.read()
+        if (done) break
+
+        // Handle each incoming stream
+        this.handleStream(stream)
+      }
+    } catch (e) {
+      if (this.connected) {
+        console.error('PyWire: WebTransport read error', e)
+        this.handleDisconnect()
+      }
+    }
+  }
+
+  private async handleStream(stream: WebTransportBidirectionalStream): Promise<void> {
+    const reader = stream.readable.getReader()
+
+    try {
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+
+        if (value) {
+          const text = this.decoder.decode(value)
+          try {
+            const msg = JSON.parse(text) as ServerMessage
+            this.notifyHandlers(msg)
+          } catch (e) {
+            console.error('PyWire: Error parsing WebTransport message', e)
+          }
+        }
+      }
+    } catch (e) {
+      console.error('PyWire: Stream read error', e)
+    }
+  }
+
+  async send(message: object): Promise<void> {
+    if (!this.transport || !this.connected) {
+      console.warn('PyWire: Cannot send message, WebTransport not connected')
+      return
+    }
+
+    try {
+      // Create a new bidirectional stream for each message
+      const stream = await this.transport.createBidirectionalStream()
+      const writer = stream.writable.getWriter()
+
+      const data = this.encoder.encode(JSON.stringify(message))
+      await writer.write(data)
+      await writer.close()
+
+      // Read the response from this stream
+      this.handleStream(stream)
+    } catch (e) {
+      console.error('PyWire: WebTransport send error', e)
+    }
+  }
+
+  disconnect(): void {
+    if (this.transport) {
+      this.transport.close()
+      this.transport = null
+    }
+    this.writer = null
+    this.connected = false
+  }
+
+  private handleDisconnect(): void {
+    this.connected = false
+    this.transport = null
+    this.writer = null
+  }
+}

pywire/client/src/dev/dev-app.ts

@@ -0,0 +1,93 @@
+import { PyWireApp, ServerMessage } from '../core'
+import { StatusOverlay } from './status-overlay'
+import { ErrorTraceHandler } from './error-trace'
+
+/**
+ * Development-mode PyWire Application.
+ * Extends core app with:
+ * - Connection status overlay
+ * - Error trace handling with source loading
+ * - Enhanced console output
+ */
+export class PyWireDevApp extends PyWireApp {
+  private overlay: StatusOverlay | null = null
+  private errorHandler: ErrorTraceHandler
+
+  constructor(config = {}) {
+    super(config)
+    this.errorHandler = new ErrorTraceHandler()
+  }
+
+  async init(): Promise<void> {
+    // Create overlay before init so status changes are captured
+    this.overlay = new StatusOverlay()
+
+    await super.init()
+  }
+
+  /**
+   * Handle connection status changes with UI overlay.
+   */
+  protected handleStatusChange(connected: boolean): void {
+    super.handleStatusChange(connected)
+    if (this.overlay) {
+      this.overlay.update(connected)
+    }
+  }
+
+  /**
+   * Navigate with offline feedback.
+   */
+  navigateTo(path: string): void {
+    if (!this.isConnected) {
+      console.warn('PyWire: Navigation blocked - Offline')
+      if (this.overlay) {
+        this.overlay.showNavigationBlocked()
+      }
+      return
+    }
+
+    super.navigateTo(path)
+  }
+
+  /**
+   * Handle incoming server messages with enhanced error trace support.
+   */
+  protected async handleMessage(msg: ServerMessage): Promise<void> {
+    switch (msg.type) {
+      case 'error_trace':
+        if (msg.trace) {
+          await this.errorHandler.handle(msg.error || 'Unknown Error', msg.trace)
+        }
+        return
+
+      case 'console':
+        // Enhanced console output with grouping
+        if (msg.lines && msg.lines.length > 0) {
+          const prefix = 'PyWire Server:'
+          const joined = msg.lines.join('\n')
+          if (msg.level === 'error') {
+            console.group(prefix + ' Error')
+            console.error(joined)
+            console.groupEnd()
+          } else if (msg.level === 'warn') {
+            console.groupCollapsed(prefix + ' Warning')
+            console.warn(joined)
+            console.groupEnd()
+          } else {
+            if (msg.lines.length === 1) {
+              console.log(prefix, joined)
+            } else {
+              console.groupCollapsed(prefix + ' Log')
+              console.log(joined)
+              console.groupEnd()
+            }
+          }
+        }
+        return
+
+      default:
+        await super.handleMessage(msg)
+    }
+  }
+}

pywire/client/src/dev/error-trace.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { ErrorTraceHandler } from './error-trace'
+
+describe('ErrorTraceHandler', () => {
+  let handler: ErrorTraceHandler
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    handler = new ErrorTraceHandler()
+    vi.stubGlobal('location', { origin: 'http://localhost:8000' })
+    vi.stubGlobal('fetch', vi.fn())
+    vi.stubGlobal('console', { error: vi.fn(), warn: vi.fn(), log: vi.fn() })
+    // vi.stubGlobal('eval', vi.fn()); // indirect eval is hard to mock, but we can check if it's called
+  })
+
+  it('should generate virtual URLs correctly', () => {
+    // getVirtualUrl is private, so we'll test it through handle()'s side effects or by casting
+    const virtualUrl = (
+      handler as unknown as { getVirtualUrl: (filename: string) => string }
+    ).getVirtualUrl('/path/to/script.py')
+    expect(virtualUrl).toContain('http://localhost:8000/_pywire/file/')
+    expect(virtualUrl).toContain('script.py')
+  })
+
+  it('should fetch source files and inject them with sourceURL', async () => {
+    const fetchMock = vi.mocked(fetch)
+    fetchMock.mockResolvedValue({
+      ok: true,
+      text: async () => 'print("hello")',
+    } as Response)
+
+    const trace = [
+      {
+        filename: '/path/to/script.py',
+        lineno: 10,
+        colno: 5,
+        name: 'my_func',
+        line: 'def my_func():',
+      },
+    ]
+
+    await handler.handle('Test Error', trace)
+
+    expect(fetchMock).toHaveBeenCalledWith('/_pywire/source?path=%2Fpath%2Fto%2Fscript.py')
+    // We expect console.error to have been called with the constructed stack
+    expect(vi.mocked(console.error)).toHaveBeenCalledWith(
+      expect.stringContaining('at my_func (http://localhost:8000/_pywire/file/')
+    )
+    expect(vi.mocked(console.error)).toHaveBeenCalledWith(expect.stringContaining(':10:5)'))
+  })
+
+  it('should handle missing column numbers', async () => {
+    vi.mocked(fetch).mockResolvedValue({ ok: false } as Response)
+
+    const trace = [{ filename: 'test.py', lineno: 5, name: 'foo', line: 'x = 1' }]
+
+    await handler.handle('Error', trace)
+
+    expect(vi.mocked(console.error)).toHaveBeenCalledWith(
+      expect.stringContaining('at foo (http://localhost:8000/_pywire/file/')
+    )
+    expect(vi.mocked(console.error)).toHaveBeenCalledWith(
+      expect.stringContaining(':5:1)') // Default colno is 1
+    )
+  })
+
+  it('should not reload already loaded sources', async () => {
+    const fetchMock = vi.mocked(fetch)
+    fetchMock.mockResolvedValue({
+      ok: true,
+      text: async () => 'content',
+    } as Response)
+
+    const trace = [{ filename: 'test.py', lineno: 1, name: 'foo', line: 'content' }]
+
+    await handler.handle('Err 1', trace)
+    await handler.handle('Err 2', trace)
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('should handle fetch failures gracefully', async () => {
+    vi.mocked(fetch).mockRejectedValue(new Error('Network error'))
+
+    const trace = [{ filename: 'test.py', lineno: 1, name: 'foo', line: 'content' }]
+
+    await handler.handle('Err', trace)
+
+    expect(vi.mocked(console.warn)).toHaveBeenCalledWith(
+      expect.stringContaining('PyWire: Failed to load source'),
+      'test.py',
+      expect.any(Error)
+    )
+    // Should still log the error stack
+    expect(vi.mocked(console.error)).toHaveBeenCalled()
+  })
+})

pywire/client/src/dev/error-trace.ts

@@ -0,0 +1,76 @@
+import { StackFrame } from '../core/transports'
+
+/**
+ * Handles error traces from the server in development mode.
+ * Loads source files and displays errors with proper source mapping in DevTools.
+ */
+export class ErrorTraceHandler {
+  private loadedSources = new Set<string>()
+
+  /**
+   * Get a virtual URL for a filename that Chrome will display in stack traces.
+   */
+  private getVirtualUrl(filename: string): string {
+    const encoded = btoa(filename).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+    const cleanName = filename.split(/[/\\]/).pop() || 'unknown'
+    return `${window.location.origin}/_pywire/file/${encoded}/${cleanName}`
+  }
+
+  /**
+   * Handle an error trace message from the server.
+   */
+  async handle(errorMessage: string, trace: StackFrame[]): Promise<void> {
+    // Load sources for frames
+    const filesToLoad = new Set<string>()
+    for (const frame of trace) {
+      if (!this.loadedSources.has(frame.filename)) {
+        filesToLoad.add(frame.filename)
+      }
+    }
+
+    await Promise.all(
+      Array.from(filesToLoad).map(async (filename) => {
+        try {
+          const virtualUrl = this.getVirtualUrl(filename)
+
+          // Fetch content
+          const url = `/_pywire/source?path=${encodeURIComponent(filename)}`
+          const resp = await fetch(url)
+          if (resp.ok) {
+            const content = await resp.text()
+
+            // Inject the raw source with sourceURL for DevTools
+            const sourceCode = `${content}\n//# sourceURL=${virtualUrl}`
+            try {
+              ;(0, eval)(sourceCode)
+            } catch {
+              // Syntax errors from Python content are expected - ignore
+            }
+
+            this.loadedSources.add(filename)
+          }
+
+          this.loadedSources.add(filename)
+        } catch (e) {
+          console.warn('PyWire: Failed to load source', filename, e)
+        }
+      })
+    )
+
+    // Construct Error with stack pointing to virtual URLs
+    const err = new Error(errorMessage)
+    const stackLines = [`${err.name}: ${err.message}`]
+
+    for (const frame of trace) {
+      const fn = frame.name || '<module>'
+      const virtualUrl = this.getVirtualUrl(frame.filename)
+      const col = frame.colno ?? 1
+      stackLines.push(`    at ${fn} (${virtualUrl}:${frame.lineno}:${col})`)
+    }
+
+    err.stack = stackLines.join('\n')
+
+    // Log just the stack string to avoid Chrome appending its own call stack
+    console.error(err.stack)
+  }
+}

pywire/client/src/dev/index.ts

@@ -0,0 +1,4 @@
+// Dev module exports
+export { PyWireDevApp } from './dev-app'
+export { StatusOverlay } from './status-overlay'
+export { ErrorTraceHandler } from './error-trace'

pywire/client/src/dev/status-overlay.ts

@@ -0,0 +1,63 @@
+/**
+ * Connection status overlay for development mode.
+ * Shows a toast-style notification when connection is lost.
+ */
+export class StatusOverlay {
+  private element: HTMLElement | null = null
+
+  constructor() {
+    this.create()
+  }
+
+  private create(): void {
+    this.element = document.createElement('div')
+    this.element.style.cssText = `
+            position: fixed;
+            bottom: 20px;
+            right: 20px;
+            background: rgba(0, 0, 0, 0.8);
+            color: white;
+            padding: 10px 20px;
+            border-radius: 5px;
+            font-family: system-ui, -apple-system, sans-serif;
+            font-size: 14px;
+            z-index: 10000;
+            display: none;
+            transition: opacity 0.3s;
+            pointer-events: none;
+        `
+    document.body.appendChild(this.element)
+  }
+
+  /**
+   * Update overlay based on connection status.
+   */
+  update(connected: boolean): void {
+    if (!this.element) return
+
+    if (connected) {
+      this.element.style.display = 'none'
+    } else {
+      this.element.textContent = 'Connection Lost - Reconnecting...'
+      this.element.style.display = 'block'
+      this.element.style.backgroundColor = 'rgba(0, 0, 0, 0.8)'
+    }
+  }
+
+  /**
+   * Show a temporary navigation-blocked message.
+   */
+  showNavigationBlocked(): void {
+    if (!this.element) return
+
+    this.element.style.backgroundColor = 'rgba(200, 0, 0, 0.9)'
+    this.element.textContent = 'Cannot navigate - Offline'
+    this.element.style.display = 'block'
+
+    setTimeout(() => {
+      if (this.element) {
+        this.element.style.backgroundColor = 'rgba(0, 0, 0, 0.8)'
+      }
+    }, 1500)
+  }
+}