Untitled

README.md

@@ -1,53 +1,49 @@
-This will all make more sense once i finish all the todo items at the bottom.
+MAIN TODO: improve this readme. For the moment, you're better off reading the sourcecode of hadoken.coffee
 
-# What is this?
-
-***On the client*** Hadoken exposes a socket.io client (and soon a simple AJAX api) that can connect to a subdomain that runs a hadoken server. it has full push and ajax support (no jsonp or some such crap)
-
-***On the server*** You can run a socket.io push server independently from the rest of your app on a different subdomain. i consider this a best practice and it allows you to retrofit existing apps on your domain with cool new push features.
-
-this is pretty much the same as twitter's phoenix. twitter uses it for ajax requests from twitter.com to api.twitter.com. in this first rough draft i use it just for socket.io connections, but ajax is next in line.
-
-# How to run the example in dev and production mode
+WARNING: there may still be some custom-to-us parts in the code. Feel free to tinker.
 
-I'm drunk and tired so I'll make it real quick. The example assumes you have two hosts in `/etc/hosts` defined like this
-
-    127.0.0.1	localhost.com
-    127.0.0.2	push.localhost.com
-
-You can add the `127.0.0.2` ip to your loopback interface like this (on mac, probably similar-ish on linux) `sudo ifconfig lo0 alias 127.0.0.2` (the alias will disappear on reboot). Don't forget to `sudo dscacheutil -flushcache` to re-read the hosts file.
-
-Examples require 'coffee-script', 'connect' and 'socket.io' to be installed in npm. Install them into the hadoken directory, I'll make a package.json later.
-
-The example is in the example directory, cd there. To test out development mode (only one server running that serves both your app or whatever and the socket.io server), run `coffee server.coffee`. Point your browser to `http://localhost.com:8080` and watch the magic in the console.
+# What is this?
 
-To test out production mode, you'll have to start two servers. From the example directory run `coffee server.coffee production`. This will launch the webapp but it won't hook up socket.io. background the task and run `coffee push_server.coffee` in the same directory. this will start a socket.io server that runs on push.localhost.com:8080. Point your browser to `http://localhost.com:8080` again and you'll see push still working. booya.
+Hadoken makes your node.js REST and/or push (via socket.io) API available on subdomains and as soon as I get to it on other domains.
 
+Just create your server like you normally would, then call `hadoken.listen` on it with the appropriate options and suddenly you're serving an xd receiver iframe and a bunch of javascript from your server that just works.
 
-# Why? (aka FAQ)
+Currently there's a dependency on connect servers because I was lazy, so keep that in mind.
 
-Because I'm an eccentric idealist and I want as little crap as possible to interfere with or share a process/machine/datacenter with my webapp's push server. Maybe the push server and the rest of my app have different scaling requirements and I want to have to put them all on the same machines and behind the same load balancers. In fact, I may want to use a load balancer that doesn't speak websockets for most of my app. I also like to have a clean separation of concerns.
+Here's a really quick example (pardon my coffeescript):
 
-More pragmatically, suppose I have a bunch of existing web properties on all kinds of subdomains of mydomain.com. Now I add this shiny new service at api.mydomain.com. What is the easiest way of making that new service available to all my properties? Hadoken! Boom.
+***Server on api.example.com***
 
-Just to be clear: for vanilla websockets this is not even necessary since they can in fact connect to other sudomains. The problem is with the fallback methods like XHR that don't work on subdomains.
+    server = connect.createServer '/sayhi', (req, res, next) ->
+      res.end 'hi'
+
+    hadoken.listen
+      baseDomain: 'example.com'
+      server: server
+
+    server.listen 80
 
-# TODO
-
- * Make a proper example that's easier to run
-
- * Figure out npm v1.0 stuff
-
- * Improve hadoken API, the example app still feels a little funky
+***Client on cdn.example.com***
+
+    <script src="http://api.example.com/hadoken" />
+    <script>
+      hadoken.ajax({
+        url: 'http://api.example.com/sayhi',
+        success: function(){
+          alert('yea!')
+        }
+      });
+
+      // if you set enableSocket to true when calling hadoken.listen
+      // you can also get a handle on a socketio connection using
+      // hadoken.socket
+    </script>
 
- * Make hadoken server write configuration vars into parent frame
 
- * Remove dependency on connect, I was just lazy
+The client uses a patched version of the reqwest library but that may change soon
 
- * Buffer all socket.io-related function calls in window.hadoken in the parent until hadoken becomes functional
+# Why?
 
- * don't copy-paste socket.io client js (and find out why minified version failed)
+I initially wrote this to pull out a push server from our API server to separate concerns better. Then it occurred to me that this could be used to public API-ify random webservices and that's awesome. Like I said though, cross-domain is not implemented yet.
 
- * implement a less arbitrary loading and configuration pattern
-
- * Expose AJAX abstraction and make the whole thing independent from socket.io.
+At campfire labs using hadoken allows us to serve all functionality (push, api, static file serving) from one process in development and from three different processes in production. It's pretty sweer