feature: Enable Electron desktop apps via Uni RPC over IPC

[xerial]

Summary

Enables Uni to build Electron desktop apps: a renderer (Chromium) calls services running in the main process (Node.js) using Uni's existing RPC stack, tunneled over Electron IPC (ipcRenderer.invoke / ipcMain.handle) instead of a network socket. Reusing the RPC wire format means service traits and clients are unchanged across HTTP and IPC.

Library — wvlet.uni.electron (Scala.js only)

• ElectronRendererChannel + ElectronChannelFactory + ElectronRenderer.install() — renderer-side HttpAsyncChannel that marshals each request through a preload bridge (window.uniRPC.request). Async-only (a sandboxed renderer has no synchronous IPC).
• ElectronRPCServer.serve(ipcMain, routers*) — main-side: registers ipcMain.handle("uni-rpc", …), dispatches via RPCDispatcher, bridges Rx[Response] → js.Promise. Electron objects are handed in as values (no require("electron")) to avoid Scala.js linker coupling.
• ElectronIPC — structured-clone-safe Request/Response ↔ payload marshaling.

Refactor

• Extract RPCDispatcher (shared, cross-platform) from netty's RPCHandler so HTTP and IPC share one dispatch path. RPCHandler now delegates to it.

Bug fixes (surfaced by the first end-to-end RPC test)

• RPCClient scalar params never serialized — JSON.parse of a bare value ("world", 42) fails; switched to JSON.parseAny. No runtime RPC test existed before, so this was latent.
• scalajs-java-securerandom was % Test — downstream JS apps couldn't link uni's main code (ULID → SecureRandom via the Weaver chain). Now a compile dep, so desktop apps link out of the box.

Example + docs

• examples/electron-app/ — full reference: Scala.js api/main/renderer, electron-vite + @scala-js/vite-plugin-scalajs pipeline, preload bridge, electron-builder packaging.
• docs/http/electron.md guide (wired into both sidebars) + adr/2026-06-24-electron-ipc-transport.md.

Verification

• New ElectronRPCTest: round-trips sync + async RPC over a fake IPC bridge — 5/5.
• uniJS http suite 345/345; netty 39/39; RPCRouterTest 7/7.
• Example compiles and links to ES modules with the expected wireMainProcess / main exports.
• scalafmtCheckAll clean; JVM/JS/Native compile; pnpm docs:build succeeds.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces Electron IPC transport support for Uni RPC, allowing Scala.js desktop applications to tunnel RPC calls over Electron's IPC instead of a network socket. It extracts a transport-neutral RPCDispatcher from netty's RPCHandler and adds the JS-only wvlet.uni.electron package containing the IPC wire contract, renderer channel, and main-process server. A complete example application and documentation are also provided. The review feedback highlights several robustness and correctness improvements, including handling potential crashes and hanging promises in the main-process dispatcher, preserving multi-value headers during serialization, preventing synchronous type errors on null payloads, and ensuring synchronous exceptions in the renderer channel do not bypass reactive stream error handling.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Uncaught exceptions in toRequest or RxRunner.run can crash the Node.js main process. Additionally, if the dispatcher returns an empty stream (e.g., if a service method returns Rx.empty), the promise will hang indefinitely because OnCompletion does not resolve or reject. Wrap the execution in a try-catch block inside the Promise constructor, and track whether a value was emitted to resolve with an error response if the stream completes empty.

  private def dispatch(dispatcher: RPCDispatcher, payload: js.Dynamic): js.Promise[js.Object] =
    new js.Promise[js.Object]((resolve, _reject) =>
      try
        val request = ElectronIPC.toRequest(payload)
        var emitted = false
        RxRunner.run(dispatcher.dispatch(request)) {
          case OnNext(v) =>
            emitted = true
            resolve(ElectronIPC.fromResponse(v.asInstanceOf[Response]))
          case OnError(e) =>
            val errorResponse = RPCStatus.INTERNAL_ERROR_I0.newException(e.getMessage, e).toResponse
            resolve(ElectronIPC.fromResponse(errorResponse))
          case OnCompletion =>
            if !emitted then
              val errorResponse = RPCStatus.INTERNAL_ERROR_I0.newException("No response emitted by RPC dispatcher").toResponse
              resolve(ElectronIPC.fromResponse(errorResponse))
        }
      catch
        case e: Throwable =>
          val errorResponse = RPCStatus.INTERNAL_ERROR_I0.newException(e.getMessage, e).toResponse
          resolve(ElectronIPC.fromResponse(errorResponse))
    )

