![](\"https://raw.githubusercontent.com/DaxBot/sockhop/master/assets/sockhop_365px.png\")
\n \n \n
Node.js IPC
\n\n\n- Object centric - put a string, object, Widget, whatever into one end and it comes out the other\n- Buffers allowed - pick your level of optimization -> send full objects or raw buffers\n- Uses TCP sockets or Unix domain sockets transparent to you\n- Easy wrappers over the tricky parts of net.socket\n- Auto reconnect\n- Ping with auto disconnect/reconnect\n- Remote callbacks across socket (basically promises over the wire)\n- Manages binary buffers across the wire, reconstructs fragments back into objects/buffers\n\n## Example\nHere's some basic examples, but check out the [full documentation here](API.md)\n\n### Basic example:\n```javascript\nconst Sockhop=require(\"sockhop\");\n\n// Create server/client pair\nlet s=new Sockhop.Server(); // You can specify a socket location, IP address, etc. or it will pick defaults\nlet c=new Sockhop.Client();\n\n// Something to pass \nclass Widget { /* ... */ }\n\n// Pass a Widget\ns.listen()\n.then(()=>c.start()) // Version 1.x used: c.connect(), which is no longer preferred: see API for details\n.then(()=>{\n\n // Send everyone a Widget \n s.sendall(new Widget()); // Can put anything here, including a raw buffer!\n\n});\n\nc.on(\"receive\", (obj, metadata)=>{\n\n // obj is serialized Widget\n // metadata.type==\"Widget\"\n\n}); \n\n```\n### Special Case: Sending a buffer\nBuffers do not, by default, nicely pack into JSON, so Sockhop has special handling for them. If you wish to send a literal, raw buffer, you can do so by passing them\nto the `.send()` method, and they will be emitted on the other side as a `receive` event with `metadata.type==\"Buffer\"`. Currently, Sockup does not support Buffers\nas part of a larger object. Note, that if the connection is not yet in binary mode (e.g. before a handshake is complete), the buffer will be base64 encoded to get it across the wire,\nbut after binary mode is established, it will be sent as raw binary data (i.e. no overhead).\n```javascript\nconst buf = Buffer.from(\"Hello, World!\");\n\ns.on(\"receive\", (obj, meta) => {\n if ( meta.type === \"Buffer\" ) {\n console.log(\"Got a buffer:\", obj.toString()); // obj is a Buffer\n }\n});\n\nc.send(buf); // Send a raw buffer\n\n```\n\nWARNING: Sending raw buffers is only semi-supported interoperating with 1.x remotes. 1.x does not support binary mode, so buffers will always be base64 encoded, but more\nimportantly, 1.x remotes do not support the encoding/decoding of the base64 strings for you. As a result, if you are committed to using a 1.x remote, but want to send raw buffers,\nyou will need to do the base64 encoding/decoding yourself:\n```javascript\n// On the 1.x remote\nc.on(\"receive\", (obj, meta) => {\n if ( meta.type === \"Buffer\" ) {\n // obj is a base64 string\n const buf = Buffer.from(obj, 'base64'); // Decode the base64 string into a Buffer\n console.log(\"Got a buffer:\", buf.toString());\n }\n});\n```\nHowever, at the point where you are editing the 1.x remote code, you might as well upgrade to 2.x and run in compatibility mode, which gives you RX/TX Buffers, but retain the 1.x behavior otherwise.\n\n### Sending Typed Buffers\nSending a raw buffer is great, but you usually want to know what kind of buffer it is so that you can easily send mutliple different types of buffers.\nSockhop supports sending typed buffers, but only in binary mode (i.e. after a handshake is complete).\nTo send a typed buffer, use the `.send_typed_buffer(type, buffer)` method. The `type` can be any string you want (less than 256 characters), and will be passed to the\nreceiver in `metadata.type` as part of the `receive:buffer` event. The `buffer` is a Node.js Buffer object (less than 4GB).\n\nThis workflow is helpful particularly if you want to implement your own custom serialization for a type. For example:\n```javascript\n// Set up a manual serialization for a custom type:\nclass MyUint32 {\n constructor(value) {\n this.value = value;\n }\n\n static from_buffer(buffer) {\n if ( buffer.length !== 4 ) throw new Error(\"Buffer length must be 4 bytes\");\n const value = buffer.readUInt32BE(0);\n return new MyUint32(value);\n }\n\n to_buffer() {\n const buffer = Buffer.alloc(4);\n buffer.writeUInt32BE(this.value);\n return buffer;\n }\n}\n\n// Must succeed the handshake:\nawait c.start(); // NOTE : `.connect()` will NOT work here, since it does not wait for the handshake to complete\n\n// Must be in binary mode to send typed buffers, this will be true after `start()` unless you configured the client/server to not allow binary mode\nif ( !c.binary_mode.tx ) throw new Error(\"Client is not in binary mode\");\n\n// Setup to receive typed buffers\ns.on(\"receive:buffer\", (buffer, meta) => { // <- NOTE this is *not* the same as \"receive\" event\n if ( meta.type === \"MyUint32\" ) {\n const my_int32 = MyUint32.from_buffer(obj);\n console.log(\"Got a MyUint32:\", my_int32.value);\n }\n});\n\n// Send a typed buffer\nconst my_value = new MyUint32(42);\nc.send_typed_buffer(\"MyUint32\", my_value.to_buffer());\n\n```\n\n### Remote callback example:\nSockhop also supports a request/reply pattern using callbacks. Just pass a function as the second argument to `.send()`, and it will be called on the remote side\nwith the reply:\n```javascript\n// Set up the handler\nServer.on(\"receive\", (obj, meta)=>{\n // obj==\"Promise to call when you get this\"\n meta.callback(\"I got your message!\");\n});\n\n// Send the message, with a callback to catch the reply\nc.send(\"Promise to call when you get this\", (reply)=>{\n // reply == \"I got your message!\"\n});\n```\n\n### Session example:\nThe client since allows for nice customization, since you control the client instantiation, however, you can also customize the Server side\nby extending the SockhopSession class. This is useful for things like authentication, etc.\n```javascript\nconst Sockhop=require(\"sockhop\");\n\n/**\n * Class to save verification information about a\n * socket\n */\nclass Session extends Sockhop.Session {\n constructor(socket, server) {\n super();\n this.socket = socket; // Save a reference to the socket\n this.verified = false;\n }\n async start() {\n // Require sockets to verify themselves with in 3 seconds\n this.to = setTimeout(() => this.socket.end(), 3000);\n }\n verify() {\n this.verified = true;\n clearTimeout(this.to);\n }\n}\n\n// Create server/client pair\nlet s=new Sockhop.Server({session_type : Session});\nlet c=new Sockhop.Client();\n\ns.on('receive', (data, meta) => {\n // Require verification to continue\n if ( !meta.session.verified && meta.type !== 'Verify' ) return;\n\n switch ( meta.type ) {\n case \"Verify\":\n // run verification code here\n meta.sesison.verify();\n case \"Other\":\n // run everything else here\n }\n});\n\ns.listen()\n.then(()=>c.start()) // Version 1.x used: c.connect(), which is no longer preferred: see API for details\n.then(()=>{\n c.send(\"some verification object\");\n});\n```\n\n### Handshake example:\nFor the 2.x libarary version, it is strongly recommended that you use handshake-based connections and events for managing lifecycle:\n```js\nconst client = new Sockhop.Client({ auto_rehandshake: true });\nawait client.start(); // Waits for handshake to complete\n\nclient.binary_mode.tx; // has a definite value, now that the handshake is complete\n\nclient.on(\"handshake\", (success, error) => {\n // Can catch errors where, or handle re-connections\n});\n\nclient.on(\"unhandshake\", () => {\n // Handle when a handshaked-connection is lost\n});\n\nawait client.disconnect();\n```\n\n### Interoperating with 1.x/compatibility mode remotes:\nThat being said, if you are trying to interoperate with a 1.x/compatibility mode remote, many of the above methods/events\nwill mis-behave, since the handshake doesn't success with a 1.x/compatibility mode remote. In that case, you will need to\nhandle both cases:\n\n```js\nconst client = new Sockhop.Client({ auto_reconnect: true });\n\nclient.on(\"receive\", (obj, meta) => {\n // Attach handlers *before* calling connect, since 1.x/compatibility mode remotes can start sending data immediately after the connect event\n\n // If you want to differentiate, you can switch on client.handshake_successful or client.binary_mode.rx == true\n if ( client.handshake_successful ) {\n // 2.x+ client\n } else {\n // 1.x/compatibility mode client\n }\n});\n\n// await client.start(); // This will throw an error if the remote is 1.x/compatibility mode\nawait client.connect(); // Does not wait for handshake to complete\n\nclient.on(\"handshake\", (success, error) => {\n // Use this for reconnctions, and to differentiate between 2.x+ and 1.x/compatibility mode remotes:\n // Check for error.code==\"ERR_HANDSHAKE_TIMEOUT\"\n\n if ( success ) {\n // 2.x+ client\n } else if (error.code==\"ERR_HANDSHAKE_TIMEOUT\") {\n // 1.x/compatibility mode remote\n } else {\n // Handle error\n }\n});\n\n\n// client.on(\"unhandshake\", () => {}); // Only fires for 2.x+ handshaked-connection lost:\nclient.on(\"disconnect\", (sock, handshaked) => {\n if ( handshaked ) {\n // 2.x+ handshaked-connection lost, same as unhandshake event\n } else {\n // Handle 1.x/compatibility or 2.x+failed handshake disconnects\n }\n});\n\nawait client.disconnect(); // Disconnects cleanly\n```\n \nIf you would rather skip the complexity, and just have this library behave like 1.x, you can enable compatibility mode,\nthough, this will totally disable all handshake-related features.\n```js\nconst client = new Sockhop.Client({ compatibility_mode: true, auto_reconnect: true });\n\nawait client.connect(); // Does not even attempt a handshake, nor waits for one\n\nclient.binary_mode.tx; // will always be false, since we are not doing a handshake\n\n// client.on(\"handshake\", (success, error) => {}); // this will never fire\nclient.on(\"connect\", () => {\n // but this will!\n});\n\n// client.on(\"unhandshake\", () => {}); // Also will never fire\nclient.on(\"disconnect\", (sock, handshaked) => {\n handshaked; // will always be false\n});\n\nawait client.disconnect(); // Disconnects cleanly\n```\n\n## Notes\nSockhop easily passes objects across the wire. If you pack/transcode JS in a way that mutates class names, this functionality will be broken! This includes auto ping functionality.\n\nIf you ```server.listen()```, make sure you ```server.close()``` when you are done so Node won't hang forever on program exit. Similarly, if you turn on ```client.ping()``` or set ```client({auto_reconnect:true})```, make sure you finish up by ```client.ping(0)``` (to disable pings) and ```client.disconnect()``` (note this will also stop pinging).\n\n\n## Migrating from 1.x to 2.x\nSockhop 2.x is mostly backwards compatible with 1.x, but there are a few changes:\n- The `Sockhop` object has had its keys captialized: e.g. `Sockhop.client` is now `Sockhop.Client`, `Sockhop.server` is now `Sockhop.Server`, etc.\n- The `client.start()` method has been added, which is now the preferred way to connect a client, as it waits for the handshake to succeed.\n - `client.start()` will attempt to connect once (throwing if the handshake fails). Then if `auto_rehandshake` is set to true, it will start the reconnect loop.\n- The `auto_reconnect` setter has been removed.\n - Instead, set `auto_reconnect` in the options object when creating the client: `new Sockhop.client({auto_reconnect:true})` and then call `client.start()/client.connect()`.\n - Note: the `client.start()/client.connect()` methods will only start the reconnect loop if the initial call succeds,\n so you will probably want to wrap it in a loop with a try/catch if you want to keep trying until it connects. See the API docs for details.\n- The `client.connect()` method is still available, but it is no longer the preferred way to connect a client.\n - Instead, use `client.start()`\n - The exception here is if you need to interopterate with a 1.x/compatibility_mode server, in which case you should use `client.connect()` and listen for\n the `handshake` event to know when the connection is ready - see the API docs for details.\n\n\n## Linting, building docs, and testing\n```sh\nnpm run lint:fix\nnpm run build\nnpm run test\n```\n\n## License\nMIT\n","readmeFilename":"README.md"}