initial commit

.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+node_modules
+dump.rdb
+npm-debug.log
+*.tgz

README.md

@@ -0,0 +1,36 @@
+# Echo Request Responder for SocketStream 0.3
+
+This is an example of an ultra-simple Request Responder for SocketStream.
+
+The echo responder simply converts any incoming message into uppercase before sending it back to the browser.
+
+The code has been fully annotated to encourage you to use it as a basis to develop your own Request Responder, allowing you to experiment with models, low-level protocols (for gaming), user presence and much more.
+
+
+### Try it out
+
+Clone the repo locally and install it with:
+
+    [sudo] npm link
+
+Create a new SocketStream project and create a local link to this repo:
+
+    cd my_new_socketstream_project
+    [sudo] npm link ss-echo-responder
+
+Add the Echo Responder to your stack:
+
+```javascript
+// in app.js
+ss.responders.add(require('ss-echo-responder'));
+```
+
+Start your app then call the Echo Responder in the browser's console:
+
+    ss.echo('Test from browser');
+
+The responder will transform the message into uppercase before calling `alert()` in the browser.
+
+***
+
+To find out how to use this project as a basis for you own Request Responder, please [read the documentation here](https://github.com/socketstream/socketstream/blob/master/doc/guide/en/writing_request_responders.md).

client/responder.js

@@ -0,0 +1,40 @@
+// This module is sent to the browser
+
+var ss = require('socketstream');
+
+module.exports = function(responderId, config, send){
+
+  // SENDING //
+
+  // Optionally attach your own custom function to the 'ss' object
+  // Here we're registering 'ss.echo()'
+  ss.registerApi('echo', function(){
+
+    // In this simple example we're only interested in the first argument sent to ss.echo()
+    var args = Array.prototype.slice.call(arguments);
+    var msg = args[0];
+
+    // Do basic error checking client-side when possible
+    if (msg && msg.length > 0) {
+
+      console.log("Sending '" + msg + "' to the server...");
+      send(msg);
+
+    } else {
+
+      console.log('Error: Please pass a valid string to the first argument');
+
+    }
+
+  });
+
+  // RECEIVING //
+
+  // Listen for incoming messages
+  ss.message.on(responderId, function(msg){
+
+    alert('Echo Responder says: ' + msg);
+
+  });
+
+}

package.json

@@ -0,0 +1,18 @@
+{
+  "name": "ss-echo-responder",
+  "description": "Example Request Responder for SocketStream",
+  "author": "Me <me@mydomain.com>",
+  "version": "0.1.0",
+  "main": "./server/index.js",
+  "repository": {
+    "type" : "git",
+    "url": "https://github.com/my/repo.git"
+  },
+  "engines": {
+    "node": ">= 0.6.0"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+  }
+}

server/index.js

@@ -0,0 +1,78 @@
+// Example 'Echo' Request Responder code for SocketStream
+// Simply transforms incoming messages to uppercase before sending the message back to the browser
+
+var fs = require('fs'),
+    path = require('path');
+
+// responderId : The unique ID assigned to this Request Responder by SocketStream
+// config      : Any optional config params defined by the user in their own /app.js file
+// ss          : The SocketStream internal API object
+module.exports = function(responderId, config, ss){
+
+  var name = config && config.name || 'echo';
+
+  /// SENDING CLIENT-SIDE CODE ///
+
+  // The ss.client.send function allows you to send any type of code to the browser
+  // Note: All client-side code will be automatically minimized in production but
+  // please take care to only send what is absolutely required, as every byte counts
+
+  // Here's an example of sending a client-side library to the browser
+  //ss.client.send('lib', 'underscore', loadFile('underscore.js'));
+
+  // Send client-side code for this responder as a module
+  ss.client.send('mod', 'echo-responder', loadFile('responder.js'));
+
+  // Automatically initialize the client-side module when the browser loads
+  // Change 'echo-responder' to the name of your responder, but don't change the arguments passed
+  ss.client.send('code', 'init', "require('echo-responder')("+responderId+", {}, require('socketstream').send("+responderId+"));")
+
+  // Return Responder API
+  return {
+
+    name: name,
+
+    /// EXPOSING SERVER-SIDE INTERFACES ///
+
+    // Once ss.start(server) has been called in your app.js file, any middleware in
+    // /server/middleware will be loaded and passed into the function below
+    // Whether or not your module chooses to use it is up to you
+    interfaces: function(middleware){
+
+      return {
+
+        // Expose the Websocket interface. Other interfaces (to allow you to access this responder over ss-console
+        // or for server-side testing) are currently being finalized and will be available as options in the near future
+        //
+        // msg  : the raw incoming message (as a string)
+        // meta : an object containing additional meta data about this request
+        // send : a function to send a response back to the originating client (optional)
+        websocket: function(msg, meta, send){
+
+          // Log incoming message to the terminal
+          ss.log('↪'.cyan, 'echo'.grey, msg);
+
+          // Transform message to uppercase
+          msg = String(msg.toUpperCase());
+
+          // Log outgoing message to the terminal
+          ss.log('↩'.green, 'echo'.grey, msg);
+
+          // Send a response back to the originating client
+          // Note: This is optional. If your client code is simply sending a heartbeat
+          // you may not necessarily want to acknowledge every request
+          send(msg);
+
+        }
+
+      }
+    }
+  }
+}
+
+// Helper to load client files
+// Note we use readFileSync as the file is only ever loaded once when you start the server and cached in RAM thereafter
+var loadFile = function(name){
+  var fileName = path.join(__dirname, '../client', name);
+  return fs.readFileSync(fileName, 'utf8');
+}