References

1. To prevent uncaught exceptions from crashing the process in asynchronous environments (like Node.js), wrap the entire body of response-writing methods in a try-catch block so that failed writes are caught centrally.
2. When implementing cross-platform background tasks, catch all Throwable exceptions (including fatal ones) and record them as a failure result instead of rethrowing them to ensure single-threaded platforms like Scala.js do not throw immediately.

[gemini-code-assist]

Multi-value headers are currently overwritten and lost during serialization because headersToJS maps each header key to a single string value in a js.Dictionary. To preserve all values for multi-value headers, serialize them as arrays of strings.

  private def headersToJS(headers: HttpMultiMap): js.Object =
    val dict = js.Dictionary.empty[js.Array[String]]
    headers.entries.foreach { case (k, v) =>
      if !dict.contains(k) then
        dict(k) = js.Array()
      dict(k).push(v)
    }
    dict.asInstanceOf[js.Object]

[gemini-code-assist]

To support deserializing multi-value headers that are serialized as arrays of strings, update jsToHeaders to check if the header value is an array and add each item individually.

  private def jsToHeaders(headers: js.Any): HttpMultiMap =
    if js.isUndefined(headers) || headers == null then
      HttpMultiMap.empty
    else
      val builder = HttpMultiMap.newBuilder
      val dict    = headers.asInstanceOf[js.Dictionary[js.Any]]
      dict.foreach { case (k, v) =>
        if js.Array.isArray(v) then
          v.asInstanceOf[js.Array[js.Any]].foreach { item =>
            builder.add(k, String.valueOf(item))
          }
        else
          builder.add(k, String.valueOf(v))
      }
      builder.result()

[gemini-code-assist]

If payload is null or undefined, calling payload.method or payload.uri will throw a JS TypeError synchronously. Add a null/undefined check to make toRequest robust.

  def toRequest(payload: js.Dynamic): Request =
    if js.isUndefined(payload) || payload == null then
      Request(HttpMethod.POST, "")
    else
      val method = HttpMethod.of(asString(payload.method)).getOrElse(HttpMethod.POST)
      val uri    = asString(payload.uri)
      val body   = asString(payload.body)
      val base   = Request(method, uri).withHeaders(jsToHeaders(payload.headers))
      if body.isEmpty then
        base
      else
        base.withJsonContent(body)

[gemini-code-assist]

If bridge is null/undefined or calling request throws a synchronous exception, it will bypass the reactive stream's error handling and crash the caller. Wrap the call in a try-catch block and return a failed Rx to ensure idiomatic error propagation.

  override def send(request: HttpRequest, config: HttpClientConfig): Rx[HttpResponse] =
    try
      val payload = ElectronIPC.toPayload(request)
      val promise = bridge.applyDynamic("request")(payload).asInstanceOf[js.Promise[js.Dynamic]]
      val future  = promise.toFuture.map(ElectronIPC.toResponse)
      Rx.future(future)
    catch
      case e: Throwable =>
        Rx.future(scala.concurrent.Future.failed(e))

References

1. When implementing cross-platform background tasks, catch all Throwable exceptions (including fatal ones) and record them as a failure result instead of rethrowing them.

[gemini-code-assist]

Throwing NotImplementedError synchronously in sendStreaming bypasses the reactive stream's error handling. Return a failed Rx instead to allow callers to handle the error through the stream.

  override def sendStreaming(request: HttpRequest, config: HttpClientConfig): Rx[Array[Byte]] =
    Rx.future(scala.concurrent.Future.failed(NotImplementedError(
      "Streaming responses are not supported over Electron IPC. Use a regular RPC call."
    )))