Merge pull request #3 from crussell52/next

Merge v0.2.0 code to master

Author: crussell52

README.md

@@ -0,0 +1,10 @@
+# Advanced Usage
+
+For the most obvious use cases, you probably don't need this stuff. But these are the things you might find useful
+when things get... _interesting_.
+
+## Custom Encoding and Decoding
+
+## Talking to Processes Outside of Node
+
+## Throttling Messages

docs/ADVANCED.md

@@ -0,0 +1,60 @@
+# Usage
+
+General knowledge for the simplest use cases. 
+
+## A Note on Safety
+
+Unix socket files exist on the file system. This library does not provide any special handling of their
+creation; it leaves that up to the expert: the [NodeJs net module](https://nodejs.org/api/net.html). In fact, 
+that page has a section dedicated to Node's [IPC support](https://nodejs.org/api/net.html#net_ipc_support)
+that you should probably read, if you are not already famliiar with it.
+
+Because they are files, they are subject to permissions. Make sure you understand how those permissions work 
+for sockets on your target OS. Use appropriate caution to not expose your application's messages to unintended
+audiences **or expose your application to messages from unintended clients!**.
+
+Socket files are very commonly used. You could use this library to tap into any socket file that your process has
+access to! That could be _very_ interesting... but it could also be hazardous. In particular, the `Server` will
+try to use _any_ socket file you tell it to -- even if that socket file is normally used by another service. Now, it 
+can't "hijack" a socket file that another server is actively using, but if you occupy it, the other service may fail
+to start or its client's may think you are their server and start sending unexpected data!
+
+The details of how socket files work and the traps that might lurk in the shadows are **far** beyond the scope of this
+module's documentation. Like any good module, `socket-ipc` tries to hide this complexity from you and get you up
+and running fast. But if this is your first time stepping into this territory, it might still be worth the effort to
+learn a bit about them.  
+
+## Automatic Retry
+
+## Automatic Reconnect
+
+## Working with client ids
+
+## Event Timing
+
+The [API Docs](/docs/API.md) provide tips on minimizing errors by reacting to particular events. The natural question
+is, "Why _minimize_ instead of _eliminate_?"
+
+The simple(ish) answer is because sockets may disconnect at _any moment_, but events listeners are only executed at a 
+very specific phase of the node [event loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/). In 
+other words, it is _always_ possible that the socket may be made unavailable (ended or closed) _before_ attached
+listeners have a chance to react to it.
+
+This module tries to strike a balance between usability and giving you the ability to quickly respond to sockets
+becoming unavailable.
+
+For convenience, `socket-ipc` events will listen for key socket events and either emit more specific events or simply
+_echo_ the original event. For example, whenever a `socket` emits an `error` event `socket-ipc` will handle it by 
+repeating it as its own `error` event. Because of the way the Node event loop works, that means the socket-ipc `error` 
+event may (will?) be "emitted" at least one event loop iteration later than the original socket `error` event. For many 
+cases these _repeats_ should be good enough. However, this is application dependent. 
+
+To allow high-throughput applications respond just a _little bit_ faster when needed, we expose the actual `net.Socket` 
+instance upon connection. We have also sprinkled "hints" in our API docs about when these applications may want to 
+attach listeners directly to the socket event.
+
+Our "official" recommendation is that you listen to the `socket-ipc` events unless the timing is causing specific 
+problems in your application. If you suspect timing side effects, _try_ listening directly to the socket and see if that 
+makes a _worth-while_ difference. But remember, even listening directly the socket does not guarantee that your listener 
+will be able to respond "fast enough" to avoid errors -- sometimes the updated socket state just hasn't made its way 
+into userland Node.

docs/API.md

@@ -22,3 +22,13 @@ client.on('disconnect', () => console.log('disconnected from server'));
 client.on('reconnect', () => console.log('reconnected to server'));
 client.on('message', (message, topic) => console.log(`Heard: [${topic}]`, message));
 client.connect();
+
+
+function shutdown(reason) {
+    // Stop all processing and let node naturally exit.
+    console.log('shutting down: ', reason);
+    client.close();
+}
+
+process.on('SIGTERM', () => shutdown('sigterm'));
+process.on('SIGINT', () => shutdown('sigint'));

docs/USAGE.md

@@ -19,15 +19,17 @@ const {Server} = require('../../src/index');
 
 const SOCKET_FILE = undefined;
 
-
+let server;
 let newServerTimeout;
+let serverCloseTimeout;
 let nextServerNum = 1;
+let shuttingDown = false;
 function createServer() {
     clearTimeout(newServerTimeout);
     const serverNum = nextServerNum++;
     console.log(`creating server (${serverNum})`);
 
-    const server = new Server({socketFile: SOCKET_FILE});
+    server = new Server({socketFile: SOCKET_FILE});
     server.on('connectionClose', (clientId) => console.log(`Client (${clientId}) disconnected`));
     server.on('listening', () => console.log(`server (${serverNum}) is listening`));
     server.on('connection', (clientId) => {
@@ -39,12 +41,21 @@ function createServer() {
     // After the first client connects, start a time to shut down the server.
     // This will show what happens to the client(s) when a server disappears.
     server.once('connection', () => {
+        if (shuttingDown) {
+            return;
+        }
+
         console.log(`Server (${serverNum}) will shut down in 10 second.`);
-        setTimeout(() => server.close(), 10000);
+        clearTimeout(serverCloseTimeout);
+        serverCloseTimeout = setTimeout(() => server.close(), 10000);
     });
 
     // When the server closes, auto-spawn a new one after a second.
     server.on('close', () => {
+        if (shuttingDown) {
+            return;
+        }
+
         console.log(`server (${serverNum}) closed. Starting a replacement server in 5 second.`);
         newServerTimeout = setTimeout(() => createServer(), 5000);
     });
@@ -54,3 +65,17 @@ function createServer() {
 }
 
 createServer();
+
+
+
+function shutdown(reason) {
+    // Stop all processing and let node naturally exit.
+    console.log('shutting down: ', reason);
+    shuttingDown = true;
+    clearTimeout(newServerTimeout);
+    clearTimeout(serverCloseTimeout);
+    server.close();
+}
+
+process.on('SIGTERM', () => shutdown('sigterm'));
+process.on('SIGINT', () => shutdown('sigint'));

examples/resilience/client.js

@@ -0,0 +1,77 @@
+/**
+ * Provides a simple client which makes a lot of noise about the server state.
+ *
+ * Run one or more copies of in conjunction with `server.js` in the same directory to
+ * see how the client deals with an unreliable server.
+ *
+ * Hint: Don't forget to define the SOCKET_FILE before running!
+ *
+ * @author Chris Russell <[email protected]>
+ * @copyright Chris Russell 2018
+ * @license MIT
+ */
+
+const {Client} = require('../../src/index');
+
+const SOCKET_FILE = undefined;
+
+
+let spamInterval;
+function spam() {
+    spamInterval = setInterval(() => {
+        for (let i = 0; i < 300; i++) {
+            client.send('hello', i + ':' + data[Math.floor(Math.random() * Math.floor(999))]);
+        }
+    }, 5);
+}
+
+
+function generate_random_data1(size){
+    let chars = 'abcdefghijklmnopqrstuvwxyz'.split('');
+    let len = chars.length;
+    let random_data = [];
+
+    while (size--) {
+        random_data.push(chars[Math.random()*len | 0]);
+    }
+
+    return random_data.join('');
+}
+
+let data = [];
+for (let i = 0; i < 1000; i++) {
+    data.push(generate_random_data1(32));
+}
+
+
+const client = new Client({socketFile: SOCKET_FILE});
+client.on('connect', (socket) => {
+    socket.on('close', () => {
+        console.log('Server went away (close).');
+        clearInterval(spamInterval);
+    });
+
+    socket.on('end', () => {
+        console.log('Server went away.');
+        clearInterval(spamInterval);
+    });
+
+    console.log('connected to server');
+    spam()
+});
+
+client.on('error', (e) => {
+    console.log(e);
+});
+
+client.connect();
+
+function shutdown(reason) {
+    // Stop all processing and let node naturally exit.
+    console.log('shutting down: ', reason);
+    clearInterval(spamInterval);
+    client.close();
+}
+
+process.on('SIGTERM', () => shutdown('sigterm'));
+process.on('SIGINT', () => shutdown('sigint'));

examples/resilience/server.js

@@ -0,0 +1,46 @@
+/**
+ * Provides a simple client which makes a lot of noise about the server state.
+ *
+ * Run one or more copies of in conjunction with `server.js` in the same directory to
+ * see how the client deals with an unreliable server.
+ *
+ * Hint: Don't forget to define the SOCKET_FILE before running!
+ *
+ * @author Chris Russell <[email protected]>
+ * @copyright Chris Russell 2018
+ * @license MIT
+ */
+
+const {Server} = require('../../src/index');
+
+const SOCKET_FILE = undefined;
+
+const server = new Server({socketFile: SOCKET_FILE});
+server.on('listen', () => {
+    console.log('listening');
+});
+
+
+let msgCount = 0;
+let clientCount = 0;
+server.on('connection', (id, socket) => {
+    clientCount++;
+    socket.on('close', () => clientCount--);
+});
+server.on('message', (message) => msgCount++);
+let statusInterval = setInterval(() => {
+    console.log(`~${msgCount} messages in last 1s from ${clientCount} clients.`);
+    msgCount = 0;
+}, 1000);
+server.listen();
+
+
+function shutdown(reason) {
+    // Stop all processing and let node naturally exit.
+    console.log('shutting down: ', reason);
+    clearInterval(statusInterval);
+    server.close();
+}
+
+process.on('SIGTERM', () => shutdown('sigterm'));
+process.on('SIGINT', () => shutdown('sigint'));

examples/spam/client.js

@@ -1,6 +1,6 @@
 {
   "name": "@crussell52/socket-ipc",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "An event-driven IPC implementation using unix file sockets.",
   "keywords": ["sockets", "ipc", "unix"],
   "homepage": "https://crussell52.github.io/node-socket-ipc/",