{"id":17239,"library":"grenache-nodejs-http","title":"Grenache Node.js HTTP","description":"Grenache Node.js HTTP implementation, currently at stable version 1.0.1, is a specialized micro-framework designed for building performant microservices in Node.js environments. It stands out by utilizing Distributed Hash Tables (DHT), similar to those found in Bittorrent, to facilitate peer-to-peer connections rather than traditional centralized brokers. This package provides the HTTP transport layer for Grenache, enabling the creation of RPC servers and clients that announce and discover services over an overlay network managed by external 'Grape' DHT nodes. Its release cadence follows the broader Grenache ecosystem. Key differentiators include its decentralized service discovery, direct peer-to-peer communication, and focus on optimized performance, moving beyond conventional request-response patterns by leveraging a robust, distributed network infrastructure. It specifically abstracts away the complexities of DHT interaction for HTTP-based service communication.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/bitfinexcom/grenache-nodejs-http","tags":["javascript","grenache","kademlia","nodejs","micro-services"],"install":[{"cmd":"npm install grenache-nodejs-http","lang":"bash","label":"npm"},{"cmd":"yarn add grenache-nodejs-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add grenache-nodejs-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core Grenache Link functionality, essential for connecting to the DHT (Grape) and managing peer communication, which is utilized by the HTTP server and client.","package":"grenache-nodejs-link","optional":false}],"imports":[{"note":"This package is CommonJS-only in its current stable version (1.x). Attempting to use ESM import syntax will result in errors.","wrong":"import { PeerRPCServer } from 'grenache-nodejs-http'","symbol":"PeerRPCServer","correct":"const { PeerRPCServer } = require('grenache-nodejs-http')"},{"note":"Grenache services are typically accessed via named imports (destructuring) from the main package object. This package is CommonJS-only.","wrong":"import PeerRPCClient from 'grenache-nodejs-http'","symbol":"PeerRPCClient","correct":"const { PeerRPCClient } = require('grenache-nodejs-http')"},{"note":"While possible to import the entire module, it's more common to destructure PeerRPCServer and PeerRPCClient directly from the required object for clarity and direct access.","symbol":"GrenacheHttpModule","correct":"const GrenacheHttp = require('grenache-nodejs-http')"}],"quickstart":{"code":"/*\n  Before running this code, you need to install grenache-grape globally:\n  npm i -g grenache-grape\n\n  Then, start two Grape instances:\n  grape --dp 20001 --aph 30001 --bn '127.0.0.1:20002'\n  grape --dp 20002 --aph 40001 --bn '127.0.0.1:20001'\n*/\n\nconst Link = require('grenache-nodejs-link')\nconst { PeerRPCServer, PeerRPCClient } = require('grenache-nodejs-http')\n\n// RPC Server\nconst serverLink = new Link({\n  grape: 'http://127.0.0.1:30001'\n})\nserverLink.start()\n\nconst peerServer = new PeerRPCServer(serverLink, {\n  timeout: 300000\n})\npeerServer.init()\n\nconst service = peerServer.transport('server')\n// Use Math.floor(Math.random()) for port generation, replacing _.random\nservice.listen(Math.floor(Math.random() * 1000) + 1024)\n\nsetInterval(() => {\n  serverLink.announce('rpc_test', service.port, {})\n}, 1000)\n\nservice.on('request', (rid, key, payload, handler) => {\n  console.log(`Server received request for '${key}' with payload: '${payload}'`)\n  handler.reply(null, 'world')\n})\n\nconsole.log(`RPC Server listening on port ${service.port} and announcing 'rpc_test'`)\n\n// RPC Client\nconst clientLink = new Link({\n  grape: 'http://127.0.0.1:30001'\n})\nclientLink.start()\n\nconst peerClient = new PeerRPCClient(clientLink, {})\npeerClient.init()\n\npeerClient.request('rpc_test', 'hello', { timeout: 10000 }, (err, data) => {\n  if (err) {\n    console.error('Client error:', err)\n    process.exit(-1)\n  }\n  console.log(`Client received data: '${data}'`) // world\n  // In a real application, you might want to stop links gracefully\n  // clientLink.stop()\n  // serverLink.stop()\n  // process.exit(0)\n})\n\nconsole.log('RPC Client sending request to \\'rpc_test\\' service...')","lang":"javascript","description":"This example demonstrates how to set up two Grenache Grape DHT instances, create a Grenache RPC server that announces a service, and an RPC client that requests data from it over HTTP."},"warnings":[{"fix":"Install 'grenache-grape' globally (npm i -g grenache-grape) and start at least two instances on different ports, bootstrapping them to each other, e.g., `grape --dp 20001 --aph 30001 --bn '127.0.0.1:20002'`.","message":"Grenache requires external 'Grape' DHT instances to be running and accessible for service discovery and communication. This is a runtime dependency, not an npm installation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Choose the appropriate event listener based on whether you need streaming capabilities ('stream') or buffered payload access ('request'). If 'disableBuffered' is active, implement manual buffering logic for 'request' if needed.","message":"The PeerRPCServer's 'stream' event is emitted immediately upon request arrival, while the 'request' event buffers the entire payload before emission. If 'disableBuffered' is true, the 'request' event must be manually triggered or handled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a timer (e.g., `setInterval`) to regularly re-announce your service port and name to the Grenache network (DHT/Grape).","message":"Service announcements made via 'link.announce()' are ephemeral in the DHT. To ensure continuous service availability, announcements must be re-issued periodically, typically using a setInterval.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 16.0 or newer. Check the `engines` field in `package.json` for exact requirements.","message":"This package explicitly requires Node.js version 16.0 or higher, as indicated by the `engines` field in `package.json`. Running on older versions may lead to unexpected errors or failure to start.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the RPC server is running and has successfully announced its service to the Grape network. Check Grape connectivity from both client and server, and increase the timeout if the service is known to have long processing times.","cause":"The RPC client did not receive a response from the service within the specified timeout, often due to the service not being announced or not responding in time.","error":"Error: Timeout"},{"fix":"Verify that the Grape instance is running on the specified IP address and port, and that no firewall is blocking the connection. Double-check the 'grape' option in the Link constructor.","cause":"The Grenache Link instance was unable to connect to the specified Grape (DHT) node. This usually means Grape is not running or is inaccessible.","error":"Error: connect ECONNREFUSED 127.0.0.1:30001"},{"fix":"For CommonJS, use `const { PeerRPCServer } = require('grenache-nodejs-http')` or `const PeerRPCServer = require('grenache-nodejs-http').PeerRPCServer`. This package does not support ESM imports in its current major version.","cause":"Attempted to use `PeerRPCServer` (or `PeerRPCClient`) without correctly requiring/importing it, or using an incorrect import style for CommonJS.","error":"ReferenceError: PeerRPCServer is not defined"}],"ecosystem":"npm","meta_description":null}