Cosmopolite

Client/server publish/subscribe, presence and key/value storage for AppEngine

Cosmopolite Tutorial

AppEngine prerequisites

  1. Download and install the Python AppEngine SDK

Server-side setup

  1. Create an application in your SDK client
  2. Download cosmopolite via the links at left. Unpack it into a "cosmopolite" subdirectory of your local application
  3. Create an app.yaml file for your application.
  4. Add a cosmopolite include to your app.yaml file: 
    includes:
- cosmopolite
  5. Start the application in your SDK client

Test cosmopolite

  1. Access your local cosmopolite debug page (replace port if necessary): http://localhost:8080/cosmopolite/static/debug.html
  2. Subscribe to a subject testsubject
  3. Send a message to that subject; it should appear in the message list below

Create a test page

  1. Create a test.html page at the top level of your application: 
    <html>
  <head>
    <script src="/cosmopolite/static/cosmopolite.js" charset="UTF-8"></script>
  </head>
  <body>
    <script>
// Subsequent script examples go here
    </script>
  </body>
</html>
  2. Add a mapping to app.yaml: 
    handlers:
- url: /test.html
  static_files: test.html
  upload: test.html
  3. Have it create a cosmopolite instance and send a message to it: 
    var cosmo = new Cosmopolite();
cosmo.sendMessage('testsubject', 'test message');
  4. Keep the debug page (from above) up and subscribed (to testsubject) in one browser tab
  5. Load your test page
  6. The debug page should show the message from the test page
  7. You've written code that uses cosmopolite!

Time out for concepts

  1. Subject: a topic that clients that publish and subscribe to, e.g. "books"
  2. Message: a single chunk of data transmitted to a single subject, e.g. "I love books!"
  3. Pin: an ephemeral message that is deleted when the client that pinned it disconnects
  4. Instance: a single instantiation of Cosmopolite() in a browser (destroyed on page close)
  5. Client: a persistent identifier for a browser (consistent across browser restarts)
  6. Profile: a collection of clients that all speak as the same user (and so should appear the same to subscribers)

Subscribe to a subject

  1. Change your test script: 
    var callbacks = {
  onMessage: function(msg) {
    alert(msg['message']);
  },
};
var cosmo = new Cosmopolite(callbacks);
cosmo.subscribe('testsubject');
  2. Load (or re-load) the test page
  3. Use the debug interface to send a message to testsubject
  4. Your test page should generate an alert popup

Key/value store

  1. Cosmopolite can be used as a key/value store, with historical data and update notification
  2. When subscribing to a subject, you can request the most recent message for that subject
  3. Change your test script: 
    var cosmo = new Cosmopolite();
cosmo.subscribe('testsubject', 1).then(function() {
  var msg = cosmo.getLastMessage('testsubject');
  alert(msg['message']);
});
  4. Your test page should generate an alert popup showing the last message sent