連絡
R·E·N·R·A·K·U

"an api should just be a bunch of async functions, damn it!"
— Chase Moskal, many years ago

renraku is a magic typescript json-rpc library that makes life joyous again.

📦 npm install @e280/renraku
💡 async functions as api
🔌 http, websockets, postmessage, anything
↔️ fully stoked for bidirectionality
🌐 node + browser
🏛️ json-rpc 2.0
🤖 for web workers, see comrade
💻 an https://e280.org/ project

⛩️ RENRAKU http api

🍏 your api is just async functions — rpc.ts

import Renraku from "@e280/renraku"

export type MyFns = Awaited<ReturnType<typeof myRpc>>

export const myRpc = Renraku.asRpc(async meta => ({
  async now() {
    return Date.now()
  },

  async add(a: number, b: number) {
    return a + b
  },

  nesty: {
    is: {
      besty: {
        async mul(a: number, b: number) {
          return a * b
        },
      },
    },
  },
}))

meta.request is the http node request object (with headers and stuff)
meta.ip is the ip address associated with the request
for input validation, you should use zod or something

🍏 make an http server — server.ts
```
import Renraku from "@e280/renraku"
import {myRpc} from "./rpc.js"

await new Renraku.Server({rpc: myRpc})
  .listen(8000)
```
- your functions are served on a POST / json-rpc 2.0 endpoint
- you get a free GET /health route that returns the current js timestamp

🍏 make a clientside remote — client.ts

import Renraku from "@e280/renraku"
import type {MyFns} from "./rpc.js"

const remote = Renraku.httpRemote<MyFns>({url: "http://localhost:8000/"})

🪄 now you can magically call the functions on the clientside

await remote.now()
  // 1753780093703

await remote.add(2, 2)
  // 4

await remote.nesty.is.besty.mul(2, 3)
  // 6

👹 roll your own: node http integration

if you're feeling spartan, you can produce an ordinary node http RequestListener for your rpc functions:
import Renraku from "@e280/renraku"
import * as http from "node:http"
import {myRpc} from "./rpc.js"

const requestListener = Renraku.makeRequestListener({rpc: myRpc})

new http.Server(requestListener)
  .listen(8000)

⛩️ RENRAKU websockets api

renraku websocket apis are bidirectional, meaning the serverside and clientside can call each other.. just be careful not to create a circular loop, lol..

and yes — a single renraku server can support an http rpc endpoint and a websocket api simultaneously.

🍏 make your serverside — serverside.ts

import Renraku from "@e280/renraku"
import type {Clientside} from "./clientside.js"

export type Serverside = {
  now(): Promise<number>
}

export const serverside = (
  Renraku.asAccepter<Serverside, Clientside>(async connection => {
    console.log("connected", connection.ip)
    return {
      fns: {
        async now() {
          // 🫨 omg we're calling the clientside from the serverside!
          await connection.remote.sum(1, 2)
          return Date.now()
        },
      },
      disconnected() {
        console.log("disconnected", connection.ip)
      },
    }
  })
)

🍏 make your clientside — clientside.ts

import Renraku from "@e280/renraku"
import type {Serverside} from "./serverside.js"

export type Clientside = {
  sum(a: number, b: number): Promise<number>
}

export const clientside = (
  Renraku.asConnector<Clientside, Serverside>(async connection => {
    console.log("connected")
    return {
      fns: {
        async sum(a: number, b: number) {
          return a + b
        },
      },
      disconnected() {
        console.log("disconnected")
      },
    }
  })
)

🍏 run the websocket server — server.ts

import Renraku from "@e280/renraku"
import {serverside} from "./serverside.js"

await new Renraku.Server({websocket: serverside})
  .listen(8000)

🍏 connect as a client — client.ts

import Renraku from "@e280/renraku"
import {clientside} from "./clientside.js"

const connection = await Renraku.wsConnect({
  connector: clientside,
  socket: new WebSocket("ws://localhost:8000/"),
})

// call the serverside functionality
const result = await connection.remote.now()
  // 1753738662615

// get the average ping time in milliseconds
connection.rtt.average
  // 99

// kill the connection
connection.close()

🍏 the connection object has a bunch of good stuff

