JeeLabs: Ground control to… browser

After yesterday’s RPC example, which makes the server an easy-to-use service in client code, let’s see how to do things in the other direction.

I should note that there is usually much less reason to do this, since at any point in time there can be zero, one, or occasionally more clients connected to the server in the first place. Still, it could be useful for a server to collect client status info, or to periodically save some state. The benefit of server-initiated requests being that it turns authentication around, assuming we trust the server.

Ok, so here’s some silly code on the client which I’d like to be able to call from the server:

ng = angular.module 'myApp'

ng.config ($stateProvider, navbarProvider, primus) ->
  $stateProvider.state 'view1',
    url: '/'
    templateUrl: 'view1/view.html'
    controller: 'View1Ctrl'
  navbarProvider.add '/', 'View1', 11
  
  primus.client.view1_twice = (x) ->
    2 * x

ng.controller 'View1Ctrl', ->

This is the “View 1″ module, similar to the Admin module, exposing code for server use:

  primus.client.view1_twice = (x) ->
    2 * x

On the server side, the first thing to note is that we can’t just call this at any point in time. It’s only available when a client is connected. In fact, if more than one client is connected, then there will be multiple instances of this code. Here is app/view1/host.coffee:

module.exports = (app, plugin) ->
  app.on 'running', (primus) ->
    primus.on 'connection', (spark) ->
      
      spark.client('view1_twice', 123).then (res) ->
        console.log 'double', res

The output on the server console, whenever a client connects, is – rather unsurprisingly:

    double 246

What’s more interesting here, is the logic of that server-side code:

• the app/view1/host.coffee exports one function, accepting two args
• when loaded on startup, it will be called with the app and Primus plugin object
• we’re in setup mode at this point, so this is a good time to define event handlers
• the app.on 'running' handler gets called when all server setup is complete
• now we can set up a handler to capture all new client connections
• when such a connection comes in, Primus will hand us a “spark” to talk to
• a spark is essentially a WebSocket session, it supports a few calls and streaming
• now we can call the ‘view1_twice’ code on the client via RPC
• this creates and returns a promise, since the RPC will take a little bit of time
• we set it up so that when the promise is fulfilled, console.log ... gets called

And that’s it. As with yesterday’s setup, all the communication and handling of asynchronous callbacks is taken care of behind the scenes.

There is some asymmetry in naming conventions and the uses of promises, but here’s the summary:

• to define a function ‘foo’ on the host, define it as app.host.foo = …
• to call that function on the client, use host ‘foo’, …
• the result is an Angular promise, use “.then …” to pick it up if needed
• to define a function ‘bar’ on the client, define it as primus.client = …
• to call that function from the server, use spark.client ‘bar’, …
• the result is a q promise, use “.then …” to pick it up

Ok, so there are some slight differences between the two promise API’s. But the main benefit of this all is that the passing of time and networking involved is completely abstracted away. Maybe I’ll be able to unify this further, some day.