lonesome-js

High-performance programmable reverse proxy bindings for Node.js, built on top of Pingora.

中文文档 (README.zh.md)

• Built on Pingora for modern async proxy performance and reliability.
• Runtime route updates (addOrUpdate) with Node.js without process restarts.
• Request matching and middleware conditions powered by CEL expressions.
• virtual_js upstream mode for in-process Node.js service composition.
• Route middlewares for auth, headers, redirects, caching, compression, CORS, rate limiting, and programmable interception.

Most reverse proxies focus on static config files and process-level reload workflows. lonesome-js is designed around a runtime API and programmable request flow.

Instead of limiting logic to fixed directives, routes and middleware conditions can use CEL expressions for matching and value generation.

Examples:

• Route match: "Method('POST') && PathPrefix('/api') && Query('debug', '1')"
• Conditional middleware: rule: "Header('x-env', 'prod')"
• Dynamic value: expression: "MethodValue() + '-' + QueryValue('id')"

Beyond TCP/Unix socket upstreams, virtual_js allows requests to be bridged into JavaScript handlers in-process. This makes it possible to build internal adapters and programmable backends without opening extra network ports.

npm i lonesome-js

Windows on arm prebuilt binding is not available; use WSL as a temporary workaround, or build it yourself.

import { LonesomeServer } from 'lonesome-js'

const server = new LonesomeServer()

server.start({
  listeners: [{ kind: 'tcp', addr: '127.0.0.1:8080' }],
})

server.addOrUpdate({
  id: 'basic-proxy',
  matcher: { rule: "PathPrefix('/api')", priority: 50 },
  middlewares: [],
  upstreams: [
    { kind: 'tcp', address: '127.0.0.1:9000' },
  ],
  loadBalancer: { algorithm: 'round_robin' },
})

server.addOrUpdate({
  id: 'basic-proxy',
  matcher: { rule: "PathPrefix('/api')", priority: 50 },
  middlewares: [{ type: 'respond', config: { status: 418, body: 'teapot' } }],
  upstreams: [
    { kind: 'tcp', address: '127.0.0.1:9000' },
  ],
})

• Primary target: Node.js via the npm package.
• Deno can consume the package through npm:lonesome-js for local/server use cases that allow npm/native bindings. See the example app: example/lonesome-lake.

• Docs index and LonesomeServer control API: docs/readme.md
• Route lifecycle and hot updates: docs/route.md
• CEL expressions: docs/cel.md
• virtual_js upstreams: docs/virtual_js.md
• Interceptor middleware: docs/interceptor.md
• Middlewares: docs/middlewares/readme.md