fix(desktop): drive the IPC port handshake and event stream through state machines (#61953)

This commit is contained in:
Luke Parker
2026-11-05 00:03:43 -06:00
committed by GitHub
Unverified
parent 0280763488
commit a4ce0b0989
12 changed files with 1271 additions and 179 deletions
+10 -21
View File
@@ -1,31 +1,20 @@
import type { WebContents } from "electron"
import { Effect, Queue, Stream } from "effect"
import type { DesktopEvent } from "../shared/ipc-rpc/events"
const queues = new Map<number, Queue.Queue<DesktopEvent>>()
type Sink = (sender: WebContents, event: DesktopEvent) => boolean
export const bindIpcEvents = Effect.fn("IpcEvents.bind")(function* (senderId: number) {
const queue = yield* Queue.unbounded<DesktopEvent>()
const previous = queues.get(senderId)
queues.set(senderId, queue)
// The IPC transport owns each window's event stream and registers itself here while its layer lives.
let sink: Sink | undefined
if (previous) yield* Queue.shutdown(previous)
export function setIpcEventSink(next: Sink) {
sink = next
return Effect.fnUntraced(function* () {
if (queues.get(senderId) === queue) queues.delete(senderId)
yield* Queue.shutdown(queue)
})()
})
export function ipcEventStream(senderId: number) {
const queue = queues.get(senderId)
return queue ? Stream.fromQueue(queue) : Stream.empty
return () => {
if (sink === next) sink = undefined
}
}
/** Returns false when the renderer has no event stream to receive the event. */
/** Returns false when the renderer has no event stream to receive the event, now or once its document binds. */
export function emitIpcEvent(sender: WebContents, event: DesktopEvent) {
const queue = queues.get(sender.id)
return queue ? Queue.offerUnsafe(queue, event) : false
return sink ? sink(sender, event) : false
}
@@ -1,15 +1,17 @@
import { Effect } from "effect"
import { Effect, Stream } from "effect"
import { EventRpcs } from "../../shared/ipc-rpc"
import { ipcEventStream } from "../ipc-events"
import { IpcPortHandoff } from "../ipc-transport"
import { sender } from "./context"
export const eventHandlers = EventRpcs.toLayer(
Effect.gen(function* () {
const handoff = yield* IpcPortHandoff
return EventRpcs.of({
DesktopEvents: (_request, context) => ipcEventStream(sender(handoff, context).id),
DesktopEvents: (_request, context) => {
const events = handoff.events(context.client.id)
return events ? Stream.fromQueue(events) : Stream.empty
},
})
}),
)
@@ -5,7 +5,6 @@ import { StorageChanged } from "../../shared/ipc-rpc/events"
import { emitIpcEvent } from "../ipc-events"
import { IpcPortHandoff } from "../ipc-transport"
import { DesktopStorage } from "../storage"
import { sender } from "./context"
export const storageHandlers = StorageRpcs.toLayer(
Effect.gen(function* () {
@@ -17,12 +16,12 @@ export const storageHandlers = StorageRpcs.toLayer(
StorageUpdate: ({ name, insert, remove }, context) =>
Effect.sync(() => {
const revision = storage.state.update(name, insert, remove)
// Other windows hold their own copy of this namespace; tell them what moved.
const origin = sender(handoff, context)
// Other windows hold their own copy of this namespace; tell them what moved. A reloading
// window's new document is another copy too: an unloading document's flush reaches it.
const event = new StorageChanged({ name, insert, remove, revision })
for (const win of BrowserWindow.getAllWindows()) {
if (win.webContents !== origin) emitIpcEvent(win.webContents, event)
if (!handoff.isCurrentClient(win.webContents, context.client.id)) emitIpcEvent(win.webContents, event)
}
return revision
@@ -0,0 +1,183 @@
import { describe, expect, test } from "bun:test"
import {
createIpcTransportState,
MAX_BUFFERED_EVENTS,
selectBoundClientId,
selectBoundEventQueue,
selectClientEventQueue,
selectClientIds,
selectClientPort,
selectClientSender,
transitionIpcTransport,
type IpcTransportCommand,
type IpcTransportEvent,
type IpcTransportState,
} from "./ipc-machine"
// Senders, ports, queues and events are opaque to the machine, so labels stand in for them.
type State = IpcTransportState<string, string, string, string>
type Event = IpcTransportEvent<string, string, string, string>
type Command = IpcTransportCommand<string, string, string, string>
const WINDOW = 7
const prepared: Event = { type: "sender.prepared", senderId: WINDOW, sender: "window" }
function bound(port: string, events: string): Event {
return { type: "port.bound", senderId: WINDOW, sender: "window", port, events }
}
function emitted(event: string): Event {
return { type: "event.emitted", senderId: WINDOW, event }
}
function replay(events: readonly Event[], from: State = createIpcTransportState()) {
return events.reduce<{ state: State; commands: Command[] }>(
(result, event) => {
const next = transitionIpcTransport(result.state, event)
return { state: next.state, commands: [...result.commands, ...next.commands] }
},
{ state: from, commands: [] },
)
}
describe("IPC transport machine", () => {
test("holds a new window's events from its storage snapshot until its port binds", () => {
// On dev the window had no event queue until bind, so a StorageChanged sent in between was dropped.
const waiting = replay([prepared, emitted("storage R1")])
expect(waiting.commands).toEqual([{ type: "watch-sender", senderId: WINDOW, sender: "window" }])
expect(selectBoundEventQueue(waiting.state, WINDOW)).toBeUndefined()
const next = transitionIpcTransport(waiting.state, bound("p0", "q0"))
expect(next.commands).toEqual([
{ type: "attach-port", clientId: 0, port: "p0" },
{ type: "offer-events", events: "q0", items: ["storage R1"] },
])
expect(selectBoundEventQueue(next.state, WINDOW)).toBe("q0")
expect(selectClientEventQueue(next.state, 0)).toBe("q0")
})
test("moves events sent during a reload to the new document and drains the old port", () => {
// On dev the reload's events went into the old queue, which the new port's bind then shut down.
const first = replay([bound("p0", "q0")])
const unloading = transitionIpcTransport(first.state, prepared)
expect(unloading.commands).toEqual([
{ type: "shutdown-events", events: "q0" },
{ type: "notify-disconnect", clientId: 0 },
])
// The unloading document still answers its pagehide flush, but streams no events.
expect(selectClientPort(unloading.state, 0)).toBe("p0")
expect(selectClientSender(unloading.state, 0)).toBe("window")
expect(selectClientEventQueue(unloading.state, 0)).toBeUndefined()
expect(selectBoundClientId(unloading.state, WINDOW)).toBeUndefined()
const reloaded = replay(
[emitted("menu"), emitted("zoom"), emitted("focus"), emitted("storage"), prepared, bound("p1", "q1")],
unloading.state,
)
// Disconnect listeners heard about client 0 once, when its document started unloading.
expect(reloaded.commands).toEqual([
{ type: "close-port", port: "p0" },
{ type: "end-client", clientId: 0 },
{ type: "attach-port", clientId: 1, port: "p1" },
{ type: "offer-events", events: "q1", items: ["menu", "zoom", "focus", "storage"] },
])
expect(selectClientIds(reloaded.state)).toEqual(new Set([1]))
expect(selectBoundClientId(reloaded.state, WINDOW)).toBe(1)
})
test("keeps a reload's events when the old port closes before the new one binds", () => {
// On dev the closing port deleted the window's queue, so later events had nowhere to go.
const closed = replay([bound("p0", "q0"), prepared, emitted("storage"), { type: "client.closed", clientId: 0 }])
expect(closed.commands.slice(-2)).toEqual([
{ type: "close-port", port: "p0" },
{ type: "end-client", clientId: 0 },
])
expect(selectClientIds(closed.state)).toEqual(new Set())
expect(transitionIpcTransport(closed.state, bound("p1", "q1")).commands).toEqual([
{ type: "attach-port", clientId: 1, port: "p1" },
{ type: "offer-events", events: "q1", items: ["storage"] },
])
})
test("replaces a bound port that is rebound without a snapshot", () => {
const rebound = replay([bound("p0", "q0"), bound("p1", "q1")])
expect(rebound.commands.slice(2)).toEqual([
{ type: "shutdown-events", events: "q0" },
{ type: "close-port", port: "p0" },
{ type: "notify-disconnect", clientId: 0 },
{ type: "end-client", clientId: 0 },
{ type: "attach-port", clientId: 1, port: "p1" },
])
expect(selectClientSender(rebound.state, 0)).toBeUndefined()
expect(selectBoundEventQueue(rebound.state, WINDOW)).toBe("q1")
})
test("forgets a window whose bound port closes", () => {
const closed = replay([bound("p0", "q0"), { type: "client.closed", clientId: 0 }])
expect(closed.commands.slice(2)).toEqual([
{ type: "shutdown-events", events: "q0" },
{ type: "close-port", port: "p0" },
{ type: "notify-disconnect", clientId: 0 },
{ type: "end-client", clientId: 0 },
{ type: "unwatch-sender", senderId: WINDOW, sender: "window" },
])
// Events for a window with no document on the way are not held.
const after = transitionIpcTransport(closed.state, emitted("late"))
expect(after.state).toBe(closed.state)
})
test.each([
{
name: "bound",
events: [bound("p0", "q0")],
released: ["shutdown-events", "close-port", "notify-disconnect", "end-client"],
},
{ name: "awaiting its first port", events: [prepared], released: [] },
{ name: "draining a reload", events: [bound("p0", "q0"), prepared], released: ["close-port", "end-client"] },
])("releases a destroyed window that is $name", (input) => {
const before = replay(input.events)
const next = transitionIpcTransport(before.state, { type: "sender.destroyed", senderId: WINDOW })
expect(next.commands.map((command) => command.type)).toEqual([...input.released, "unwatch-sender"])
expect(selectClientIds(next.state)).toEqual(new Set())
expect(transitionIpcTransport(next.state, emitted("late")).state).toBe(next.state)
})
test("caps the events held for a window", () => {
const full = replay(
Array.from({ length: MAX_BUFFERED_EVENTS }, (_, index) => emitted(`e${index}`)),
replay([prepared]).state,
)
expect(transitionIpcTransport(full.state, emitted("overflow")).state).toBe(full.state)
})
test("ignores stale and repeated events", () => {
const waiting = replay([prepared]).state
expect(transitionIpcTransport(waiting, prepared).state).toBe(waiting)
expect(transitionIpcTransport(waiting, { type: "client.closed", clientId: 3 }).state).toBe(waiting)
expect(transitionIpcTransport(waiting, { type: "sender.destroyed", senderId: 99 }).state).toBe(waiting)
})
test("closes everything on dispose and refuses later ports", () => {
const disposed = replay([bound("p0", "q0"), { type: "disposed" }])
expect(disposed.state).toEqual({ status: "disposed" })
expect(disposed.commands.slice(2).map((command) => command.type)).toEqual([
"shutdown-events",
"close-port",
"notify-disconnect",
"end-client",
"unwatch-sender",
])
expect(transitionIpcTransport(disposed.state, bound("p1", "q1")).commands).toEqual([
{ type: "close-port", port: "p1" },
{ type: "shutdown-events", events: "q1" },
])
expect(transitionIpcTransport(disposed.state, prepared).commands).toEqual([])
})
})
+314
View File
@@ -0,0 +1,314 @@
/** Caps the events held for a window whose renderer has not bound its port yet. */
export const MAX_BUFFERED_EVENTS = 1_024
// A window (sender) either waits for its document's port, holding the events sent meanwhile, or is
// bound to one renderer client with a live event queue. While a new document loads, the previous
// document's port drains: it still answers in-flight RPCs (pagehide storage flushes) but receives
// no events.
export type IpcSender<Sender, Port, Events, Item> =
| {
readonly status: "awaiting-port"
readonly sender: Sender
readonly buffered: readonly Item[]
readonly draining: { readonly clientId: number; readonly port: Port } | undefined
}
| {
readonly status: "bound"
readonly sender: Sender
readonly clientId: number
readonly port: Port
readonly events: Events
}
export type IpcTransportState<Sender, Port, Events, Item> =
| {
readonly status: "open"
readonly nextClientId: number
readonly senders: ReadonlyMap<number, IpcSender<Sender, Port, Events, Item>>
/** Index from each bound or draining client to its sender. */
readonly clients: ReadonlyMap<number, number>
}
| { readonly status: "disposed" }
export type IpcTransportEvent<Sender, Port, Events, Item> =
| { readonly type: "sender.prepared"; readonly senderId: number; readonly sender: Sender }
| { readonly type: "event.emitted"; readonly senderId: number; readonly event: Item }
| {
readonly type: "port.bound"
readonly senderId: number
readonly sender: Sender
readonly port: Port
readonly events: Events
}
| { readonly type: "client.closed"; readonly clientId: number }
| { readonly type: "sender.destroyed"; readonly senderId: number }
| { readonly type: "disposed" }
export type IpcTransportCommand<Sender, Port, Events, Item> =
| { readonly type: "watch-sender"; readonly senderId: number; readonly sender: Sender }
| { readonly type: "unwatch-sender"; readonly senderId: number; readonly sender: Sender }
| { readonly type: "attach-port"; readonly clientId: number; readonly port: Port }
| { readonly type: "close-port"; readonly port: Port }
| { readonly type: "offer-events"; readonly events: Events; readonly items: readonly Item[] }
| { readonly type: "shutdown-events"; readonly events: Events }
/** Tells `onDisconnect` listeners the client no longer receives events. */
| { readonly type: "notify-disconnect"; readonly clientId: number }
/** Tells the RPC server the client is gone, interrupting its requests. */
| { readonly type: "end-client"; readonly clientId: number }
export type IpcTransportTransition<Sender, Port, Events, Item> = {
readonly state: IpcTransportState<Sender, Port, Events, Item>
readonly commands: readonly IpcTransportCommand<Sender, Port, Events, Item>[]
}
export function createIpcTransportState<Sender, Port, Events, Item>(): IpcTransportState<Sender, Port, Events, Item> {
return { status: "open", nextClientId: 0, senders: new Map(), clients: new Map() }
}
export function transitionIpcTransport<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
event: IpcTransportEvent<Sender, Port, Events, Item>,
): IpcTransportTransition<Sender, Port, Events, Item> {
if (state.status === "disposed") {
// A port handed over during shutdown has no server to talk to.
if (event.type === "port.bound")
return {
state,
commands: [
{ type: "close-port", port: event.port },
{ type: "shutdown-events", events: event.events },
],
}
return { state, commands: [] }
}
switch (event.type) {
case "sender.prepared": {
const current = state.senders.get(event.senderId)
if (current?.status === "awaiting-port") return { state, commands: [] }
if (!current)
return {
state: withSender(state, event.senderId, awaiting(event.sender, undefined)),
commands: [{ type: "watch-sender", senderId: event.senderId, sender: event.sender }],
}
// The bound document is unloading: its events stop now, its port drains until it closes.
return {
state: withSender(
state,
event.senderId,
awaiting(current.sender, { clientId: current.clientId, port: current.port }),
),
commands: [
{ type: "shutdown-events", events: current.events },
{ type: "notify-disconnect", clientId: current.clientId },
],
}
}
case "event.emitted": {
const current = state.senders.get(event.senderId)
// Bound senders take events straight from `selectBoundEventQueue`, without a transition.
if (current?.status !== "awaiting-port" || current.buffered.length >= MAX_BUFFERED_EVENTS)
return { state, commands: [] }
return {
state: withSender(state, event.senderId, { ...current, buffered: [...current.buffered, event.event] }),
commands: [],
}
}
case "port.bound": {
const current = state.senders.get(event.senderId)
const clientId = state.nextClientId
const clients = new Map(state.clients)
const released = current?.status === "bound" ? current.clientId : current?.draining?.clientId
if (released !== undefined) clients.delete(released)
clients.set(clientId, event.senderId)
const senders = new Map(state.senders)
senders.set(event.senderId, {
status: "bound",
sender: current?.sender ?? event.sender,
clientId,
port: event.port,
events: event.events,
})
return {
state: { status: "open", nextClientId: clientId + 1, senders, clients },
commands: [
...(current
? release(current)
: [{ type: "watch-sender" as const, senderId: event.senderId, sender: event.sender }]),
{ type: "attach-port", clientId, port: event.port },
...(current?.status === "awaiting-port" && current.buffered.length > 0
? [{ type: "offer-events" as const, events: event.events, items: current.buffered }]
: []),
],
}
}
case "client.closed": {
const senderId = state.clients.get(event.clientId)
const current = senderId === undefined ? undefined : state.senders.get(senderId)
if (senderId === undefined || !current) return { state, commands: [] }
const clients = new Map(state.clients)
clients.delete(event.clientId)
// A draining port closing leaves the window waiting for its new document, events kept.
if (current.status === "awaiting-port")
return {
state: {
...state,
senders: new Map(state.senders).set(senderId, { ...current, draining: undefined }),
clients,
},
commands: release(current),
}
const senders = new Map(state.senders)
senders.delete(senderId)
return {
state: { ...state, senders, clients },
commands: [
...release<Sender, Port, Events, Item>(current),
{ type: "unwatch-sender", senderId, sender: current.sender },
],
}
}
case "sender.destroyed": {
const current = state.senders.get(event.senderId)
if (!current) return { state, commands: [] }
const senders = new Map(state.senders)
senders.delete(event.senderId)
const clients = new Map(state.clients)
const clientId = current.status === "bound" ? current.clientId : current.draining?.clientId
if (clientId !== undefined) clients.delete(clientId)
return {
state: { ...state, senders, clients },
commands: [...release(current), { type: "unwatch-sender", senderId: event.senderId, sender: current.sender }],
}
}
case "disposed":
return {
state: { status: "disposed" },
commands: [...state.senders].flatMap(([senderId, current]) => [
...release(current),
{ type: "unwatch-sender" as const, senderId, sender: current.sender },
]),
}
}
}
/** The event queue of a sender's bound renderer; read on every `emitIpcEvent`, so it allocates nothing. */
export function selectBoundEventQueue<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
senderId: number,
) {
if (state.status !== "open") return
const current = state.senders.get(senderId)
return current?.status === "bound" ? current.events : undefined
}
/** The event queue a client streams; none for a draining client, so an unloading document never reads its successor's events. */
export function selectClientEventQueue<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
clientId: number,
) {
const current = senderOf(state, clientId)
return current?.status === "bound" && current.clientId === clientId ? current.events : undefined
}
/** The port of a bound or draining client, which still answers its RPCs. */
export function selectClientPort<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
clientId: number,
) {
const current = senderOf(state, clientId)
if (current?.status === "bound") return current.port
return current?.draining?.port
}
export function selectClientSender<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
clientId: number,
) {
return senderOf(state, clientId)?.sender
}
/** The client that receives a sender's events, if its current document has bound one. */
export function selectBoundClientId<Sender, Port, Events, Item>(
state: IpcTransportState<Sender, Port, Events, Item>,
senderId: number,
) {
if (state.status !== "open") return
const current = state.senders.get(senderId)
return current?.status === "bound" ? current.clientId : undefined
}
export function selectClientIds<Sender, Port, Events, Item>(state: IpcTransportState<Sender, Port, Events, Item>) {
return new Set(state.status === "open" ? state.clients.keys() : [])
}
function senderOf<Sender, Port, Events, Item>(state: IpcTransportState<Sender, Port, Events, Item>, clientId: number) {
if (state.status !== "open") return
const senderId = state.clients.get(clientId)
return senderId === undefined ? undefined : state.senders.get(senderId)
}
function awaiting<Sender, Port, Events, Item>(
sender: Sender,
draining: { readonly clientId: number; readonly port: Port } | undefined,
): IpcSender<Sender, Port, Events, Item> {
return { status: "awaiting-port", sender, buffered: [], draining }
}
function withSender<Sender, Port, Events, Item>(
state: Extract<IpcTransportState<Sender, Port, Events, Item>, { status: "open" }>,
senderId: number,
sender: IpcSender<Sender, Port, Events, Item>,
): IpcTransportState<Sender, Port, Events, Item> {
return { ...state, senders: new Map(state.senders).set(senderId, sender) }
}
// Disconnects the client a sender holds: a bound client loses its events and its listeners hear
// about it; a draining one already did both when its document started unloading.
function release<Sender, Port, Events, Item>(
current: IpcSender<Sender, Port, Events, Item>,
): IpcTransportCommand<Sender, Port, Events, Item>[] {
if (current.status === "bound")
return [
{ type: "shutdown-events", events: current.events },
{ type: "close-port", port: current.port },
{ type: "notify-disconnect", clientId: current.clientId },
{ type: "end-client", clientId: current.clientId },
]
if (!current.draining) return []
return [
{ type: "close-port", port: current.draining.port },
{ type: "end-client", clientId: current.draining.clientId },
]
}
@@ -2,11 +2,14 @@ import { describe, expect, test } from "bun:test"
import { EventEmitter } from "node:events"
import { MessageChannel } from "node:worker_threads"
import type { MessagePortMain, WebContents } from "electron"
import { Effect, Layer, ManagedRuntime, Predicate, Schema, Stream } from "effect"
import { Deferred, Effect, Layer, ManagedRuntime, Predicate, Schema, Stream } from "effect"
import { Rpc, RpcGroup, RpcMessage, RpcServer } from "effect/rpc"
import { Transferable } from "effect/workers"
import { omitUndefined } from "../shared/ipc-transport"
import { EventRpcs, MenuCommandTriggered } from "../shared/ipc-rpc/events"
import { FilesOpenFilePicker } from "../shared/ipc-rpc/files"
import { emitIpcEvent } from "./ipc-events"
import { eventHandlers } from "./ipc-handlers/events"
import { IpcPortHandoff, IpcServerProtocolLive } from "./ipc-transport"
describe("desktop RPC transport", () => {
@@ -116,8 +119,77 @@ describe("desktop RPC transport", () => {
for (const port of [first.port2, second.port2, reloaded.port2]) port.close()
await runtime.dispose()
})
test("delivers events sent between a window's snapshot and its port binding", async () => {
const runtime = ManagedRuntime.make(eventsLive)
const handoff = await runtime.runPromise(IpcPortHandoff)
const win = sender(1)
// A window that has not asked for its snapshot has no document to hold events for.
expect(emitIpcEvent(win, new MenuCommandTriggered({ id: "early" }))).toBe(false)
handoff.prepare(win)
// On dev these were dropped: the window had no event queue until its port bound.
expect(emitIpcEvent(win, new MenuCommandTriggered({ id: "a" }))).toBe(true)
expect(emitIpcEvent(win, new MenuCommandTriggered({ id: "b" }))).toBe(true)
const channel = new MessageChannel()
handoff.bind(win, serverPort(channel.port1))
emitIpcEvent(win, new MenuCommandTriggered({ id: "c" }))
expect(await chunks(channel.port2, 0, "DesktopEvents", 3)).toEqual(["a", "b", "c"].map(menuCommand))
channel.port2.close()
await runtime.dispose()
})
test("lets a reloading window's old port finish its flush while events wait for the new document", async () => {
const runtime = ManagedRuntime.make(eventsLive)
const handoff = await runtime.runPromise(IpcPortHandoff)
const disconnected: number[] = []
handoff.onDisconnect((clientId) => disconnected.push(clientId))
const win = sender(1)
const first = new MessageChannel()
handoff.bind(win, serverPort(first.port1))
const firstEvents = call(first.port2, 0, "DesktopEvents", null)
const flush = call(first.port2, 1, "test.flush", null)
await Effect.runPromise(Deferred.await(flushStarted))
// The new document's snapshot: the old one stops receiving events but still answers its RPCs.
handoff.prepare(win)
expect((await firstEvents).chunks).toEqual([])
emitIpcEvent(win, new MenuCommandTriggered({ id: "during reload" }))
Effect.runSync(Deferred.succeed(flushGate, undefined))
expect((await flush).exit).toEqual(success("flushed"))
const second = new MessageChannel()
handoff.bind(win, serverPort(second.port1))
expect(await chunks(second.port2, 0, "DesktopEvents", 1)).toEqual([menuCommand("during reload")])
expect(disconnected).toEqual([0])
for (const port of [first.port2, second.port2]) port.close()
await runtime.dispose()
})
})
const flushStarted = Effect.runSync(Deferred.make<void>())
const flushGate = Effect.runSync(Deferred.make<void>())
const FlushRpcs = RpcGroup.make(Rpc.make("test.flush", { success: Schema.String }))
const flushHandlers = FlushRpcs.toLayer({
"test.flush": () =>
Deferred.succeed(flushStarted, undefined).pipe(Effect.andThen(Deferred.await(flushGate)), Effect.as("flushed")),
})
const eventsLive = RpcServer.layer(EventRpcs.merge(FlushRpcs)).pipe(
Layer.provide(Layer.mergeAll(eventHandlers, flushHandlers)),
Layer.provideMerge(IpcServerProtocolLive),
)
function menuCommand(id: string) {
return Schema.encodeSync(MenuCommandTriggered)(new MenuCommandTriggered({ id }))
}
class TestEvent extends Schema.TaggedClass<TestEvent>()("TestEvent", { value: Schema.String }) {}
const TestRpcs = RpcGroup.make(
@@ -161,6 +233,26 @@ function call(port: MessageChannel["port2"], id: number, tag: string, payload: R
port.postMessage({ _tag: "Request", id, tag, payload, headers: [] })
})
}
// Subscribes to a stream that never ends and settles once `count` values have arrived.
function chunks(port: MessageChannel["port2"], id: number, tag: string, count: number) {
const values: unknown[] = []
return new Promise<unknown[]>((resolve) => {
const onMessage = (message: RpcMessage.FromServerEncoded) => {
if (!Predicate.isTagged(message, "Chunk") || Number(message.requestId) !== id) return
values.push(...message.values)
port.postMessage({ _tag: "Ack", requestId: message.requestId } satisfies RpcMessage.AckEncoded)
if (values.length < count) return
port.off("message", onMessage)
resolve(values)
}
port.on("message", onMessage)
port.postMessage({ _tag: "Request", id, tag, payload: null, headers: [] })
})
}
/* oxlint-enable anti-slop-effect/no-manual-tagged-construction */
function sender(id: number) {
+149 -91
View File
@@ -1,127 +1,185 @@
import type { MessagePortMain, WebContents } from "electron"
import { Context, Effect, Layer, Option, Queue, Schema, Stream } from "effect"
import { RpcMessage, RpcServer } from "effect/rpc"
import { bindIpcEvents } from "./ipc-events"
type PortBinding = {
readonly id: number
readonly sender: WebContents
readonly port: MessagePortMain
readonly onMessage: (event: Electron.MessageEvent) => void
readonly onClose: () => void
readonly unbindEvents: Effect.Effect<void>
}
import type { DesktopEvent } from "../shared/ipc-rpc/events"
import { setIpcEventSink } from "./ipc-events"
import {
createIpcTransportState,
selectBoundClientId,
selectBoundEventQueue,
selectClientEventQueue,
selectClientIds,
selectClientPort,
selectClientSender,
transitionIpcTransport,
type IpcTransportCommand,
type IpcTransportEvent,
} from "./ipc-machine"
type Handoff = {
/** Holds a window's events from now until its next document binds a port; call when a document starts loading. */
readonly prepare: (sender: WebContents) => void
readonly bind: (sender: WebContents, port: MessagePortMain) => void
readonly sender: (clientId: number) => WebContents | undefined
/** Runs after a renderer port closes or is replaced, before a replacement port for its sender binds. */
/** The event queue a client's `DesktopEvents` stream reads; none once its document is unloading. */
readonly events: (clientId: number) => Queue.Queue<DesktopEvent> | undefined
/** Whether the client is the one receiving the sender's events, rather than a document it replaced. */
readonly isCurrentClient: (sender: WebContents, clientId: number) => boolean
/** Runs when a renderer stops receiving events: its port closed, or its document unloads or was replaced. */
readonly onDisconnect: (listener: (clientId: number) => void) => () => void
}
export class IpcPortHandoff extends Context.Service<IpcPortHandoff, Handoff>()("opencode/desktop/IpcPortHandoff") {}
type TransportEvent = IpcTransportEvent<WebContents, MessagePortMain, Queue.Queue<DesktopEvent>, DesktopEvent>
type TransportCommand = IpcTransportCommand<WebContents, MessagePortMain, Queue.Queue<DesktopEvent>, DesktopEvent>
type PortListeners = { readonly onMessage: (event: Electron.MessageEvent) => void; readonly onClose: () => void }
// Messages cross the port by structured clone, like Effect's worker protocol: no serialization
// layer, so binary payloads stay binary and nothing is packed into a shared buffer. Electron's
// MessagePortMain can only transfer ports, so byte payloads are cloned in both directions.
export const IpcServerProtocolLive = Layer.unwrap(
Effect.gen(function* () {
const handoffs = yield* Queue.unbounded<readonly [WebContents, MessagePortMain]>()
const bindings = new Map<number, PortBinding>()
const senderBindings = new Map<number, number>()
const runSync = Effect.runSyncWith(yield* Effect.context())
const disconnects = yield* Queue.unbounded<number>()
const inbound = yield* Queue.unbounded<readonly [number, RpcMessage.FromClientEncoded]>()
const disconnected = new Set<(clientId: number) => void>()
const senderListeners = new Map<number, () => void>()
const portListeners = new Map<MessagePortMain, PortListeners>()
let state = createIpcTransportState<WebContents, MessagePortMain, Queue.Queue<DesktopEvent>, DesktopEvent>()
const protocol = Layer.effect(
RpcServer.Protocol,
RpcServer.Protocol.make(
Effect.fnUntraced(function* (writeRequest) {
const disconnects = yield* Queue.unbounded<number>()
const inbound = yield* Queue.unbounded<readonly [number, RpcMessage.FromClientEncoded]>()
const runFork = Effect.runForkWith(yield* Effect.context())
let nextClientId = 0
const dispatch = (event: TransportEvent) => {
const next = transitionIpcTransport(state, event)
// Commit first: disconnect listeners (deep links) emit events that read the new state.
state = next.state
next.commands.forEach(perform)
}
const disconnect = Effect.fnUntraced(function* (id: number) {
const binding = bindings.get(id)
const perform = (command: TransportCommand) => {
switch (command.type) {
case "watch-sender": {
const onDestroyed = () => dispatch({ type: "sender.destroyed", senderId: command.senderId })
senderListeners.set(command.senderId, onDestroyed)
command.sender.once("destroyed", onDestroyed)
if (!binding) return
bindings.delete(id)
return
}
if (senderBindings.get(binding.sender.id) === id) senderBindings.delete(binding.sender.id)
binding.port.off("message", binding.onMessage)
binding.port.off("close", binding.onClose)
binding.sender.off("destroyed", binding.onClose)
yield* binding.unbindEvents
binding.port.close()
disconnected.forEach((listener) => listener(id))
Queue.offerUnsafe(disconnects, id)
})
case "unwatch-sender": {
const onDestroyed = senderListeners.get(command.senderId)
senderListeners.delete(command.senderId)
const bind = Effect.fnUntraced(function* (sender: WebContents, port: MessagePortMain) {
const previous = senderBindings.get(sender.id)
if (onDestroyed) command.sender.off("destroyed", onDestroyed)
if (previous !== undefined) yield* disconnect(previous)
return
}
if (sender.isDestroyed()) {
port.close()
return
}
const id = nextClientId++
const onMessage = (event: Electron.MessageEvent) => {
case "attach-port": {
const listeners = {
onMessage: (event: Electron.MessageEvent) => {
// SAFETY: the other end of this port is the renderer's ipc-client, which posts only RPC client
// messages; the RPC server decodes each request's payload with that RPC's schema.
Queue.offerUnsafe(inbound, [id, event.data as RpcMessage.FromClientEncoded] as const)
}
const onClose = () => runFork(disconnect(id))
const unbindEvents = yield* bindIpcEvents(sender.id)
const binding = { id, sender, port, onMessage, onClose, unbindEvents }
bindings.set(id, binding)
senderBindings.set(sender.id, id)
port.on("message", onMessage)
port.on("close", onClose)
sender.once("destroyed", onClose)
port.start()
})
yield* Stream.fromQueue(handoffs).pipe(
Stream.runForEach(([sender, port]) => bind(sender, port)),
Effect.forkScoped,
)
yield* Stream.fromQueue(inbound).pipe(
Stream.runForEach(([id, message]) => (bindings.has(id) ? writeRequest(id, message) : Effect.void)),
Effect.forkScoped,
)
yield* Effect.addFinalizer(() => Effect.forEach([...bindings.keys()], disconnect, { discard: true }))
return {
codecFor: Schema.toCodecJson,
disconnects,
send: (clientId, response) =>
Effect.sync(() => {
bindings.get(clientId)?.port.postMessage(response)
}),
end: disconnect,
clientIds: Effect.sync(() => new Set(bindings.keys())),
initialMessage: Effect.succeed(Option.none()),
supportsAck: true,
supportsTransferables: false,
supportsSpanPropagation: false,
supportsNotifications: true,
Queue.offerUnsafe(inbound, [command.clientId, event.data as RpcMessage.FromClientEncoded] as const)
},
onClose: () => dispatch({ type: "client.closed", clientId: command.clientId }),
}
}),
),
portListeners.set(command.port, listeners)
command.port.on("message", listeners.onMessage)
command.port.on("close", listeners.onClose)
command.port.start()
return
}
case "close-port": {
// Detach before closing so the port's own close event does not dispatch again.
const listeners = portListeners.get(command.port)
portListeners.delete(command.port)
if (listeners) {
command.port.off("message", listeners.onMessage)
command.port.off("close", listeners.onClose)
}
command.port.close()
return
}
case "offer-events":
return void Queue.offerAllUnsafe(command.events, command.items)
case "shutdown-events":
return void runSync(Queue.shutdown(command.events))
case "notify-disconnect":
return disconnected.forEach((listener) => listener(command.clientId))
case "end-client":
return void Queue.offerUnsafe(disconnects, command.clientId)
}
}
const protocol = yield* RpcServer.Protocol.make(
Effect.fnUntraced(function* (writeRequest) {
yield* Stream.fromQueue(inbound).pipe(
Stream.runForEach(([id, message]) => (selectClientPort(state, id) ? writeRequest(id, message) : Effect.void)),
Effect.forkScoped,
)
return {
codecFor: Schema.toCodecJson,
disconnects,
send: (clientId, response) =>
Effect.sync(() => {
selectClientPort(state, clientId)?.postMessage(response)
}),
end: (clientId) => Effect.sync(() => dispatch({ type: "client.closed", clientId })),
clientIds: Effect.sync(() => selectClientIds(state)),
initialMessage: Effect.succeed(Option.none()),
supportsAck: true,
supportsTransferables: false,
supportsSpanPropagation: false,
supportsNotifications: true,
}
}),
)
const clearSink = setIpcEventSink((sender, event) => {
const queue = selectBoundEventQueue(state, sender.id)
if (queue) return Queue.offerUnsafe(queue, event)
const before = state
dispatch({ type: "event.emitted", senderId: sender.id, event })
// Held for a document that has not bound its port yet.
return state !== before
})
yield* Effect.addFinalizer(() =>
Effect.sync(() => {
clearSink()
dispatch({ type: "disposed" })
}),
)
return Layer.merge(
protocol,
Layer.succeed(RpcServer.Protocol)(protocol),
Layer.succeed(IpcPortHandoff)({
bind: (sender, port) => {
Queue.offerUnsafe(handoffs, [sender, port])
prepare: (sender) => {
if (!sender.isDestroyed()) dispatch({ type: "sender.prepared", senderId: sender.id, sender })
},
sender: (clientId) => bindings.get(clientId)?.sender,
bind: (sender, port) => {
// A destroyed window already released whatever it held.
if (sender.isDestroyed()) return port.close()
dispatch({ type: "port.bound", senderId: sender.id, sender, port, events: runSync(Queue.unbounded()) })
},
sender: (clientId) => selectClientSender(state, clientId),
events: (clientId) => selectClientEventQueue(state, clientId),
isCurrentClient: (sender, clientId) => selectBoundClientId(state, sender.id) === clientId,
onDisconnect: (listener) => {
disconnected.add(listener)
+8
View File
@@ -20,7 +20,9 @@ import { showCliInstaller } from "./native/install-cli"
import { createMenu, disposeMenu, refreshMenu } from "./native/menu"
import { onNativeTranslations } from "./native/translations"
import { DesktopCli } from "./service/desktop-cli"
import { setStorageSnapshotObserver } from "./storage/snapshot"
import { getLastFocusedWindow } from "./windows"
import { isRendererUrl } from "./windows/scheme"
const services = Layer.mergeAll(DesktopFiles.layer, Plugins.layer)
@@ -72,6 +74,10 @@ export const registerIpcHandlers = Effect.gen(function* () {
win.webContents.postMessage(IpcTransportPort, null, [channel.port2])
}
// A committed document replaces the bound one; its events wait for the port posted when it loads.
win.webContents.on("did-navigate", (_event, url) => {
if (isRendererUrl(url)) handoff.prepare(win.webContents)
})
win.webContents.on("did-finish-load", post)
// The first window starts loading before the layers exist and may already be done.
@@ -81,6 +87,8 @@ export const registerIpcHandlers = Effect.gen(function* () {
const onWindowCreated = (_event: Electron.Event, win: BrowserWindow) => wire(win)
const stopDisconnects = handoff.onDisconnect(lifecycle.deepLinks.disconnect)
yield* Effect.addFinalizer(() => Effect.sync(stopDisconnects))
const stopSnapshots = setStorageSnapshotObserver(handoff.prepare)
yield* Effect.addFinalizer(() => Effect.sync(stopSnapshots))
// A language the renderer pushes rebuilds the menu once it is installed.
const stopTranslations = onNativeTranslations(refreshMenu)
yield* Effect.addFinalizer(() =>
+15 -1
View File
@@ -1,4 +1,4 @@
import { app, ipcMain } from "electron"
import { app, ipcMain, type WebContents } from "electron"
import { WindowSnapshotChannel, type WindowSnapshot } from "../../shared/ipc-transport"
import { isRendererUrl } from "../windows/scheme"
import { readWindowSnapshot } from "./window-snapshot"
@@ -14,6 +14,18 @@ export function setStorageSnapshotProvider(next: Provider) {
provider = next
}
// Hears about a snapshot just before it is read, so the window holds the changes made after it
// until its document can receive them.
let observer: ((sender: WebContents) => void) | undefined
export function setStorageSnapshotObserver(next: (sender: WebContents) => void) {
observer = next
return () => {
if (observer === next) observer = undefined
}
}
export function registerStorageSnapshotHandler() {
// SAFETY: Electron delivers untrusted IPC arguments; accept only an array whose every element is a string here.
// oxlint-disable-next-line anti-slop/no-unknown-parameters -- see SAFETY above
@@ -24,6 +36,8 @@ export function registerStorageSnapshotHandler() {
// oxlint-disable-next-line anti-slop/no-runtime-typeof -- see SAFETY above
if (!Array.isArray(names) || !names.every((name) => typeof name === "string")) return { storage: {} }
observer?.(event.sender)
return provider(names)
})
}
@@ -0,0 +1,202 @@
import { describe, expect, test } from "bun:test"
import type { RpcMessage } from "effect/rpc"
import {
createIpcClientState,
ipcClosedError,
selectPendingChunk,
transitionIpcClient,
type IpcClientCommand,
type IpcClientEvent,
type IpcClientState,
type IpcPending,
} from "./ipc-client-machine"
type State = IpcClientState<string>
type Event = IpcClientEvent<string>
type Command = IpcClientCommand<string>
// SAFETY: requests are the RPC wire format's plain encoded messages, as ipc-client.ts builds them.
/* oxlint-disable anti-slop-effect/no-manual-tagged-construction -- see SAFETY above */
function message(id: number, tag: string): RpcMessage.RequestEncoded {
return { _tag: "Request", id, tag, payload: null, headers: [] }
}
/* oxlint-enable anti-slop-effect/no-manual-tagged-construction */
function entry(): IpcPending {
return { resolve: () => undefined, reject: () => undefined }
}
function started(id: number, tag: string, pending = entry()): Event {
return { type: "request.started", id, message: message(id, tag), entry: pending }
}
function replay(events: readonly Event[], from: State = createIpcClientState()) {
return events.reduce<{ state: State; commands: Command[] }>(
(result, event) => {
const next = transitionIpcClient(result.state, event)
return { state: next.state, commands: [...result.commands, ...next.commands] }
},
{ state: from, commands: [] },
)
}
describe("IPC client machine", () => {
test("fails waiting requests when main never posts the port", () => {
// On dev the port promise had no timeout, so every invoke and the startup splash waited forever.
const init = entry()
const theme = entry()
const waiting = replay([
started(0, "DesktopEvents", { ...entry(), chunk: () => undefined }),
started(1, "AppAwaitInitialization", init),
started(2, "AppThemeReady", theme),
])
const timedOut = transitionIpcClient(waiting.state, { type: "handshake.timed-out" })
expect(timedOut.state.status).toBe("timed-out")
expect(timedOut.commands).toEqual([{ type: "reject", entries: [init, theme], error: ipcClosedError("timeout") }])
const late = entry()
expect(transitionIpcClient(timedOut.state, started(3, "AppThemeReady", late)).commands).toEqual([
{ type: "reject", entries: [late], error: new Error("Desktop IPC port handshake timed out") },
])
})
test("connects a port that arrives after the handshake timed out", () => {
// A slow subresource holds back the load event main posts the port on; the document still gets its IPC.
const chunk = () => undefined
const timedOut = replay([
started(0, "DesktopEvents", { ...entry(), chunk }),
started(1, "AppThemeReady"),
{ type: "handshake.timed-out" },
])
const connected = transitionIpcClient(timedOut.state, { type: "port.received", port: "late" })
expect(connected.state.status).toBe("connected")
expect(connected.commands).toEqual([
{ type: "cancel-handshake-timer" },
{ type: "unlisten-window" },
{ type: "attach-port", port: "late" },
{ type: "post-request", port: "late", message: message(0, "DesktopEvents") },
])
// Events reach the subscription, and new calls go straight to the port.
expect(selectPendingChunk(connected.state, 0)).toBe(chunk)
expect(transitionIpcClient(connected.state, started(2, "AppThemeReady")).commands).toEqual([
{ type: "post-request", port: "late", message: message(2, "AppThemeReady") },
])
})
test("never sends a request aborted before the port arrives", () => {
// On dev the request was posted when the port arrived, ahead of its interrupt, so main ran it.
const aborted = entry()
const waiting = replay([
started(0, "DesktopEvents"),
started(1, "FilesOpenFilePicker", aborted),
started(2, "StorageItems"),
{ type: "request.aborted", id: 1, reason: "cancelled" },
])
expect(waiting.commands).toEqual([{ type: "reject", entries: [aborted], error: "cancelled" }])
expect(transitionIpcClient(waiting.state, { type: "port.received", port: "p" }).commands).toEqual([
{ type: "cancel-handshake-timer" },
{ type: "unlisten-window" },
{ type: "attach-port", port: "p" },
{ type: "post-request", port: "p", message: message(0, "DesktopEvents") },
{ type: "post-request", port: "p", message: message(2, "StorageItems") },
])
})
test("posts a connected request in the same turn and interrupts it on abort", () => {
const connected = replay([{ type: "port.received", port: "p" }]).state
const posted = transitionIpcClient(connected, started(0, "StorageUpdate"))
expect(posted.commands).toEqual([{ type: "post-request", port: "p", message: message(0, "StorageUpdate") }])
const aborted = transitionIpcClient(posted.state, { type: "request.aborted", id: 0, reason: "stop" })
expect(aborted.commands).toEqual([
{ type: "reject", entries: [expect.anything()], error: "stop" },
{ type: "post-interrupt", port: "p", requestId: 0 },
])
expect(transitionIpcClient(aborted.state, { type: "request.aborted", id: 0, reason: "stop" }).state).toBe(
aborted.state,
)
})
test("settles each request once from its exit", () => {
const succeeded = entry()
const failed = entry()
const connected = replay([
started(0, "A", succeeded),
started(1, "B", failed),
{ type: "port.received", port: "p" },
])
const settled = replay(
[
{ type: "response.exited", id: 0, exit: { ok: true, value: 42 } },
{ type: "response.exited", id: 1, exit: { ok: false, error: "nope" } },
],
connected.state,
)
expect(settled.commands).toEqual([
{ type: "resolve", entry: succeeded, value: 42 },
{ type: "reject", entries: [failed], error: "nope" },
])
const again = transitionIpcClient(settled.state, { type: "response.exited", id: 0, exit: { ok: true, value: 1 } })
expect(again.state).toBe(settled.state)
})
test("streams chunks only to a pending request", () => {
const chunk = () => undefined
const connected = replay([started(0, "DesktopEvents", { ...entry(), chunk }), { type: "port.received", port: "p" }])
expect(selectPendingChunk(connected.state, 0)).toBe(chunk)
expect(selectPendingChunk(connected.state, 1)).toBeUndefined()
})
test("fails every pending request on a server defect", () => {
const first = entry()
const second = entry()
const connected = replay([started(0, "A", first), started(1, "B", second), { type: "port.received", port: "p" }])
const error = new Error("Desktop IPC defect")
const defected = transitionIpcClient(connected.state, { type: "server.defected", error })
expect(defected.commands).toEqual([{ type: "reject", entries: [first, second], error }])
expect(transitionIpcClient(defected.state, { type: "server.defected", error }).state).toBe(defected.state)
})
test.each([
{
name: "connected",
events: [{ type: "port.received", port: "p" }] satisfies Event[],
release: [{ type: "close-port", port: "p" }] satisfies Command[],
},
{
name: "still waiting for its port",
events: [] satisfies Event[],
release: [{ type: "cancel-handshake-timer" }, { type: "unlisten-window" }] satisfies Command[],
},
])("closes on pagehide while $name and fails what is unsettled", (input) => {
const unsettled = entry()
const before = replay([started(0, "StorageItems", unsettled), ...input.events])
const disposed = transitionIpcClient(before.state, { type: "disposed" })
expect(disposed.state).toEqual({ status: "closed" })
expect(disposed.commands).toEqual([
...input.release,
{ type: "reject", entries: [unsettled], error: new Error("Desktop IPC connection closed") },
])
})
test("ignores a timer that fires after the port arrived", () => {
const connected = replay([{ type: "port.received", port: "p" }]).state
expect(transitionIpcClient(connected, { type: "handshake.timed-out" }).state).toBe(connected)
expect(transitionIpcClient(connected, { type: "port.received", port: "extra" }).commands).toEqual([
{ type: "close-port", port: "extra" },
])
})
})
@@ -0,0 +1,204 @@
import type { RpcMessage } from "effect/rpc"
/** How long a renderer waits for main to post its IPC port before failing the calls waiting on it. */
export const PORT_HANDSHAKE_TIMEOUT_MS = 30_000
export type IpcCloseReason = "timeout" | "disposed"
export type IpcPending = {
// SAFETY: the reply is the RPC's success value as the trusted main process encoded it; callers narrow it at `invoke`.
// oxlint-disable-next-line anti-slop/no-unknown-parameters -- see SAFETY above
readonly resolve: (value: unknown) => void
readonly reject: (cause: unknown) => void
/** Present for streams (the event subscription), which wait for the port even after the handshake times out. */
readonly chunk?: (values: ReadonlyArray<unknown>) => void
}
export type IpcQueuedRequest = { readonly id: number; readonly message: RpcMessage.RequestEncoded }
// `timed-out` still waits for the port: main posts it once the document's load event fires, which a
// slow subresource can hold back. Calls fail fast there; streams queue and start when the port arrives.
export type IpcClientState<Port> =
| {
readonly status: "awaiting-port" | "timed-out"
/** Requests to post, in order, once the port arrives. */
readonly queued: readonly IpcQueuedRequest[]
readonly pending: ReadonlyMap<number, IpcPending>
}
| { readonly status: "connected"; readonly port: Port; readonly pending: ReadonlyMap<number, IpcPending> }
| { readonly status: "closed" }
export type IpcExit = { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: unknown }
export type IpcClientEvent<Port> =
| {
readonly type: "request.started"
readonly id: number
readonly message: RpcMessage.RequestEncoded
readonly entry: IpcPending
}
| { readonly type: "request.aborted"; readonly id: number; readonly reason: unknown }
| { readonly type: "port.received"; readonly port: Port }
| { readonly type: "handshake.timed-out" }
| { readonly type: "response.exited"; readonly id: number; readonly exit: IpcExit }
| { readonly type: "server.defected"; readonly error: unknown }
| { readonly type: "disposed" }
export type IpcClientCommand<Port> =
| { readonly type: "cancel-handshake-timer" }
| { readonly type: "unlisten-window" }
| { readonly type: "attach-port"; readonly port: Port }
| { readonly type: "close-port"; readonly port: Port }
| { readonly type: "post-request"; readonly port: Port; readonly message: RpcMessage.RequestEncoded }
| { readonly type: "post-interrupt"; readonly port: Port; readonly requestId: number }
| { readonly type: "resolve"; readonly entry: IpcPending; readonly value: unknown }
| { readonly type: "reject"; readonly entries: readonly IpcPending[]; readonly error: unknown }
export type IpcClientTransition<Port> = {
readonly state: IpcClientState<Port>
readonly commands: readonly IpcClientCommand<Port>[]
}
/** The state a renderer starts in; its driver starts the handshake timer with it. */
export function createIpcClientState<Port>(): IpcClientState<Port> {
return { status: "awaiting-port", queued: [], pending: new Map() }
}
export function transitionIpcClient<Port>(
state: IpcClientState<Port>,
event: IpcClientEvent<Port>,
): IpcClientTransition<Port> {
if (state.status === "closed") {
if (event.type === "request.started")
return { state, commands: [{ type: "reject", entries: [event.entry], error: ipcClosedError("disposed") }] }
if (event.type === "port.received") return { state, commands: [{ type: "close-port", port: event.port }] }
return { state, commands: [] }
}
switch (event.type) {
case "request.started": {
if (state.status === "timed-out" && !event.entry.chunk)
return { state, commands: [{ type: "reject", entries: [event.entry], error: ipcClosedError("timeout") }] }
const pending = new Map(state.pending).set(event.id, event.entry)
if (state.status !== "connected")
return {
state: { ...state, queued: [...state.queued, { id: event.id, message: event.message }], pending },
commands: [],
}
// Posted in this turn, so a pagehide flush reaches the port before the document goes.
return {
state: { ...state, pending },
commands: [{ type: "post-request", port: state.port, message: event.message }],
}
}
case "request.aborted": {
const entry = state.pending.get(event.id)
if (!entry) return { state, commands: [] }
const pending = new Map(state.pending)
pending.delete(event.id)
const reject: IpcClientCommand<Port> = { type: "reject", entries: [entry], error: event.reason }
// A request that never left the renderer is dropped, so main never runs it.
if (state.status !== "connected")
return {
state: { ...state, queued: state.queued.filter((request) => request.id !== event.id), pending },
commands: [reject],
}
return {
state: { ...state, pending },
commands: [reject, { type: "post-interrupt", port: state.port, requestId: event.id }],
}
}
case "port.received": {
if (state.status === "connected") return { state, commands: [{ type: "close-port", port: event.port }] }
return {
state: { status: "connected", port: event.port, pending: state.pending },
commands: [
{ type: "cancel-handshake-timer" },
{ type: "unlisten-window" },
{ type: "attach-port", port: event.port },
...state.queued.map(
(request): IpcClientCommand<Port> => ({
type: "post-request",
port: event.port,
message: request.message,
}),
),
],
}
}
case "handshake.timed-out": {
if (state.status !== "awaiting-port") return { state, commands: [] }
const calls = [...state.pending].filter(([, entry]) => !entry.chunk)
const pending = new Map([...state.pending].filter(([, entry]) => entry.chunk))
return {
state: { status: "timed-out", queued: state.queued.filter((request) => pending.has(request.id)), pending },
commands:
calls.length > 0
? [{ type: "reject", entries: calls.map(([, entry]) => entry), error: ipcClosedError("timeout") }]
: [],
}
}
case "response.exited": {
if (state.status !== "connected") return { state, commands: [] }
const entry = state.pending.get(event.id)
if (!entry) return { state, commands: [] }
const pending = new Map(state.pending)
pending.delete(event.id)
return {
state: { ...state, pending },
commands: [
event.exit.ok
? { type: "resolve", entry, value: event.exit.value }
: { type: "reject", entries: [entry], error: event.exit.error },
],
}
}
case "server.defected": {
if (state.status !== "connected" || state.pending.size === 0) return { state, commands: [] }
return {
state: { ...state, pending: new Map() },
commands: [{ type: "reject", entries: [...state.pending.values()], error: event.error }],
}
}
case "disposed":
return {
state: { status: "closed" },
commands: [
...(state.status === "connected"
? [{ type: "close-port" as const, port: state.port }]
: [{ type: "cancel-handshake-timer" as const }, { type: "unlisten-window" as const }]),
...(state.pending.size > 0
? [{ type: "reject" as const, entries: [...state.pending.values()], error: ipcClosedError("disposed") }]
: []),
],
}
}
}
/** The pending request a streamed chunk belongs to; read on every chunk, so it allocates nothing. */
export function selectPendingChunk<Port>(state: IpcClientState<Port>, requestId: number) {
return state.status === "closed" ? undefined : state.pending.get(requestId)?.chunk
}
export function ipcClosedError(reason: IpcCloseReason) {
return new Error(reason === "timeout" ? "Desktop IPC port handshake timed out" : "Desktop IPC connection closed")
}
+84 -57
View File
@@ -3,6 +3,15 @@ import type { RpcMessage } from "effect/rpc"
import type { DesktopRpcClient } from "../shared/ipc-rpc"
import type { DesktopEvent } from "../shared/ipc-rpc/events"
import { IpcTransportPort, omitUndefined } from "../shared/ipc-transport"
import {
createIpcClientState,
PORT_HANDSHAKE_TIMEOUT_MS,
selectPendingChunk,
transitionIpcClient,
type IpcClientCommand,
type IpcClientEvent,
type IpcPending,
} from "./ipc-client-machine"
// The main process serves Effect's RpcServer over a MessagePort; this side speaks its wire format
// directly. Messages cross by structured clone (no serialization layer, binary stays binary), every
@@ -21,51 +30,42 @@ type InvokeResult<Tag extends InvokeTag> =
type EventValue<Tag extends EventTag> = Extract<DesktopEvent, { readonly _tag: Tag }>
type Pending = {
// SAFETY: the reply is the RPC's success value as the trusted main process encoded it; see the note above.
// oxlint-disable-next-line anti-slop/no-unknown-parameters -- see SAFETY above
readonly resolve: (value: unknown) => void
readonly reject: (cause: unknown) => void
readonly chunk?: (values: ReadonlyArray<unknown>) => void
}
const pending = new Map<number, Pending>()
const listeners = new Map<EventTag, Set<(value: DesktopEvent) => void>>()
// SAFETY: pagehide only waits for these callbacks to settle and ignores what they resolve to.
// oxlint-disable-next-line anti-slop/no-unknown-returns -- see SAFETY above
const beforeDispose = new Set<() => Promise<unknown> | void>()
let state = createIpcClientState<MessagePort>()
let nextId = 0
const port = new Promise<MessagePort>((resolve) => {
const onMessage = (event: MessageEvent) => {
if (event.source !== window || event.data !== IpcTransportPort) return
const value = event.ports[0]
const onWindowMessage = (event: MessageEvent) => {
if (event.source !== window || event.data !== IpcTransportPort) return
const value = event.ports[0]
if (!value) return
window.removeEventListener("message", onMessage)
// SAFETY: the port comes from the trusted main process, whose RPC server posts only its own messages.
value.addEventListener("message", (message) => receive(value, message.data as RpcMessage.FromServerEncoded))
value.start()
resolve(value)
}
if (value) dispatch({ type: "port.received", port: value })
}
window.addEventListener("message", onMessage)
})
window.addEventListener("message", onWindowMessage)
const handshakeTimer = setTimeout(() => dispatch({ type: "handshake.timed-out" }), PORT_HANDSHAKE_TIMEOUT_MS)
// Let queued work (storage flushes) hand its messages to the port before it closes.
window.addEventListener(
"pagehide",
() => void Promise.allSettled([...beforeDispose].map((callback) => callback())).then(() => port.then((p) => p.close())),
() =>
void Promise.allSettled([...beforeDispose].map((callback) => callback())).then(() =>
dispatch({ type: "disposed" }),
),
{ once: true },
)
void request("DesktopEvents", null, (values) => {
// The event stream outlives a handshake timeout; only pagehide rejects it, and nobody is left to tell.
request("DesktopEvents", null, (values) => {
// SAFETY: DesktopEvents streams desktop events, whose encoded fields are JSON-native and read as decoded.
for (const value of values as ReadonlyArray<DesktopEvent>) listeners.get(value._tag)?.forEach((fn) => fn(value))
})
}).catch(() => undefined)
// SAFETY: as for `beforeDispose`, the callback's result is only awaited, never read.
// oxlint-disable-next-line anti-slop/no-unknown-returns -- see SAFETY above
@@ -114,7 +114,7 @@ export function listen<Tag extends EventTag>(tag: Tag, listener: (value: EventVa
function request(
tag: InvokeTag | "DesktopEvents",
payload: InvokeArgs<InvokeTag>[0] | null,
chunk?: Pending["chunk"],
chunk?: IpcPending["chunk"],
signal?: AbortSignal,
) {
const id = nextId++
@@ -122,11 +122,7 @@ function request(
return new Promise<unknown>((resolve, reject) => {
if (signal?.aborted) return reject(signal.reason)
const abort = () => {
if (!pending.delete(id)) return
reject(signal?.reason)
void port.then((p) => p.postMessage({ _tag: "Interrupt", requestId: id } satisfies RpcMessage.InterruptEncoded))
}
const abort = () => dispatch({ type: "request.aborted", id, reason: signal?.reason })
signal?.addEventListener("abort", abort, { once: true })
@@ -137,48 +133,79 @@ function request(
callback(value)
}
pending.set(id, { resolve: settle(resolve), reject: settle(reject), chunk })
const message: RpcMessage.RequestEncoded = {
_tag: "Request",
dispatch({
type: "request.started",
id,
tag,
payload: omitUndefined(payload),
headers: [],
message: { _tag: "Request", id, tag, payload: omitUndefined(payload), headers: [] },
entry: { resolve: settle(resolve), reject: settle(reject), chunk },
})
})
}
function dispatch(event: IpcClientEvent<MessagePort>) {
const next = transitionIpcClient(state, event)
state = next.state
next.commands.forEach(perform)
}
function perform(command: IpcClientCommand<MessagePort>) {
switch (command.type) {
case "cancel-handshake-timer":
return clearTimeout(handshakeTimer)
case "unlisten-window":
return window.removeEventListener("message", onWindowMessage)
case "attach-port": {
const port = command.port
// SAFETY: the port comes from the trusted main process, whose RPC server posts only its own messages.
port.addEventListener("message", (message) => receive(port, message.data as RpcMessage.FromServerEncoded))
port.start()
return
}
void port.then((p) => p.postMessage(message))
})
case "close-port":
return command.port.close()
case "post-request":
return command.port.postMessage(command.message)
case "post-interrupt":
return command.port.postMessage({
_tag: "Interrupt",
requestId: command.requestId,
} satisfies RpcMessage.InterruptEncoded)
case "resolve":
return command.entry.resolve(command.value)
case "reject":
return command.entries.forEach((entry) => entry.reject(command.error))
}
}
function receive(p: MessagePort, message: RpcMessage.FromServerEncoded) {
switch (message._tag) {
case "Chunk": {
pending.get(Number(message.requestId))?.chunk?.(message.values)
selectPendingChunk(state, Number(message.requestId))?.(message.values)
p.postMessage({ _tag: "Ack", requestId: message.requestId } satisfies RpcMessage.AckEncoded)
return
}
case "Exit": {
const id = Number(message.requestId)
const entry = pending.get(id)
pending.delete(id)
const exit = message.exit
if (!entry) return
if (message.exit._tag === "Success") return entry.resolve(message.exit.value)
return entry.reject(failure(message.exit.cause))
return dispatch({
type: "response.exited",
id: Number(message.requestId),
exit: exit._tag === "Success" ? { ok: true, value: exit.value } : { ok: false, error: failure(exit.cause) },
})
}
case "Defect": {
const error = new Error("Desktop IPC defect", { cause: message.defect })
pending.forEach((entry) => entry.reject(error))
pending.clear()
return
}
case "Defect":
return dispatch({ type: "server.defected", error: new Error("Desktop IPC defect", { cause: message.defect }) })
case "ClientProtocolError": {
console.error("[desktop-ipc] protocol error", message.error)