{"id":17771431,"url":"https://github.com/rootslab/cocker","last_synced_at":"2025-03-15T16:31:04.953Z","repository":{"id":6342909,"uuid":"7579050","full_name":"rootslab/cocker","owner":"rootslab","description":"Cocker, a socket module to aggressively handle connection retries.","archived":false,"fork":false,"pushed_at":"2018-01-01T01:16:31.000Z","size":146,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-09T07:40:23.044Z","etag":null,"topics":["cocker","conne","connection-loop","connection-retry","native-promises","nodejs","reconnection","socket"],"latest_commit_sha":null,"homepage":"","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/rootslab.png","metadata":{"files":{"readme":"Readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-01-12T18:46:24.000Z","updated_at":"2018-01-01T16:19:03.000Z","dependencies_parsed_at":"2022-09-17T12:01:07.873Z","dependency_job_id":null,"html_url":"https://github.com/rootslab/cocker","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fcocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootslab","download_url":"https://codeload.github.com/rootslab/cocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221585972,"owners_count":16847857,"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":["cocker","conne","connection-loop","connection-retry","native-promises","nodejs","reconnection","socket"],"created_at":"2024-10-26T21:32:52.086Z","updated_at":"2025-03-15T16:31:04.944Z","avatar_url":"https://github.com/rootslab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Cocker\n\n[![NPM VERSION](http://img.shields.io/npm/v/cocker.svg?style=flat)](https://www.npmjs.org/package/cocker)\n[![CODACY BADGE](https://img.shields.io/codacy/b18ed7d95b0a4707a0ff7b88b30d3def.svg?style=flat)](https://www.codacy.com/public/44gatti/cocker)\n[![CODECLIMATE-TEST-COVERAGE](https://img.shields.io/codeclimate/c/rootslab/cocker.svg?style=flat)](https://codeclimate.com/github/rootslab/cocker)\n[![LICENSE](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/rootslab/cocker#mit-license)\n\n![NODE VERSION](https://img.shields.io/node/v/cocker.svg)\n[![TRAVIS CI BUILD](http://img.shields.io/travis/rootslab/cocker.svg?style=flat)](http://travis-ci.org/rootslab/cocker)\n[![BUILD STATUS](http://img.shields.io/david/rootslab/cocker.svg?style=flat)](https://david-dm.org/rootslab/cocker)\n[![DEVDEPENDENCY STATUS](http://img.shields.io/david/dev/rootslab/cocker.svg?style=flat)](https://david-dm.org/rootslab/cocker#info=devDependencies)\n\n[![NPM MONTHLY](http://img.shields.io/npm/dm/cocker.svg?style=flat)](http://npm-stat.com/charts.html?package=cocker)\n[![NPM YEARLY](https://img.shields.io/npm/dy/cocker.svg)](http://npm-stat.com/charts.html?package=cocker)\n[![NPM TOTAL](https://img.shields.io/npm/dt/cocker.svg)](http://npm-stat.com/charts.html?package=cocker)\n\n[![NPM GRAPH](https://nodei.co/npm/cocker.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/cocker/)\n\n__Cocker__, a socket module to __aggressively__ handle connection retries.\n\n\u003e __NOTE__: It directly inherits from __net.Socket__. \n\n### Table of Contents\n\n- __[Install](#install)__\n- __[Run Tests](#run-tests)__\n- __[Constructor](#constructor)__\n- __[Options](#options)__\n- __[Properties](#properties)__\n- __[Methods](#methods)__\n    - __[bye](#cockerbye)__    \n    - __[run](#cockerrun)__\n    - __[die](#cockerdie)__\n    - __[hunt](#cockerhunt)__\n    - __[prey](#cockerprey)__\n    - __[watch](#cockerwatch)__\n- __[Events](#events)__\n- __[Examples](#examples)__\n  - __[Simple Mode](#simple-mode)__ \n    - __[re-connection loop with run](#simple-mode)__\n  - __[Native Promises](#native-promises)__\n    - __[connection with hunt](#native-promises)__\n    - __[connection with prey (through an address list)](#native-promises)__\n    - __[looping with watch](#native-promises)__\n    - __[looping (indefinitely) with hunt and watch](#native-promises)__\n- __[MIT License](#mit-license)__\n\n------------------------------------------------------------------------------\n\n### Install\n\n```bash\n$ npm install cocker [-g]\n```\n\n\u003e __require__:\n\n```javascript\nconst Cocker  = require( 'cocker' );\n```\n\n### Run Tests\n\n```bash\n$ cd cocker/\n$ npm test\n```\n\n __to execute a single test file simply do__:\n\n```bash\n $ node test/file-name.js\n```\n\n------------------------------------------------------------------------------\n\n### Constructor\n\n\u003e Arguments between [ ] are optional.\n\n```javascript\nCocker( [ Object options ] )\n```\n\u003e or\n```javascript\nnew Cocker( [ Object options ] )\n```\n\n#### Options\n\n\u003e __NOTE__: default options are listed.\n\n\u003e It accepts a configuration hash/object:\n\n###### option\n```javascript\n{\n , address : Object\n , connection : Object\n , reconnection : Object\n}\n```\n\n###### option.address (default)\n```javascript\n{\n    host : '127.0.0.1'\n    , port : 0\n    , family : null\n    /*\n     * Specify an IPC endpoint, like a unix domain socket, if a string is\n     * provided, the TCP-specific options above are ignored.\n     * For further details, see \"Identifying paths for IPC connections\" in \n     * the /api/net section.\n     */\n    , path : null\n }\n```\n\n###### option.address (additional options for net.Socket)\n```javascript\n{   \n    // should connect from\n    localAddress : undefined\n    , localPort: undefined\n    // custom lookup and hints\n    , lookup : dns.lookup \n    , hints : 0\n }\n```\n\n###### option.connection\n```javascript\n {\n    encoding : null\n    , keepAlive : true\n    , timeout : 0\n    , noDelay : true\n    , allowHalfOpen : false\n }\n```\n\n###### option.reconnection\n```javascript\n {\n    trials : 3\n    , interval : 1000\n    /*\n     * A value to use for calculating the pause between two\n     * connection attempts. Default value is the golden ratio.\n     * Final value is calculated as:\n     * interval * Math.pow( factor, curr.attempts + 1 )\n     */\n    , factor : ( Math.sqrt( 5 ) + 1 ) / 2\n }\n```\n------------------------------------------------------------------------------\n\n### Properties\n\n\u003e __NOTE__: do not mess up with these properties.\n\n##### a property that holds the current configuration object\n```javascript\nCocker.options : Object\n```\n\n##### current number of connection attempts\n```javascript\nCocker.attempts : Number\n```\n\n##### a flag to signal the current status of the connection\n```javascript\nCocker.lost : Boolean\n```\n\n##### a flag used to disable reconnection (after #hunt Promise resolution)\n```javascript\nCocker.stop : Boolean\n```\n\n##### current lapse of time (to wait) until the next connection attempt\n```javascript\nCocker.lapse : Number\n```\n------------------------------------------------------------------------------\n\n### Methods\n\n\u003e all the methods from net.Socket module are inherited.\n\n|            name          |                   description                    |\n|:-------------------------|:-------------------------------------------------|\n| __[bye](#cockerbye)__    | `end the connection.`                            |\n| __[run](#cockerrun)__    | `connect to a socket or attempting to.`          |\n| __[die](#cockerdie)__    | `end the connection. (Promise)`                  |\n| __[hunt](#cockerhunt)__  | `connect to a socket or attempting to. (Promise)`|\n| __[prey](#cockerprey)__  | `connect using a list of hosts. (Promise)`       |\n| __[watch](#cockerwatch)__| `re-connect after losing the current connection. (Promise)` |\n\n\u003e Arguments between [ ] are optional.\n\n#### Cocker.bye\n\u003e ##### end the connection (without re-connecting).\n```javascript\n'bye' : function ( [ Buffer | String data [, String enc ] ] ) : undefined\n```\n\n#### Cocker.run\n\u003e ##### connect to a socket or attempting to (k times).\n```javascript\n// it optionally accepts a cocker option object to reconfigure the socket.\n'run' : function ( [ Object cocker_options ] ) : undefined\n```\n\n#### Cocker.die\n\u003e ##### end the connection (without re-connecting).\n```javascript\n// Promise will not be resolved until 'lost' event\n'die' : function ( [ Buffer | String data [, String enc ] ] ) : Promise\n```\n\n#### Cocker.hunt\n\u003e ##### connect to a socket or attempting to (k times).\n```javascript\n/*\n * Try to connect to a socket. Promise will not be resolved until 'online',\n * rejected after 'lost' event; it optionally accepts a cocker option object\n * to reconfigure the socket.\n */\n'hunt' : function ( [ Object cocker_options ] ) : Promise\n```\n\n#### Cocker.prey\n\u003e ##### try to connect until success, using a list of optional hosts/config.\n```javascript\n/*\n * It recursively scan a list, using #hunt Promises. The #prey Promise will \n * not be resolved until a connection will be made, definitively rejected\n * when no hosts had accepted one. \n * Every host in the list should be an object like Cocker.options.address.\n */\n'prey' : function ( Array hosts ) : Promise\n```\n\n#### Cocker.watch\n\u003e ##### try to re-connect after losing the current connection.\n```javascript\n/*\n * When the current established connection is lost, it tries to reconnect.\n * This Promise has the same resolution as for #hunt, the only difference is\n * that this Promise was \"registered\" on socket disconnection, then it will be\n * resolved/rejected only after capturing a 'lost' event from the current\n * broken connection. See examples.\n */\n'watch' : function ( [ Object cocker_options ] ) : Promise\n```\n\n------------------------------------------------------------------------------\n\n### Events\n\n\u003e all the events from net.Socket module are inherited.\n\n##### !online: connection was established.\n```javascript\n// when: soon after socket !connect event\n'online' : function ( Object address  )\n```\n\n##### !offline: connection is down.\n```javascript\n// when: on the first !close event for the current socket\n'offline' : function ( Object address  )\n```\n\n##### !attempt: current connection attempt.\n```javascript\n// when: after !offline, on every connection attempt, until !lost or !online \n'attempt' : function ( Number t, Object address, Number lapse )\n```\n\n##### !lost: no other attempts will be made, connection is definitively lost.\n```javascript\n// when: soon before the last !close event.\n'lost' : function ( Number t, Object address, Number lapse )\n```\n------------------------------------------------------------------------------\n\n### Examples\n\n#### Simple Mode\n\n - __[re-connection loop with run](example/run-reconn-loop-example.js)__\n\n#### Native Promises\n\n  - __[connection with hunt](example/promises-single-address-example.js)__\n  - __[connection with prey (through an address list)](example/promises-multi-address-example.js)__\n  - __[looping with watch](example/promises-reconn-loop-example.js)__\n  - __[looping (indefinitely) with hunt and watch](example/promises-reconn-infinite-loop-example.js)__\n\n\u003e See __[examples](example/)__.\n\n### MIT License\n\n\u003e Copyright (c) 2013-present \u0026lt; Guglielmo Ferri : 44gatti@gmail.com \u0026gt;\n\n\u003e Permission is hereby granted, free of charge, to any person obtaining\n\u003e a copy of this software and associated documentation files (the\n\u003e 'Software'), to deal in the Software without restriction, including\n\u003e without limitation the rights to use, copy, modify, merge, publish,\n\u003e distribute, sublicense, and/or sell copies of the Software, and to\n\u003e permit persons to whom the Software is furnished to do so, subject to\n\u003e the following conditions:\n\n\u003e __The above copyright notice and this permission notice shall be\n\u003e included in all copies or substantial portions of the Software.__\n\n\u003e THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\n\u003e EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n\u003e MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\n\u003e IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\n\u003e CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\n\u003e TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\n\u003e SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fcocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootslab%2Fcocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fcocker/lists"}