all connection objects have this stuff:

connection.socket // raw websocket instance

connection.rtt.latest // latest known ping time in milliseconds
connection.rtt.average // average of a handful of latest ping results
connection.rtt.on(rtt => {}) // subscribe to individual ping results

// remote for calling fns on the other side
await connection.remote.sum(1, 2)

// kill this connection
connection.close()

serverside connections also have HttpMeta stuff:

connection.ip // ip address of the client
connection.request // http request with headers and such

👹 roll your own: websocket upgrader integration

WsIntegration provides an upgrader that you can plug into a stock node http server:

import Renraku from "@e280/renraku"
import * as http from "node:http"
import {serverside} from "./serverside.js"

const server = new http.Server()
const websockets = new Renraku.WsIntegration({accepter: serverside})
server.on("upgrade", websockets.upgrader)

⛩️ RENRAKU gnarly details

🍏 all `Renraku.Server` options

new Renraku.Server({

  // expose http json-rpc api
  rpc: async meta => ({
    async hello() { return "lol" },
  }),

  // expose websocket json-rpc api
  websocket: Renraku.asAccepter<Serverside, Clientside>(
    async connection => ({
      fns: {async hello() { return "lmao" }},
      disconnected() {},
    })
  ),

  // supply a logger to get verbose console output (only logs errors by default)
  tap: new Renraku.LoggerTap(),

  // allow cross-origin requests (cors is disabled by default)
  cors: {origins: "*"},
  
  // request timeout in milliseconds (defaults to 60_000)
  timeout: 60_000,

  // requests with bodies bigger than this number are rejected (10 MB default)
  maxRequestBytes: 10_000_000,

  // specify the url of the rpc endpoint (defaults to `/`)
  rpcRoute: "/",

  // specify the url of the health endpoint (defaults to `/health`)
  healthRoute: "/health",

  // provide a transmuter that modifies incoming requests before routing
  transmuters: [],

  // you can provide custom listeners for additional http routes..
  routes: [
    Renraku.route.get("/hello", Renraku.respond.text("hello world")),
  ],
})

🍏 logging and error handling

renraku has this concept of a Tap, which allows you to hook into renraku for logging purposes
almost every renraku facility, can accept a tap — like makeRemote, makeEndpoint, etc
- ErrorTap (default) — logs errors, but not every request
- LoggerTap — (default for Server) verbose logging, all errors and every request
- DudTap — silent, doesn't log anything

🍏 error handling

for security-by-default, when renraku encounters an error, it reports unexposed error to the client

const timingApi = {
  async now() {
    throw new Error("not enough minerals")
      //                   ☝️
      // secret message is hidden from remote clients
  },
}

but you can throw an ExposedError when you want the error message sent to the client

import {ExposedError} from "@e280/renraku"

const timingApi = {
  async now() {
    throw new ExposedError("insufficient vespene gas")
      //                        ☝️
      //             publicly visible message
  },
}

any other kind of error will NOT send the message to the client
the intention here is security-by-default, because error messages could potentially include sensitive information

🍏 `secure` and `authorize` auth helpers

use the secure function to section off parts of your api that require auth

// auth param can be any type you want
const secured = Renraku.secure(async(auth: string) => {

  // here you can do any auth work you need
  if (auth !== "hello")
    throw new Error("auth error: did not receive warm greeting")

  return {
    async sum(a: number, b: number) {
      return a + b
    },
  }
})

// 'secure' augments the functions to require the 'auth' param first
await secured.sum("hello", 1, 2)

use the authorize function on the clientside to provide the auth param upfront
```
const authorized = Renraku.authorize(secured, async() => "hello")

// now the auth is magically provided for each call
await authorized.sum(1, 2)
```
- but why an async getter function?
  because it's a perfect opportunity for you to refresh tokens or what-have-you.
  the getter is called for each api call.
secure and authorize do not support arbitrary nesting, so you have to pass them a flat object of async functions

🍏 optimize fn calls

`tune` symbol

