Cloudshift - A haXe Stack for Node.js

See cloudshift.cl for full documentation.

Cloudshift is written and maintained by Ritchie Turner ([email protected]) and is currently under heavy development; the apis are subject to change.

Core Module

Cloudshift provides a consistent set of abstractions on client and server for dealing with common problems;

• Asynchronous haXe remoting for inter tier and sub-process communication
• Outcome<A,B> (a Future<Either<A,B>>) as the means for dealing with async callback hell and error handling with helper functions provided as Mixins.
• Parts are components which have an asynchronous new() in the start() method - start() and an optional asynchronous stop(). Parts are also Observable.
• Mixins, mostly the Stax prelude extensions with extensions for Parts and Outcomes.
• Observables - Typical observer functionality.

Http Module

Simplest example …

Http.server()
.root("/dir/to/serve")
.start({host:"localhost",port:8080});

and/or provide multiple handlers per url, e.g.

Http.server().handler(~/^\/remotes/,rem.httpHandler)   

For haXers a limited Neko api is also supported on handler req/resp objects to get you going.

Channel Module

Publish/subscribe with session management, channel security. Currently a Push implementation (web socket conduit will be added).

Http.server().root("www").start({host:"localhost",port:8082})
  .outcome(function(http) {
      Session.manager().start(http)
        .outcome(function(sess:SessionMgr) {
            sess.authorize(sessAuth);
            Channel.server()
              .addChannelAuth(channelAuth)
              .start(sess).outcome(startRooms);
          });
    });

Once you have your client or server, you may get a channel and pub/sub

function startRooms(channelServer:ChannelServer) {
channelServer.channel("/chat/room").outcome(function(room) {
    room.pub("blah");
    room.sub(function(msg) {
       
    });
});

Data Module

There is a database component with, so far, one driver, Sqlite3. The api is asynchronous and NoSQL where objects are stored in “buckets”. JSON is the default storage format but you may add serializers per bucket if you prefer to store haXe serialized objects or anything else.

Data provides a general indexing facility which utilises the underlying sqlite indexes. Objects are relatable and queryable across buckets.

The Sqlite driver is a popular C++ module for Node.js supported by many of the leading names in the Node.js community. It’s asynchronous and embedded in the node.js instance.

So, each Cloudshift instance has it’s own database, this can be easily augmented so that each instance running talks to a central Cloudshift instance just running data services. Cloudshift provides a remote api compatible driver for this purpose.

Data.store(REMOTESQLITE("http://localhost:8082/data")).outcome(function(store) {
store.bucket("woot").outcome(function(woot) {
   
    woot.where('name="lore"').outcome(function(recs) {
        trace(recs.stringify());
      });
    
    woot.insert({email:"[email protected]",name:"lore",passwd:"and why not"})
      .outcome(function(u) {
          trace("lore's id = "+Data.oid(u));
      });
  });

Data also supplies a persistent hash.

The main point here is to think of the Node.js/Sqlite3 combination as a database server in it’s own right

Worker Module

Extend Worker and create seamless sub process workers using the haXe remoting protocol.

Sys Module

File I/O, Process services wrapped in Outcomes as appropriate for this kind of usage:

Sys.writeFile("woot","hi there")
  .oflatMap(function(file) {
        return file.stat();
    })
  .omap(function(stat) {
      return stat.path;
    })
  .oflatMap(function(path) {
      return path.rename("niceone");
    })
  .outcome(function(newFileName) {
      trace("cool "+newFileName);
          
      var p = Sys.events();
    
      p.observe(function(o) {
          switch(o) {
          case ProcessUncaughtException(ex):
            trace("uuncauthg exp:"+ex);
          default:
          }
        });

      trace(Sys.argv());
      trace(Sys.title());
      trace("osuptime:"+Sys.osUptime()+", uptime:"+Sys.uptime());
      });

Installation and Dependencies

install node.js for your platform

• npm install formidable
• npm install sqlite3
• haxelib install nodejs
• haxelib install cloudshift

Note, the cloudshift haxelib does not include the nodejs dependency by default, as the cloudshift lib is used on both client and server having the -D nodejs defined automatically on the client is an unwanted side effect. So be sure to install nodejs bindings manually.

• Formidable is the node.js POST multipart handler. (https://github.com/felixge/node-formidable)
• Sqlite3 - not be available on Windows (https://github.com/developmentseed/node-sqlite3)
• nodejs (https://github.com/cloudshift/hx-node)