wraith/docs/spikes/rdp-frame-transport-results.md

Spike: RDP Frame Transport Mechanisms

Status: Research-based (not yet benchmarked) Date: 2026-03-17 Target platform: Windows (developing on macOS) Wails version: v3.0.0-alpha.74

---

Context

When Wraith connects to a remote desktop via FreeRDP, the Go backend receives raw bitmap frames that must be delivered to the frontend for rendering on an HTML <canvas>. This spike evaluates three transport approaches, estimating throughput for a 1920x1080 session at 30 fps.

---

Approach 1: Local HTTP Endpoint

How it works

1. Go spins up a local HTTP server on a random high port (net.Listen("tcp", "127.0.0.1:0")).
2. Each frame is JPEG-encoded and served at a predictable URL (e.g., http://127.0.0.1:{port}/frame?session=3).
3. The frontend fetches frames via fetch(), <img> tag, or ReadableStream for chunked delivery.

Throughput estimate

Metric	Value
1080p RGBA raw	~8 MB/frame
1080p JPEG (quality 80)	~100-200 KB/frame
At 30 fps (JPEG)	~3-6 MB/s
Loopback bandwidth	>1 GB/s

Loopback HTTP can handle this with headroom to spare.

Pros

• No base64 overhead — binary JPEG bytes transfer directly.
• Standard HTTP semantics; easy to debug with browser DevTools.
• Can use Transfer-Encoding: chunked or Server-Sent Events for push-based delivery.
• Can serve multiple sessions on the same server with different paths.

Cons

• Requires an extra listening port on localhost.
• Potential firewall or endpoint-security issues on locked-down Windows enterprise machines.
• Slightly more complex setup (port allocation, CORS headers for Wails webview origin).

---

Approach 2: Wails Bindings (Base64)

How it works

1. Go encodes each frame as a JPEG, then base64-encodes the result.
2. A Wails-bound method (SessionService.GetFrame(sessionID)) returns the base64 string.
3. The frontend decodes the string, creates an ImageBitmap or sets it as a data URI, and draws it on a <canvas>.

Throughput estimate

Metric	Value
1080p JPEG (quality 80)	~100-200 KB/frame
Base64 of JPEG (+33%)	~133-270 KB/frame
At 30 fps	~4-8 MB/s of string data
Wails IPC overhead	Negligible for this payload size

This is feasible. Modern JavaScript engines handle base64 decoding at several hundred MB/s.

Pros

• No extra ports — everything flows through the existing Wails IPC channel.
• Works out of the box with Wails bindings; no additional infrastructure.
• No firewall concerns.

Cons

• 33% base64 size overhead on every frame.
• CPU cost of base64.StdEncoding.EncodeToString() in Go and atob() in JS on every frame (though both are fast).
• Polling-based unless combined with Wails events to signal frame availability.
• May bottleneck at very high resolutions (4K) or high FPS (60+).

---

Approach 3: Wails Events (Streaming)

How it works

1. Go emits each frame as a Wails event: app.EmitEvent("frame:3", base64JpegString).
2. The frontend subscribes: wails.Events.On("frame:3", handler).
3. The handler decodes and renders on canvas.

Throughput estimate

Same as Approach 2 — the payload is identical (base64 JPEG). The difference is delivery mechanism (push vs. pull).

Pros

• Push-based — the frontend receives frames as soon as they are available with no polling delay.
• Natural Wails pattern; aligns with how other real-time data (connection status, notifications) already flows.

Cons

• Same 33% base64 overhead as Approach 2.
• Wails event bus may not be optimised for high-frequency, large-payload events. This is unvalidated.
• Harder to apply backpressure — if the frontend cannot keep up, events queue without flow control.

---

Throughput Summary

Approach	Payload/frame	30 fps throughput	Extra infra
1 — Local HTTP	~150 KB (binary JPEG)	~4.5 MB/s	Localhost port
2 — Wails bindings	~200 KB (base64 JPEG)	~6 MB/s	None
3 — Wails events	~200 KB (base64 JPEG)	~6 MB/s	None

All three approaches are within comfortable limits for 1080p at 30 fps. The differentiator is operational simplicity, not raw throughput.

---

Recommendation

Start with Approach 2 (base64 JPEG via Wails bindings).

Rationale:

1. JPEG compression brings 1080p frames down to ~200 KB, making the 33% base64 overhead manageable (~6 MB/s at 30 fps).
2. No extra ports or firewall concerns — important for enterprise Windows environments where Wraith will be deployed.
3. Simple implementation: one Go method, one frontend call per frame.
4. If polling latency is a problem, upgrade to Approach 3 (events) with minimal code change — the payload encoding is identical.

If benchmarking reveals issues (dropped frames, high CPU from encoding), fall back to Approach 1 (local HTTP) which eliminates base64 overhead entirely. The migration path is straightforward: replace the fetch(dataUri) call with fetch(httpUrl).

---

Next Step

Benchmark during Phase 3 when FreeRDP integration is in progress and real frame data is available. Key metrics to capture:

• End-to-end frame latency (Go encode to canvas paint)
• CPU utilisation on both Go and browser sides
• Frame drop rate at 30 fps and 60 fps
• Memory pressure from base64 string allocation/GC