all the functions on a renraku Remote can be 'tuned'
import the symbol
```
import {tune} from "@e280/renraku"
```
imagine we have some renraku remote
```
await remote.sum(1, 2)
  // 3
```
tune a call with notify
```
await remote.sum[tune]({notify: true})(1, 2)
  // undefined
```
- this is how we do a json-rpc protocol 'notification' request, which skips the response (for fire-and-forget actions)
- sometimes responses are not needed, so this can be a nice little optimization
tune a call with transfer
```
const buffer = new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]).buffer

await remote.deliver[tune]({transfer: [buffer]})(buffer)
```
- this is how we specify transferables for fast zero-copy transfers between worker threads and such
- important in sister project comrade for threading workloads

`settings` symbol

it's a set-and-forget way to pre-configure the default behavior for a remote fn
import the symbol
```
import {settings} from "@e280/renraku"
```
settings to configure notify permanently on a fn
```
await remote.sum[settings].notify = true
```
now future calls will use notify: true (unless tune overrides)
```
await remote.sum(1, 2)
  // undefined
```

⛩️ RENRAKU messenger and conduits

Messenger is a bidirectional-capable api mediator, though it can also be used in a one-way capacity.

Conduit subclasses facilitate communications over various mediums:

BroadcastConduit — for broadcast channel
PostableConduit — for post message channels like web workers
WindowConduit — for window post message channels
WebsocketConduit — used under the hood for websockets (but you should use wsConnect helper instead)

the following examples will demonstrate using Messengers with WindowConduits for a common popup api example.

🍏 incredible high-effort diagram

+----ALPHA----+      +----BRAVO----+
|             |      |             |
|  [Conduit]<==========>[Conduit]  |
|      |      |      |      |      |
| [Messenger] |      | [Messenger] |
|             |      |             |
+-------------+      +-------------+

"alpha and bravo" could be a "clientside and serverside" or "window and popup" or whatever
the point is, each side gets its own conduit and its own messenger
the conduits are literally talking to each other
the messenger's job is to deal with json-rpc and provide you with a callable remote and execute your local rpc endpoint

🍏 example — calling fns on a popup — one-way messenger

api.ts — make a popup api

import Renraku from "@e280/renraku"

export const appOrigin = "https://example.e280.org"
export type PopupFns = Awaited<ReturnType<typeof popupRpc>>

export const popupRpc = Renraku.asMessengerRpc(async meta => ({
  async sum(a: number, b: number) {
    return a + b
  },
}))

popup.ts — in the popup, we create a messenger to expose our fns

import Renraku from "@e280/renraku"
import {popupRpc, appOrigin} from "./api.js"

const messenger = new Renraku.Messenger({
  rpc: popupRpc,
  conduit: new Renraku.conduits.WindowConduit({
    localWindow: window,
    targetWindow: window.opener,
    targetOrigin: appOrigin,
    allow: e => e.origin === appOrigin,
  }),
})

parent.ts — in the parent window, we create a messenger to call our fns

import Renraku from "@e280/renraku"
import {PopupFns, appOrigin} from "./api.js"

const popup = window.open(`${appOrigin}/popup`)

const messenger = new Renraku.Messenger<PopupFns>({
  conduit: new Renraku.conduits.WindowConduit({
    localWindow: window,
    targetWindow: popup,
    targetOrigin: appOrigin,
    allow: e => e.origin === appOrigin,
  }),
})

now we can call the popup's fns:

await messenger.remote.sum(2, 3)
  // 5

🍏 example — bidirectional parent and popup calls — two-way messenger

api.ts — make both apis

import Renraku from "@e280/renraku"

export const appOrigin = "https://example.e280.org"
export type PopupFns = {sum(a: number, b: number): Promise<number>}
export type ParentFns = {mul(a: number, b: number): Promise<number>}

export const popupRpc = Renraku.asMessengerRpc<PopupFns, ParentFns>(async meta => ({
  async sum(a, b) {
    await meta.remote.mul(2, 3) // 🧐 yes, we can call the other side
    return a + b
  },
}))

export const parentRpc = Renraku.asMessengerRpc<ParentFns, PopupFns>(async meta => ({
  async mul(a, b) {
    return a * b
  },
}))

popup.ts — popup window side

import Renraku from "@e280/renraku"
import {appOrigin, popupRpc} from "./api.js"

