{"id":20464464,"url":"https://github.com/bytedance/node-unix-socket","last_synced_at":"2025-08-21T15:33:06.291Z","repository":{"id":45789398,"uuid":"514229734","full_name":"bytedance/node-unix-socket","owner":"bytedance","description":"Unix dgram, seqpacket, etc binding for Node.js.","archived":false,"fork":false,"pushed_at":"2024-10-19T09:51:37.000Z","size":419,"stargazers_count":61,"open_issues_count":4,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-01T06:18:11.343Z","etag":null,"topics":["dgram","nodejs","reuseport","rust","seqpacket-sockets","unix-socket"],"latest_commit_sha":null,"homepage":"https://bytedance.github.io/node-unix-socket/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytedance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-15T10:33:46.000Z","updated_at":"2025-05-31T07:58:22.000Z","dependencies_parsed_at":"2023-02-13T13:01:09.953Z","dependency_job_id":"d8b56d0f-2431-4d1f-a123-d2f8746ac0e2","html_url":"https://github.com/bytedance/node-unix-socket","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bytedance/node-unix-socket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnode-unix-socket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnode-unix-socket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnode-unix-socket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnode-unix-socket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytedance","download_url":"https://codeload.github.com/bytedance/node-unix-socket/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnode-unix-socket/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271500361,"owners_count":24770375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dgram","nodejs","reuseport","rust","seqpacket-sockets","unix-socket"],"created_at":"2024-11-15T13:15:10.770Z","updated_at":"2025-08-21T15:33:05.854Z","avatar_url":"https://github.com/bytedance.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-unix-socket\n\n![npm_bandage](https://img.shields.io/npm/v/node-unix-socket) ![github_ci_status](https://github.com/bytedance/node-unix-socket/workflows/CI/badge.svg)\n\n`node-unix-socket` allows you to use some nonblocking unix sockets that are currently not supported by Node.js native modules, including:\n\n- unix seqpacket(`SOCK_SEQPACKET`) sockets\n- unix datagram(`SOCK_DGRAM`) sockets\n- Using `SO_REUSEPORT` enabled TCP [net.Server](https://nodejs.org/dist/latest-v16.x/docs/api/net.html#class-netserver)\n\n`node-unix-socket` is a [napi-rs](https://napi.rs/) based [Node.js addons](https://nodejs.org/docs/latest-v16.x/api/addons.html) and:\n- This lib bases on n-api and is pre-compiled so that it doesn't require compilation environments if yours is pre-built supported.\n- This lib won't introduce any other asynchronous runtimes as it uses [libuv](https://libuv.org/) inside Node.js.\n\nWe use `SOCK_SEQPACKET` sockets for in our internal APM.\n\n## Tested Platforms \u0026 Node.js\n\n|Platform|Node.js|DgramSocket|Seqpacket|\n|---|---|---|---|\n|x64 Linux|12 + LTS|✅|✅|\n|x64 Darwin|12 + LTS|✅||\n|aarch64 Darwin|12 + LTS|✅||\n\n## Installation\n\n```\nnpm i node-unix-socket\n```\n\n## API Documents\n\n[API Documents](https://bytedance.github.io/node-unix-socket/)\n\n## Seqpacket Sockets\n\n`SOCK_SEQPACKET` sockets are like `SOCK_STREAM` sockets while they keep message boundaries.\n\nNote that `SOCK_SEQPACKET` sockets don't work on MacOS.\n\n### Example\n\n[Online Example](https://codesandbox.io/s/node-unix-seqpacket-socket-n3hd8l?file=/index.js)\n\n```js\nconst { SeqpacketServer, SeqpacketSocket } = require('node-unix-socket');\nconst os = require('os');\nconst path = require('path');\nconst fs = require('fs');\n\nconst bindPath = path.resolve(os.tmpdir(), './my_seqpacket.sock');\n\ntry {\n  fs.unlinkSync(bindPath);\n} catch (e) {}\n\nconst server = new SeqpacketServer();\nserver.listen(bindPath);\nserver.on('connection', (socket) =\u003e {\n  socket.on('data', (buf) =\u003e {\n    console.log('received', buf.toString());\n  });\n});\n\nconst client = new SeqpacketSocket();\nclient.connect(bindPath, () =\u003e {\n  const data = ['hello, ', 'w', 'o', 'r', 'l', 'd'];\n\n  for (const str of data) {\n    client.write(Buffer.from(str));\n  }\n  client.end();\n});\n```\n\n## Dgram Sockets\n\n### Example\n\n[Online Example](https://codesandbox.io/s/node-unix-dgram-socket-76cyyu?file=/index.js)\n\n```js\nconst { DgramSocket } = require('node-unix-socket');\nconst os = require('os');\nconst path = require('path');\nconst fs = require('fs');\n\nconst path1 = path.resolve(os.tmpdir(), './my_dgram_1.sock');\nconst path2 = path.resolve(os.tmpdir(), './my_dgram_2.sock');\n\ntry {\n  fs.unlinkSync(path1);\n  fs.unlinkSync(path2);\n} catch (err) {}\n\nconst socket1 = new DgramSocket();\nconst socket2 = new DgramSocket();\n\nsocket1.bind(path1);\nsocket2.bind(path2);\n\nsocket2.on('data', (data, remoteAddr) =\u003e {\n  console.log(`socket2 received: ${data.toString()}`);\n  // echo\n  socket2.sendTo(data, 0, data.length, remoteAddr);\n});\n\nsocket1.on('data', (data) =\u003e {\n  console.log(`socket1 received: ${data.toString()}`);\n});\n\nsetInterval(() =\u003e {\n  const buf = Buffer.from('hello');\n  socket1.sendTo(buf, 0, buf.length, path2);\n}, 1000);\n```\n\n## `SO_REUSEPORT` enabled TCP net.Server\n\nThe [cluster](https://nodejs.org/dist/latest-v18.x/docs/api/cluster.html) module share server ports by accepting new connections in the primary process and distributing them to worker processes.\n\nWith `SO_REUSEPORT`, sockets will be distributed by kernel instead, and which should be more performant especially for scenario of having a lot of short-lived connections.\n\nFor example, the arrow in the image below shows cpu usage of a PM2 primary process which we found in our environment.\n\n![cpu_usage](./resource/cpu_usage.png)\n\nNote that `SO_REUSEPORT` might behave much differently across operating systems. See this [post](https://stackoverflow.com/questions/14388706/how-do-so-reuseaddr-and-so-reuseport-differ) for more information.\n\n### Example\n\n[Online Http Server Example](https://codesandbox.io/s/node-so-reuseport-net-server-no9mvm?file=/index.js)\n\n```js\nconst { createReuseportFd } = require('node-unix-socket');\nconst { Server, Socket } = require('net');\n\nconst port = 8080;\nconst host = '0.0.0.0';\n\n// create multple servers listening to a same host, port.\nfor (let i = 0; i \u003c 2; i += 1) {\n  const fd = createReuseportFd(port, host);\n  const server = new Server((socket) =\u003e {\n    socket.on('data', (buf) =\u003e {\n      console.log(`server ${i} received:`, buf);\n      // echo\n      socket.write(buf);\n    });\n  });\n\n  server.listen(\n    {\n      fd,\n    },\n    () =\u003e {\n      console.log(`server ${i} is listening on ${port}`);\n    }\n  );\n}\n\nsetInterval(() =\u003e {\n  const client = new Socket();\n  client.on('data', (buf) =\u003e {\n    console.log('client received:', buf);\n    client.destroy();\n  });\n  client.connect(port, host, () =\u003e {\n    client.write(Buffer.from('hello'));\n  });\n}, 1000);\n```\n\n## CONTRIBUTING\n\n[CONTRIBUTING.md](./CONTRIBUTING.md)\n\n## Development\n\n1. Setup rust and Node.js.\n2. Modify the code.\n2. `npm run build \u0026\u0026 npm run test`\n\n## LICENSE\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2Fnode-unix-socket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytedance%2Fnode-unix-socket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2Fnode-unix-socket/lists"}