-
-
Notifications
You must be signed in to change notification settings - Fork 144
feat(client, server): Message Port Adapter #528
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
c3d2f54
wip
dinwwwh f7820e6
wip
dinwwwh 96e61ee
test
dinwwwh 0a3d8da
tests
dinwwwh ef210d7
docs
dinwwwh d3e4085
browser extension playground
dinwwwh c4ee6fa
playground + docs
dinwwwh 5f11cf3
electron
dinwwwh 467423a
worker thread
dinwwwh ba0bca0
disable browser type:check
dinwwwh 198ccfe
improve worker threads example
dinwwwh f595dd0
improve
dinwwwh d291b7b
fix playground
dinwwwh af63fe1
update
dinwwwh File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| --- | ||
| title: Message Port | ||
| description: Using oRPC with Message Ports | ||
| --- | ||
|
|
||
| # Message Port | ||
|
|
||
| oRPC offers built-in support for common Message Port implementations, enabling easy internal communication between different processes. | ||
|
|
||
| | Environment | Documentation | | ||
| | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | ||
| | [Electron Message Port](https://www.electronjs.org/docs/latest/tutorial/message-ports) | [Integration Guide](/docs/integrations/electron) | | ||
| | [Browser Extension Long-lived Connections](https://developer.chrome.com/docs/extensions/develop/concepts/messaging#connect) | [Integration Guide](/docs/integrations/browser-extension) | | ||
| | [Node.js Worker Threads Port](https://nodejs.org/api/worker_threads.html#workerparentport) | [Integration Guide](/docs/integrations/worker-threads) | | ||
|
|
||
| ## Basic Usage | ||
|
|
||
| Message Ports work by establishing two endpoints that can communicate with each other: | ||
|
|
||
| ```ts [bridge] | ||
| const channel = new MessageChannel() | ||
| const serverPort = channel.port1 | ||
| const clientPort = channel.port2 | ||
| ``` | ||
|
|
||
| ```ts [server] | ||
| import { experimental_RPCHandler as RPCHandler } from '@orpc/server/message-port' | ||
|
|
||
| const handler = new RPCHandler(router) | ||
|
|
||
| handler.upgrade(serverPort, { | ||
| context: {}, // Optionally provide an initial context | ||
| }) | ||
| ``` | ||
|
|
||
| ```ts [client] | ||
| import { experimental_RPCLink as RPCLink } from '@orpc/client/message-port' | ||
|
|
||
| const link = new RPCLink({ | ||
| port: clientPort, | ||
| }) | ||
| ``` | ||
|
|
||
| :::info | ||
| This only shows how to configure the link. For full client examples, see [Client-Side Clients](/docs/client/client-side). | ||
| ::: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| title: Browser Extension Integration | ||
| description: Integrate oRPC with Browser Extensions | ||
| --- | ||
|
|
||
| # Browser Extension Integration | ||
|
|
||
| Easily set up type-safe communication between scripts in your browser extension using [Message Port Adapter](/docs/adapters/message-port). Before you begin, it’s recommended to read the [Message Passing Docs](https://developer.chrome.com/docs/extensions/develop/concepts/messaging#connect) | ||
|
|
||
| ::: warning | ||
| The browser [Message Passing API](https://developer.chrome.com/docs/extensions/develop/concepts/messaging) does not support transferring binary data, which means oRPC features like `File` and `Blob` cannot be used natively. However, you can temporarily work around this limitation by extending the [RPC JSON Serializer](/docs/advanced/rpc-json-serializer#extending-native-data-types) to encode `File` and `Blob` as Base64. | ||
| ::: | ||
|
|
||
| ## Server | ||
|
|
||
| To listen for connections on a port and upgrade the handler: | ||
|
|
||
| ```ts | ||
| import { experimental_RPCHandler as RPCHandler } from '@orpc/server/message-port' | ||
| import { router } from './router' | ||
|
|
||
| const handler = new RPCHandler(router) | ||
|
|
||
| browser.runtime.onConnect.addListener((port) => { | ||
| handler.upgrade(port, { | ||
| context: {}, // provide initial context if needed | ||
| }) | ||
| }) | ||
| ``` | ||
|
|
||
| :::info | ||
| Both `browser` and `chrome` namespaces work similarly in this case. You can use whichever one you prefer. | ||
| ::: | ||
|
|
||
| ## Client | ||
|
|
||
| To connect to the port and create an oRPC link on the client side: | ||
|
|
||
| ```ts | ||
| import { experimental_RPCLink as RPCLink } from '@orpc/client/message-port' | ||
|
|
||
| const port = browser.runtime.connect() | ||
|
|
||
| const link = new RPCLink({ | ||
| port, | ||
| }) | ||
| ``` | ||
|
|
||
| :::info | ||
| This only shows how to configure the link. For full client examples, see [Client-Side Clients](/docs/client/client-side). | ||
| ::: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| --- | ||
| title: Electron Integration | ||
| description: Integrate oRPC with Electron | ||
| --- | ||
|
|
||
| # Electron Integration | ||
|
|
||
| Establish type-safe communication between processes in [Electron](https://www.electronjs.org/) using the [Message Port Adapter](/docs/adapters/message-port). Before you start, we recommend reading the [MessagePorts in Electron](https://www.electronjs.org/docs/latest/tutorial/message-ports) guide. | ||
|
|
||
| ## Main Process | ||
|
|
||
| Listen for a port sent from the renderer, then upgrade it: | ||
|
|
||
| ```ts | ||
| import { experimental_RPCHandler as RPCHandler } from '@orpc/server/message-port' | ||
| import { router } from './router' | ||
|
|
||
| const handler = new RPCHandler(router) | ||
|
|
||
| app.whenReady().then(() => { | ||
| ipcMain.on('start-orpc-server', async (event) => { | ||
| const [serverPort] = event.ports | ||
| handler.upgrade(serverPort) | ||
| serverPort.start() | ||
| }) | ||
| }) | ||
| ``` | ||
|
|
||
| :::info | ||
| Channel `start-orpc-server` is arbitrary. you can use any name that fits your needs. | ||
| ::: | ||
|
|
||
| ## Preload Process | ||
|
|
||
| Receive the port from the renderer and forward it to the main process: | ||
|
|
||
| ```ts | ||
| window.addEventListener('message', (event) => { | ||
| if (event.data === 'start-orpc-client') { | ||
| const [serverPort] = event.ports | ||
|
|
||
| ipcRenderer.postMessage('start-orpc-server', null, [serverPort]) | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| ## Renderer Process | ||
|
|
||
| Create a `MessageChannel`, send one port to the preload script, and use the other to initialize the client link: | ||
|
|
||
| ```ts | ||
| const { port1: clientPort, port2: serverPort } = new MessageChannel() | ||
|
|
||
| window.postMessage('start-orpc-client', '*', [serverPort]) | ||
|
|
||
| const link = new RPCLink({ | ||
| port: clientPort, | ||
| }) | ||
|
|
||
| clientPort.start() | ||
| ``` | ||
|
|
||
| :::info | ||
| This only shows how to configure the link. For full client examples, see [Client-Side Clients](/docs/client/client-side). | ||
| ::: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: Worker Threads Integration | ||
| description: Enable type-safe communication between Node.js Worker Threads using oRPC. | ||
| --- | ||
|
|
||
| # Worker Threads Integration | ||
|
|
||
| Use [Node.js Worker Threads](https://nodejs.org/api/worker_threads.html) with oRPC for type-safe inter-thread communication via the [Message Port Adapter](/docs/adapters/message-port). Before proceeding, we recommend reviewing the [Node.js Worker Thread API](https://nodejs.org/api/worker_threads.html). | ||
|
|
||
| ## Worker Thread | ||
|
|
||
| Listen for a `MessagePort` sent from the main thread and upgrade it: | ||
|
|
||
| ```ts | ||
| import { parentPort } from 'node:worker_threads' | ||
| import { experimental_RPCHandler as RPCHandler } from '@orpc/server/message-port' | ||
|
|
||
| const handler = new RPCHandler(router) | ||
|
|
||
| parentPort.on('message', (message) => { | ||
| if (message instanceof MessagePort) { | ||
| handler.upgrade(message) | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| ## Main Thread | ||
|
|
||
| Create a `MessageChannel`, send one port to the thread worker, and use the other to initialize the client link: | ||
|
|
||
| ```ts | ||
| import { MessageChannel, Worker } from 'node:worker_threads' | ||
| import { experimental_RPCLink as RPCLink } from '@orpc/client/message-port' | ||
|
|
||
| const { port1: clientPort, port2: serverPort } = new MessageChannel() | ||
|
|
||
| const worker = new Worker('some-worker.js') | ||
|
|
||
| worker.postMessage(serverPort, [serverPort]) | ||
|
|
||
| const link = new RPCLink({ | ||
| port: clientPort | ||
| }) | ||
| ``` | ||
|
|
||
| :::info | ||
| This only shows how to configure the link. For full client examples, see [Client-Side Clients](/docs/client/client-side). | ||
| ::: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| export * from './link-client' | ||
| export * from './message-port' | ||
| export * from './rpc-link' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| import type { StandardLazyResponse, StandardRequest } from '@orpc/standard-server' | ||
| import type { ClientContext, ClientOptions } from '../../types' | ||
| import type { StandardLinkClient } from '../standard' | ||
| import type { SupportedMessagePort } from './message-port' | ||
| import { ClientPeer } from '@orpc/standard-server-peer' | ||
| import { onMessagePortClose, onMessagePortMessage, postMessagePortMessage } from './message-port' | ||
|
|
||
| export interface experimental_LinkMessagePortClientOptions { | ||
| port: SupportedMessagePort | ||
| } | ||
|
|
||
| export class experimental_LinkMessagePortClient<T extends ClientContext> implements StandardLinkClient<T> { | ||
| private readonly peer: ClientPeer | ||
|
|
||
| constructor(options: experimental_LinkMessagePortClientOptions) { | ||
| this.peer = new ClientPeer(async (message) => { | ||
| postMessagePortMessage(options.port, message instanceof Blob ? await message.arrayBuffer() : message) | ||
| }) | ||
|
|
||
| onMessagePortMessage(options.port, async (message) => { | ||
| await this.peer.message(message) | ||
| }) | ||
|
|
||
| onMessagePortClose(options.port, () => { | ||
| this.peer.close() | ||
| }) | ||
| } | ||
|
|
||
| async call(request: StandardRequest, _options: ClientOptions<T>, _path: readonly string[], _input: unknown): Promise<StandardLazyResponse> { | ||
| const response = await this.peer.request(request) | ||
| return { ...response, body: () => Promise.resolve(response.body) } | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.