const messenger = new Renraku.Messenger({
  rpc: popupRpc,
  conduit: new Renraku.conduits.WindowConduit({
    localWindow: window,
    targetWindow: window.opener,
    targetOrigin: appOrigin,
    allow: e => e.origin === appOrigin,
  }),
})

now the popup can call parent fns

await messenger.remote.mul(2, 3)
  // 6

parent.ts — parent window side

import Renraku from "@e280/renraku"
import {appOrigin, parentRpc} from "./api.js"

const popup = window.open(`${appOrigin}/popup`)

const messenger = new Renraku.Messenger({
  rpc: parentRpc,
  conduit: new Renraku.conduits.WindowConduit({
    localWindow: window,
    targetWindow: popup,
    targetOrigin: appOrigin,
    allow: e => e.origin === appOrigin,
  }),
})

now the parent can call popup fns

await messenger.remote.sum(2, 3)
  // 5

🍏 messenger zero-copy transferables

Messenger is often used across postMessage boundaries, to talk to popups, iframes, or web workers.

as such, you can set meta.transfer array, so you can return transferables:

export const popupRpc = Renraku.asMessengerRpc(async meta => ({
  async getData() {
    const bytes = new Uint8Array([0xB0, 0x0B, 0x1E, 0x5]).buffer
    meta.transfer = [bytes]
    return bytes // ⚡ transferred speedy-fastly
  },
}))

⛩️ RENRAKU core primitives

TODO lol we should write more in depth docs about the core tools here
makeEndpoint(~) — make a json-rpc endpoint fn for a group of async fns
makeRemote(~) — make a nested proxy tree of invokable fns, given an endpoint
makeMock(~) — sugar for making an endpoint and then a remote for the given fns
JsonRpc — namespace of json rpc types and helpers
fns(~) — typescript identity helper for a group of async fns
types.ts — typescript identity helper for a group of async fns
- AsFns<X> — ensures X is a group of valid async functions
- Remote<MyFns> — adds the magic tune stuff to the provided MyFns types

⛩️ RENRAKU means contact

💖 free and open source just for you
🌟 reward us with github stars
💻 join us at e280 if you're a real one

Name		Name	Last commit message	Last commit date
Latest commit History 693 Commits
.github/workflows		.github/workflows
.vscode		.vscode
s		s
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

連絡
R·E·N·R·A·K·U

⛩️ RENRAKU http api

👹 roll your own: node http integration

⛩️ RENRAKU websockets api

👹 roll your own: websocket upgrader integration

⛩️ RENRAKU gnarly details

🍏 all `Renraku.Server` options

🍏 logging and error handling

🍏 error handling

🍏 `secure` and `authorize` auth helpers

🍏 optimize fn calls

`tune` symbol

`settings` symbol

⛩️ RENRAKU messenger and conduits

🍏 incredible high-effort diagram

🍏 example — calling fns on a popup — one-way messenger

🍏 example — bidirectional parent and popup calls — two-way messenger

🍏 messenger zero-copy transferables

⛩️ RENRAKU core primitives

⛩️ RENRAKU means contact

About

Uh oh!

Releases

Uh oh!

Languages

License

e280/renraku

Folders and files

Latest commit

History

Repository files navigation

連絡 R·E·N·R·A·K·U

⛩️ RENRAKU http api

👹 roll your own: node http integration

⛩️ RENRAKU websockets api

👹 roll your own: websocket upgrader integration

⛩️ RENRAKU gnarly details

🍏 all Renraku.Server options

🍏 logging and error handling

🍏 error handling

🍏 secure and authorize auth helpers

🍏 optimize fn calls

tune symbol

settings symbol

⛩️ RENRAKU messenger and conduits

🍏 incredible high-effort diagram

🍏 example — calling fns on a popup — one-way messenger

🍏 example — bidirectional parent and popup calls — two-way messenger

🍏 messenger zero-copy transferables

⛩️ RENRAKU core primitives

⛩️ RENRAKU means contact

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Languages

連絡
R·E·N·R·A·K·U

🍏 all `Renraku.Server` options

🍏 `secure` and `authorize` auth helpers

`tune` symbol

`settings` symbol