{"id":13527493,"url":"https://github.com/hertzg/node-net-keepalive","last_synced_at":"2025-04-04T21:07:10.176Z","repository":{"id":34807974,"uuid":"38793888","full_name":"hertzg/node-net-keepalive","owner":"hertzg","description":"Provides high-level access to socket options like TCP_KEEPINTVL, TCP_KEEPCNT and TCP_USER_TIMEOUT for node js.","archived":false,"fork":false,"pushed_at":"2025-03-21T03:38:16.000Z","size":2619,"stargazers_count":41,"open_issues_count":2,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T20:08:43.938Z","etag":null,"topics":["ffi","ffi-bindings","hacktoberfest","javascript","keepalive","net","network","nodejs","npm","npm-package","semver","semver-release","socket","tcp","tcp-client","tcp-keepalives","tcp-socket","tcp-user-timeout"],"latest_commit_sha":null,"homepage":"https://hertzg.github.io/node-net-keepalive/","language":"JavaScript","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/hertzg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2015-07-09T03:09:27.000Z","updated_at":"2025-03-17T15:03:08.000Z","dependencies_parsed_at":"2024-01-13T03:58:55.655Z","dependency_job_id":"4377f62f-edf5-4367-b309-8f7c74c86374","html_url":"https://github.com/hertzg/node-net-keepalive","commit_stats":{"total_commits":416,"total_committers":10,"mean_commits":41.6,"dds":0.6298076923076923,"last_synced_commit":"bfdc85bc12088995905757278f867f45c45e9309"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hertzg%2Fnode-net-keepalive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hertzg%2Fnode-net-keepalive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hertzg%2Fnode-net-keepalive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hertzg%2Fnode-net-keepalive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hertzg","download_url":"https://codeload.github.com/hertzg/node-net-keepalive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"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","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":["ffi","ffi-bindings","hacktoberfest","javascript","keepalive","net","network","nodejs","npm","npm-package","semver","semver-release","socket","tcp","tcp-client","tcp-keepalives","tcp-socket","tcp-user-timeout"],"created_at":"2024-08-01T06:01:49.250Z","updated_at":"2025-04-04T21:07:10.158Z","avatar_url":"https://github.com/hertzg.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![NPM][npm_shield]][npm_url]\n[![Node][node_shield]][node_url]\n[![OS][os_shield]][npm_url]\n[![Codecov][codecov_shield]][codecov_url]\n[![CI][travis_shield]][travis_url]\n[![Dependencies][daviddm_shield]][daviddm_url]\n[![Code Quality][codacy_shield]][codacy_url]\n[![License][license_shield]][license_url]\n\n[codacy_url]: https://www.codacy.com/app/hertzg/node-net-keepalive\n[codacy_shield]: https://api.codacy.com/project/badge/Grade/d191b6408086432586e6c60577485c6f\n[npm_url]: https://www.npmjs.com/package/net-keepalive\n[npm_shield]: https://img.shields.io/npm/v/net-keepalive.svg?style=flat\n[node_url]: https://dist.nodejs.org\n[node_shield]: https://img.shields.io/badge/node-%3E%3D10.20.0-green.svg\n[os_shield]: https://img.shields.io/badge/os-linux%2Cosx%2Cbsd-green.svg\n[travis_url]: https://travis-ci.org/hertzg/node-net-keepalive\n[travis_shield]: https://travis-ci.org/hertzg/node-net-keepalive.svg?branch=master\n[daviddm_url]: https://david-dm.org/hertzg/node-net-keepalive\n[daviddm_shield]: https://david-dm.org/hertzg/node-net-keepalive.svg\n[license_url]: https://raw.githubusercontent.com/hertzg/node-net-keepalive/master/LICENSE\n[license_shield]: https://img.shields.io/badge/license-MIT-blue.svg\n[codecov_url]: https://codecov.io/gh/hertzg/node-net-keepalive\n[codecov_shield]: https://codecov.io/gh/hertzg/node-net-keepalive/branch/master/graph/badge.svg\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-12-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\n# 🔗 net-keepalive\n\n[![NPM](https://nodei.co/npm/net-keepalive.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/net-keepalive/)\n\n\u003e ℹ️ Since [libuv v1.35.0](https://github.com/libuv/libuv/blame/e45f1ec38db882f8dc17b51f51a6684027034609/src/unix/tcp.c#L387-L390) (Node `v13.12.0` \u0026 `v12.17.0`) [both `TCP_KEEPINTVL` and `TCP_KEEPCNT` have somewhat predictable values](https://github.com/libuv/libuv/pull/2669)\n\u003e This package allows you to tweak those values per each socket but at a cost of having to deal with FFI overhead and it's dependencies.\n\u003e [Check the latest node docs for socket.setKeepaliveEnable](https://nodejs.org/api/net.html#socketsetkeepaliveenable-initialdelay), if the default values are good enough for you then you don't need to use this package. \n\nThe Missing (`TCP_KEEPINTVL` and `TCP_KEEPCNT`) `SO_KEEPALIVE` socket option setters and getters for Node using FFI.\n\nTested on 🐧 `linux` \u0026 🍏 `osx` (both `amd64` and `arm64`), should work on 😈 `freebsd` and others. \nInstalls on 🐄 `win32` 🎉 but methods are no-ops (pull requests welcome).\n\nThere's also support for getting \u0026 setting the `TCP_USER_TIMEOUT` (🐧 `linux`  and 🍏 `osx` only) option, which is closely related to keep-alive.\n\n\n## Platform support\n\n| Platform     | TCP_KEEPINTVL | TCP_KEEPCNT | TCP_USER_TIMEOUT            |\n| ------------ | ------------- | ----------- | --------------------------- |\n| 🐧 `linux`   | ✅            | ✅          | ✅                          |\n| 🍏 `osx`     | ✅            | ✅          | ✅ (`TCP_RXT_CONNDROPTIME`) |\n| 😈 `freebsd` | ✅            | ✅          | ❌                          |\n| 🐄 `win32`   | ➖            | ➖          | ➖                          |\n\nLegend:\n\n- ✅ - Supported\n- ➖ - No operation \n- ❌ - Unsupported (throws)\n\n## Install\n\n```bash\nnpm install --save net-keepalive\n```\n\n## Documentation\n\nYou can find the [full API Reference Document (JSDoc)](https://hertzg.github.io/node-net-keepalive) published on our github pages.\n\nThe project includes TypeScript definitions file (`index.d.ts`) which gives an overview of the API exposed.\n\nDocumentation gets generated from JSDoc comments, feel free to improve them by sending pull requests.\n\n## Demo\n\n```javascript\nconst Net = require('net'),\n  NetKeepAlive = require('net-keepalive')\n// or\nimport * as Net from 'net'\nimport * as NetKeepAlive from 'net-keepalive'\n\n// Create a TCP Server\nconst srv = Net.createServer((s) =\u003e {\n  console.log('Connected %j', s.address())\n  // Doesn't matter what it does\n  s.pipe(s)\n})\n\n// Start on some port\nsrv.listen(1337, () =\u003e {\n  console.log('Listening on %j', srv.address())\n})\n\n// Connect to that server\nconst s = Net.createConnection({ port: 1337 }, () =\u003e {\n  console.log('Connected to %j', s.address())\n\n  //IMPORTANT: KeepAlive must be enabled for this to work\n  s.setKeepAlive(true, 1000)\n\n  // Set TCP_KEEPINTVL for this specific socket\n  NetKeepAlive.setKeepAliveInterval(s, 1000)\n\n  // Get TCP_KEEPINTVL for this specific socket\n  NetKeepAlive.getKeepAliveInterval(s) // 1000\n\n  // Set TCP_KEEPCNT for this specific socket\n  NetKeepAlive.setKeepAliveProbes(s, 1)\n\n  // Get TCP_KEEPCNT for this specific socket\n  NetKeepAlive.getKeepAliveProbes(s) // 1\n})\n```\n\nNow using `iptables` add rule to drop all `tcp` packets on `INPUT` chain to port `1337`.\n\n```bash\niptables -I INPUT -m tcp -p tcp --dport 1337 -j DROP\n```\n\nIf you were monitoring packets on `loopback` with `tcp.srcport == 1337 || tcp.dstport == 1337` filter in `wireshark`. You will see the following output:\n\n[![Wireshark screenshot KEEPALIVE](http://hertzg.github.io/node-net-keepalive/images/wireshark.jpg)](http://hertzg.github.io/node-net-keepalive/images/wireshark.jpg)\n\nHave fun!\n\nMore info about `SO_KEEPALIVE` here: [TCP Keepalive HOWTO](http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/)\n`C` Code examples here: [Examples](http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html#examples)\n\n## Sample\n\n**_Note: For these methods to work you must enable `SO_KEEPALIVE` and set the `TCP_KEEPIDLE` options for socket using `Net.Socket`-s built in method [`socket.setKeepAlive([enable][, initialDelay])`](https://nodejs.org/api/net.html#net_socket_setkeepalive_enable_initialdelay) !_**\n\n\n    TCP_KEEPIDLE (since Linux 2.4) The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket. This option should not be used in code intended to be portable.\n\n```JavaScript\nconst NetKeepAlive = require('net-keepalive')\n// or\nimport * as NetKeepAlive from 'net-keepalive'\n\n// .....\n\nconst enable = true                                             // enable SO_KEEPALIVE\nconst initialDuration = 1000                                    // start probing after 1 second of inactivity\nsocket.setKeepAlive(enable, initialDuration)                    // sets SO_KEEPALIVE and TCP_KEEPIDLE\n\nconst probeInterval = 1000                                      // after initialDuration send probes every 1 second\nNetKeepAlive.setKeepAliveInterval(socket, probeInterval)        //sets TCP_KEEPINTVL\n\nconst maxProbesBeforeFail = 10                                  // after 10 failed probes connection will be dropped\nNetKeepAlive.setKeepAliveProbes(socket, maxProbesBeforeFail)    // sets TCP_KEEPCNT\n\n// ....\n```\n\n## Code of Conduct\n\nSee [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://hertz.gg\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/1886698?v=4?s=100\" width=\"100px;\" alt=\"George Hertz\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGeorge Hertz\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#maintenance-hertzg\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e \u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=hertzg\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=hertzg\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=hertzg\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#platform-hertzg\" title=\"Packaging/porting to new platform\"\u003e📦\u003c/a\u003e \u003ca href=\"#question-hertzg\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/mildsunrise\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/1177304?v=4?s=100\" width=\"100px;\" alt=\"Alba Mendez\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAlba Mendez\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=mildsunrise\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=mildsunrise\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=mildsunrise\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://www.linkedin.com/in/pfcastro/\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/15091591?v=4?s=100\" width=\"100px;\" alt=\"Paulo Castro\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePaulo Castro\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Apdcastro\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://www.immersiveapplications.com/\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/481412?v=4?s=100\" width=\"100px;\" alt=\"Jacob Jewell\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJacob Jewell\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Ajakesjews\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/RMutharaju\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/37263240?v=4?s=100\" width=\"100px;\" alt=\"RMutharaju\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRMutharaju\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#security-RMutharaju\" title=\"Security\"\u003e🛡️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/borger\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/5930158?v=4?s=100\" width=\"100px;\" alt=\"Rafael Borges\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRafael Borges\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Aborger\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/selient\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/3947590?v=4?s=100\" width=\"100px;\" alt=\"Calvin\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eCalvin\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Aselient\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/ggsubs\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/2170237?v=4?s=100\" width=\"100px;\" alt=\"ggsubs\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eggsubs\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Aggsubs\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://mario.kozjak.io/\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/3506172?v=4?s=100\" width=\"100px;\" alt=\"Mario Kozjak\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMario Kozjak\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Amkozjak\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://codeisland.org/\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/692211?v=4?s=100\" width=\"100px;\" alt=\"Lukas Knuth\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLukas Knuth\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/commits?author=LukasKnuth\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/ikb42\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5161291?v=4?s=100\" width=\"100px;\" alt=\"Ivan\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eIvan\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Aikb42\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/otaviojacobi\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/14330369?v=4?s=100\" width=\"100px;\" alt=\"Otávio Jacobi\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eOtávio Jacobi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/hertzg/node-net-keepalive/issues?q=author%3Aotaviojacobi\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhertzg%2Fnode-net-keepalive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhertzg%2Fnode-net-keepalive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhertzg%2Fnode-net-keepalive/lists"}