@bigmistqke/rpc 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bigmistqke/rpc",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "RPC toolkit for type-safe communication across Workers, iframes, and network boundaries.",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./messenger": {
+      "import": "./dist/messenger.js",
+      "types": "./dist/messenger.d.ts"
+    },
+    "./stream": {
+      "import": "./dist/stream/index.js",
+      "types": "./dist/stream/index.d.ts"
+    },
+    "./fetch": {
+      "import": "./dist/fetch/index.js",
+      "types": "./dist/fetch/index.d.ts"
+    },
+    "./fetch/node": {
+      "import": "./dist/fetch/node.js",
+      "types": "./dist/fetch/node.d.ts"
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "6.6.3",
+    "typescript": "^5.7.2",
+    "vitest": "0.28.5"
+  },
+  "dependencies": {
+    "@types/node": "^22.15.30",
+    "bumpp": "^10.3.2",
+    "valibot": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "bump": "bumpp"
+  }
+}

package/src/fetch/index.ts

@@ -0,0 +1,84 @@
+import * as v from 'valibot'
+import { RPC } from '../types'
+import { callMethod, createCommander, createShape } from '../utils'
+
+const $FETCH_HEADER = 'RPC_RR_PROXY'
+
+export const isFetchRequest = (event: { request: Request }) =>
+  event.request.headers.has($FETCH_HEADER)
+
+export const Payload = createShape(
+  v.object({ args: v.array(v.any()), topics: v.array(v.string()) }),
+  (topics: Array<string>, args: Array<any>) => ({ topics, args }),
+)
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                  Expose / Rpc                                  */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Exposes a set of methods as an RPC endpoint over the given messenger.
+ *
+ * @param methods - An object containing functions to expose
+ * @param options - Optional target Messenger and abort signal
+ */
+export function expose<T extends object>(methods: T) {
+  return async (event: { request: Request }) => {
+    try {
+      const json = await event.request.json()
+
+      if (!Payload.validate(json)) {
+        throw new Error(`Incorrect shape`)
+      }
+      const { args, topics } = json
+
+      const payload = await callMethod(methods, topics, args)
+      return new Response(JSON.stringify({ payload }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    } catch (error) {
+      return new Response(null, {
+        statusText:
+          typeof error === 'string'
+            ? error
+            : typeof error === 'object' &&
+              error &&
+              'message' in error &&
+              typeof error.message === 'string'
+            ? error.message
+            : undefined,
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+  }
+}
+
+/**
+ * Creates an RPC proxy for calling remote methods on the given Messenger.
+ *
+ * @param messenger - The Messenger to communicate with (e.g. Worker or Window)
+ * @param options - Optional abort signal
+ * @returns A proxy object that lets you call methods remotely
+ */
+export function rpc<T extends object>(base: string): RPC<T> {
+  return createCommander<RPC<T>>(async (topics, args) => {
+    const result = await fetch(
+      new Request(`${base}/${topics.join('/')}`, {
+        method: topics.length > 0 ? 'POST' : 'GET',
+        headers: { [$FETCH_HEADER]: 'true' },
+        body: JSON.stringify(Payload.create(topics, args)),
+      }),
+    )
+
+    if (result.status !== 200) {
+      throw result.statusText
+    }
+
+    const { payload } = await result.json()
+    return payload
+  })
+}

package/src/fetch/node.ts

@@ -0,0 +1,44 @@
+/// <reference types="node" />
+
+import { IncomingMessage, ServerResponse } from 'http'
+import { Payload } from '.'
+import { callMethod } from '../utils'
+
+export function exposeNode<T extends object>(
+  methods: T,
+  {
+    wrap = (res: ServerResponse, result: any) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify(result))
+    },
+    unwrap = async (req: IncomingMessage): Promise<{ topics: string[]; args: any[] }> => {
+      const body = await new Promise<string>((resolve, reject) => {
+        let data = ''
+        req.on('data', chunk => (data += chunk))
+        req.on('end', () => resolve(data))
+        req.on('error', reject)
+      })
+
+      const json = JSON.parse(body)
+      if (!Payload.validate(json)) {
+        throw new Error(`Incorrect shape`)
+      }
+
+      return json
+    },
+  }: {
+    wrap?: (res: ServerResponse, result: any) => void
+    unwrap?: (req: IncomingMessage) => Promise<{ topics: string[]; args: any[] }>
+  } = {},
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    try {
+      const { topics, args } = await unwrap(req)
+      const result = await callMethod(methods, topics, args)
+      wrap(res, result)
+    } catch (err: any) {
+      res.writeHead(500)
+      res.statusMessage = err?.message
+    }
+  }
+}

package/src/message-protocol.ts

@@ -0,0 +1,57 @@
+import * as v from 'valibot'
+import { createShape } from './utils'
+
+// Schema and protocol for requests
+export const $MESSENGER_REQUEST = 'RPC_PROXY_REQUEST'
+
+export const requestSchema = v.object({
+  [$MESSENGER_REQUEST]: v.number(),
+  payload: v.unknown(),
+})
+
+export const RequestShape = createShape(requestSchema, <T>(id: number, payload: T) => ({
+  [$MESSENGER_REQUEST]: id,
+  payload,
+}))
+
+export type RequestData = v.InferOutput<typeof requestSchema>
+
+// Schema and protocol for responses
+export const $MESSENGER_RESPONSE = 'RPC_PROXY_RESPONSE'
+
+export const ResponseShape = createShape(
+  v.object({
+    [$MESSENGER_RESPONSE]: v.number(),
+    payload: v.unknown(),
+  }),
+  (request: RequestData, payload: any) => ({
+    [$MESSENGER_RESPONSE]: request[$MESSENGER_REQUEST],
+    payload,
+  }),
+)
+
+// Schema and protocol of errors
+export const $MESSENGER_ERROR = 'RPC_PROXY_ERROR'
+
+export const ErrorShape = createShape(
+  v.object({
+    [$MESSENGER_ERROR]: v.number(),
+    error: v.unknown(),
+  }),
+  (data: RequestData, error: any) => ({
+    [$MESSENGER_ERROR]: data[$MESSENGER_REQUEST],
+    error,
+  }),
+)
+
+// RPC-specific request payload
+export const $MESSENGER_RPC_REQUEST = 'RPC_PROXY_RPC_REQUEST'
+
+export const RPCPayloadShape = createShape(
+  v.object({
+    [$MESSENGER_RPC_REQUEST]: v.boolean(),
+    topics: v.array(v.string()),
+    args: v.array(v.any()),
+  }),
+  (topics: Array<string>, args: Array<any>) => ({ [$MESSENGER_RPC_REQUEST]: true, topics, args }),
+)

package/src/messenger.ts

@@ -0,0 +1,176 @@
+import {
+  $MESSENGER_ERROR,
+  $MESSENGER_RESPONSE,
+  ErrorShape,
+  RequestData,
+  RequestShape,
+  ResponseShape,
+  RPCPayloadShape,
+} from './message-protocol'
+import { RPC } from './types'
+import { callMethod, createCommander, createIdRegistry, defer } from './utils'
+
+export const $TRANSFER = 'WORKER-TRANSFER'
+
+interface WorkerMessenger {
+  postMessage(message: any, transferables?: any[]): void
+  addEventListener(key: 'message', callback: (event: MessageEvent) => void): void
+  start?(): void
+}
+
+type Messenger = Window | WorkerMessenger
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                      Utils                                     */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Checks whether the given target is a `Window` object (WindowProxy).
+ */
+function isWindowProxy(target: any): target is Window {
+  return (
+    typeof target === 'object' &&
+    typeof target?.postMessage === 'function' &&
+    typeof target?.closed === 'boolean'
+  )
+}
+
+/**
+ * Returns a `postMessage` function compatible with both Window and Worker contexts.
+ */
+function usePostMessage(messenger: Messenger) {
+  if (isWindowProxy(messenger)) {
+    return (message: any, transferables?: any[]) =>
+      messenger.postMessage(message, '*', transferables)
+  } else {
+    return (message: any, transferables?: any[]) => messenger.postMessage(message, transferables)
+  }
+}
+
+/**********************************************************************************/
+/*                                                                                */
+/*                              Requester / Responder                             */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Sets up a requester that sends messages and returns promises resolving when a response is received.
+ *
+ * @param messenger - The target Messenger to send messages to
+ * @param options - Optional abort signal
+ * @returns A function to send payloads and await responses
+ */
+function createRequester(messenger: Messenger, options: { signal?: AbortSignal } = {}) {
+  const promiseRegistry = createIdRegistry<{
+    resolve(value: any): void
+    reject(value: unknown): void
+  }>()
+  const postMessage = usePostMessage(messenger)
+
+  messenger.addEventListener(
+    'message',
+    event => {
+      const data = (event as MessageEvent<unknown>).data
+      if (ErrorShape.validate(data)) {
+        promiseRegistry.free(data[$MESSENGER_ERROR])?.reject(data.error)
+      } else if (ResponseShape.validate(data)) {
+        promiseRegistry.free(data[$MESSENGER_RESPONSE])?.resolve(data.payload)
+      }
+    },
+    options,
+  )
+
+  if ('start' in messenger) {
+    messenger.start?.()
+  }
+
+  return (payload: any, transferables?: any[]) => {
+    const { promise, resolve, reject } = defer()
+    const id = promiseRegistry.register({ resolve, reject })
+    postMessage(RequestShape.create(id, payload), transferables)
+    return promise
+  }
+}
+
+/**
+ * Sets up a responder that listens for requests and responds with the result of the callback.
+ *
+ * @param messenger - The Messenger to receive messages from
+ * @param callback - A function called with the validated request event
+ * @param options - Optional abort signal
+ */
+export function createResponder(
+  messenger: Messenger,
+  callback: (data: RequestData) => any,
+  options: { signal?: AbortSignal } = {},
+) {
+  const postMessage = usePostMessage(messenger)
+
+  messenger.addEventListener(
+    'message',
+    event => {
+      const data = (event as MessageEvent).data
+      if (RequestShape.validate(data)) {
+        try {
+          postMessage(ResponseShape.create(data, callback(data)))
+        } catch (error) {
+          postMessage(ErrorShape.create(data, error))
+        }
+      }
+    },
+    options,
+  )
+
+  if ('start' in messenger) {
+    messenger.start?.()
+  }
+}
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                  Expose / Rpc                                  */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Exposes a set of methods as an RPC endpoint over the given messenger.
+ *
+ * @param methods - An object containing functions to expose
+ * @param options - Optional target Messenger and abort signal
+ */
+export function expose<T extends object>(
+  methods: T,
+  { to = self, signal }: { to?: Messenger; signal?: AbortSignal } = {},
+) {
+  createResponder(
+    to,
+    data => {
+      if (RPCPayloadShape.validate(data.payload)) {
+        try {
+          const { topics, args } = data.payload
+          return callMethod(methods, topics, args)
+        } catch (error) {
+          console.error('Error while processing rpc request:', error, data.payload, methods)
+        }
+      }
+    },
+    { signal },
+  )
+}
+
+/**
+ * Creates an RPC proxy for calling remote methods on the given Messenger.
+ *
+ * @param messenger - The Messenger to communicate with (e.g. Worker or Window)
+ * @param options - Optional abort signal
+ * @returns A proxy object that lets you call methods remotely
+ */
+export function rpc<T extends object>(
+  messenger: Messenger,
+  options?: { signal?: AbortSignal },
+): RPC<T> {
+  const request = createRequester(messenger, options)
+  return createCommander<RPC<T>>((topics, args) => request(RPCPayloadShape.create(topics, args)))
+}

package/src/server-send-events/index.ts

@@ -0,0 +1,129 @@
+import { $MESSENGER_REQUEST, RequestShape, RPCPayloadShape } from '../message-protocol'
+import * as v from 'valibot'
+import { RPC } from '../types'
+import { callMethod, createCommander, createIdRegistry, createShape, defer } from '../utils'
+
+const $SSE_RESPONSE_HEADER = 'RPC_SSE_RESPONSE'
+
+export const isSSEResponse = (event: { request: Request }) =>
+  event.request.headers.has($SSE_RESPONSE_HEADER)
+
+export const Payload = createShape(
+  v.object({ args: v.array(v.any()), topics: v.array(v.string()) }),
+  (topics: Array<string>, args: Array<any>) => ({ topics, args }),
+)
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                  Expose / Rpc                                  */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Exposes a set of methods as an RPC endpoint over the given messenger.
+ *
+ * @param methods - An object containing functions to expose
+ * @param options - Optional target Messenger and abort signal
+ */
+export function expose<T extends object>(url: string, methods: T) {
+  const sse = new EventSource(url)
+  sse.addEventListener('message', async event => {
+    try {
+      const data = JSON.parse(event.data)
+
+      if (RequestShape.validate(data) && RPCPayloadShape.validate(data.payload)) {
+        const {
+          [$MESSENGER_REQUEST]: id,
+          payload: { args, topics },
+        } = data
+
+        fetch(url, {
+          method: 'POST',
+          headers: {
+            [$SSE_RESPONSE_HEADER]: id.toString(),
+          },
+          body: JSON.stringify({ payload: await callMethod(methods, topics, args) }),
+        })
+      }
+    } catch (error) {
+      console.error('ERROR', error, event)
+    }
+  })
+}
+
+/**
+ * Creates an RPC proxy for calling remote methods on the given Messenger.
+ *
+ * @param messenger - The Messenger to communicate with (e.g. Worker or Window)
+ * @param options - Optional abort signal
+ * @returns A proxy object that lets you call methods remotely
+ */
+export function rpc<T extends object>() {
+  const promiseRegistry = createIdRegistry<{
+    resolve(value: any): void
+    reject(value: unknown): void
+  }>()
+
+  return {
+    create() {
+      const encoder = new TextEncoder()
+      const closeHandlers = new Set<() => void>()
+      let controller: ReadableStreamDefaultController
+      let closed = false
+
+      function send(value: any) {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`))
+      }
+
+      const stream = new ReadableStream({
+        start(_controller) {
+          controller = _controller
+        },
+        cancel() {
+          closeHandlers.forEach(handler => handler())
+          closed = true
+        },
+      })
+
+      return [
+        createCommander<RPC<T>>(async (topics, args) => {
+          if (closed) {
+            throw new Error(`[rpc/sse] Stream is closed.`)
+          }
+          const { promise, resolve, reject } = defer()
+          const id = promiseRegistry.register({ resolve, reject })
+          send(RequestShape.create(id, RPCPayloadShape.create(topics, args)))
+          return promise
+        }),
+        {
+          get closed() {
+            return closed
+          },
+          onClose(callback: () => void) {
+            closeHandlers.add(callback)
+            return () => closeHandlers.delete(callback)
+          },
+          response: new Response(stream, {
+            headers: {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+              Connection: 'keep-alive',
+            },
+          }),
+        },
+      ] as const
+    },
+    handleAnswer: async (event: { request: Request }) => {
+      const id = event.request.headers.get($SSE_RESPONSE_HEADER)
+      if (id !== null) {
+        try {
+          const { payload } = await event.request.json()
+          promiseRegistry.free(+id)?.resolve(payload)
+        } catch (error) {
+          console.error('ERROR', error, event)
+        }
+      }
+      return new Response()
+    },
+  }
+}