Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ProtomuxRpcRouter
✓ import ProtomuxRpcRouter from 'protomux-rpc-router'
✗ const ProtomuxRpcRouter = require('protomux-rpc-router')
Package exports ESM default export. CommonJS require will not work without a wrapper.
ProtomuxRpcRouter (type import)
✓ import type ProtomuxRpcRouter from 'protomux-rpc-router'
Use 'import type' for type-only imports in TypeScript to avoid runtime errors.
Middleware interface
✓ import type { Middleware } from 'protomux-rpc-router'
The Middleware type is exported for TypeScript users to define middleware objects.
Creates a ProtomuxRpcRouter, adds global logging middleware, registers an 'add' method with per-method validation, and attaches to a connection.
import ProtomuxRpcRouter from 'protomux-rpc-router'
import c from 'compact-encoding'
// Create router with optional capability
const router = new ProtomuxRpcRouter({ capability: process.env.CAPABILITY_KEY ? Buffer.from(process.env.CAPABILITY_KEY, 'hex') : undefined })
// Add global middleware (logging example)
router.use({
onrequest: async (ctx, next) => {
console.log('Request:', ctx.method)
const res = await next()
console.log('Response:', res)
return res
},
onopen: async () => { console.log('Router started') },
onclose: async () => { console.log('Router stopped') }
})
// Register a method
const add = router.method('add', {
requestEncoding: c.json,
responseEncoding: c.json
}, async (req) => {
return { result: req.a + req.b }
})
// Add per-method middleware (validation example)
add.use({
onrequest: async (ctx, next) => {
if (typeof ctx.value.a !== 'number' || typeof ctx.value.b !== 'number') {
throw new Error('Invalid input')
}
return next()
}
})
// Simulate a connection (in practice, from HyperDHT)
const fakeConnection = {
publicKey: Buffer.from('somekey'),
open: () => {},
close: () => {}
}
router.handleConnection(fakeConnection)
await router.ready()
// ... later
await router.close()
Debug
Known issues
gotchaMiddleware must be objects with `onrequest` method; using a function directly will fail.fixUse an object with `onrequest` method instead of a plain function.
affects: >=1.0.0
gotchaMethod names must be unique; registering a duplicate name will not throw but will overwrite the previous registration.fixEnsure each method name is unique when calling `router.method()`.
affects: >=1.0.0
gotchaThe `protomuxRpcId` parameter in `handleConnection` defaults to `connection.publicKey`; if that property is undefined or not a Buffer, unexpected behavior may occur.fixProvide an explicit `protomuxRpcId` Buffer or ensure `connection.publicKey` is set.
affects: >=1.0.0
gotchaMiddleware `onrequest` must return a value that propagates as the response; returning nothing will result in `undefined` response to the caller.fixAlways return the result of `await next()` or a custom value from middleware.
affects: >=1.0.0
deprecatedNo deprecated features in current version.
Errors
Common errors & fixes
ProtomuxRpcRouter is not a constructor
Using CommonJS require on an ESM-only package.
fixUse `import ProtomuxRpcRouter from 'protomux-rpc-router'` in an ESM context.
Cannot find module 'protomux-rpc-router'
Package not installed or typo in package name.
fixRun `npm install protomux-rpc-router` and check for spelling errors.
TypeError: middleware.onrequest is not a function
Middleware object does not have an `onrequest` method.
fixEnsure middleware is an object with an async `onrequest(ctx, next)` function.
ctx.value is undefined
No request encoding provided when registering method, or the received request data is not decoded.
fixSpecify `requestEncoding` in method options (e.g., `c.json` from compact-encoding).
Audit
Dependencies
protomux-rpcrequiredUnderlying RPC implementation; the router wraps protomux-rpc's respond() method.
compact-encodingrequiredUsed for encoding/decoding request and response values in method registration.
protomuxoptionalTransport layer for multiplexing connections; used indirectly via protomux-rpc.
hyperswarm-capabilityoptionalOptional capability verification for method access control.