A couple of new features include:

• Embedded Stomp broker via MorbidQ. Now you put stomp:// urls in the [listen] section of the configuration
• Reworked startup api for easier use with outside projects like WillowChat.
• Improvements to the IRC client (via js.io)
• Increased stability for Connection handling when the page is reloaded navigated away from then returned to
• Various small bug fixes
• See the commit logs and timeline

Obviously it makes sense to migrate to separate processes for a high-concurrency production deployment, but this method is perfect for developing applications and deploying small to medium instances.

The tutorial uses a different technique than the STOMP method I described. Dark Porter takes advantage of the fact that Django and Orbited are both written in Python, and puts everything in one process, including a custom threaded TCP server.

Dropped Connections

A web application can’t prevent most dropped connections. It can only handle them in the best manner possible. Dropped connections are a problem because unless there’s some notification mechanism, the browser won’t automatically try to reestablish the connection. Furthermore, the user will think that the application is operating in a connected state, and won’t realize that they are missing messages.

This hurts the functionality of the application, and also decreases the user’s confidence in the application, which has negative implications for how much they use it and whether they will use it for important tasks. Preventing disturbances in the user experience and increasing user trust are both very important goals. Orbited prevents lost messages by keeping a buffer of recently sent messages, but we still want to resume normal operations as possible.

Fixed Interval Reconnects

A common way to handle dropped connections is to have the browser reconnect every 30 seconds, regardless of whether the connection has dropped. Prior to 0.6.1 this is what Orbited did. This method caps the period of browser unawareness at 30 seconds + the browser timeout interval. ~30 seconds is a long time for the browser to be ignorant of the connection state. The interval can be decreased, but reconnects should be avoided for 2 reasons:

• The browser can’t receive messages while it’s reconnecting. The connection is usually fine, so most reconnects are actually making things worse for a short period of time.
• Each reconnect requires a full HTTP message to be sent and processed. This isn’t that bad for the client, but really adds up for the server, which is almost always the bottleneck for web applications. And some people are on dial-up or mobile connections.

Fixed interval reconnects aren’t horrible, and they’re used by live deployments. But there’s a much better way.

The Heartbeat Solution

Orbited 0.6.1 adds a feature called heartbeats, which provide better browser awareness at a lower overhead cost than fixed interval reconnects. A “heartbeat” is a tiny amount of data (~1 byte) sent from the server to the browser without separate HTTP headers (it’s sent in the context of the Comet connection HTTP headers), meaning the cost both of bandwidth and server processing is negligible.

If we send a heartbeat every 5 seconds, the maximum time the browser is unaware of the connection state drops from 30 seconds + the browser timeout interval (with fixed interval reconnects) to the heartbeat timeout, which defaults to 15 seconds (the timeout is longer than the interval to account for latency). And the browser only has to reconnect if the connection drops, instead of having to reconnect every 30 seconds no matter what. The timeout and the heartbeat interval can both be lowered if necessary.

Timeouts

Heartbeats also prevent browser and proxy timeouts. Browsers and proxies often close open connections after around 60 seconds of inactivity. The fixed interval reconnect avoids the connection being closed unceremoniously, but since heartbeats count as activity, they prevent the timeouts from even happening. The fewer reconnects the better.

Usage with Transports

Orbited provides two Comet transports: streaming and long polling. Streaming provides better performance and is the default/recommended option. Both transports work with heartbeats. IE and Opera can only read heartbeats when they’re used with a streaming connection, so a long polling connection can’t use them for dropped connection handling, but they’re still handy for avoiding timeouts. Streaming with heartbeats works with most firewalls, forward proxies, reverse proxies, and routers, but if a particular deployment of intermediaries does manage to thwart streaming, the server can fall back to long-polling.

What You Need to Do

Probably nothing! Orbited 0.6.1 and onward use streaming with heartbeats by default. If you want you can lower the heartbeat interval and timeout for even better browser awareness of dropped connections.

If you’re using a version of Orbited lower than 0.6.x, this is a great time to make the change, because 0.6.0 marked the change from alpha to beta, with the corresponding stabilization in API and core functionality. Remember to stop by the mailing list, IRC channel (#orbited on freenode or use the LiveDemo), and Trac system to participate in the development process and/or get help with Orbited.

Prior to 0.5, Orbited used a custom protocol (the Orbit protocol) for communication between it and the framework. Inside Orbited was a rudimentary message queue. This is the method used in the outdated CherryChat tutorial.

Use Existing Solutions

With 0.5, the team decided to switch to a standard and well-developed protocol: STOMP. Instead of trying to improve the message queue functionality, we decided to focus on TCPSocket and Comet. Using STOMP allows the use of advanced stand-alone message queue brokers like ActiveMQ and RabbitMQ. It also removes the need to write and update clients for the custom Orbit protocol, since there are actively maintained STOMP clients in many languages. These benefits are similar to the benefits of the biggest change in 0.5: TCPSocket, which lets you use existing protocols for communication to the browser.

The Super-Easy Way

ActiveMQ and RabbitMQ are fairly easy to install and use, but many people wanted something even easier and simpler for testing and basic deployments. Starting with 0.7, Orbited will feature a built-in basic STOMP message queue. The message queue has already been released as a Twisted-based daemon called Morbid. If you have setuptools installed, type easy_install morbid and then run orbited and morbid. Go into the Stomp demo and it should work! Once Orbited 0.7 is released you won’t even have to install Morbid.

The Benefits in Two Sentences

With the integrated STOMP message queue, you can use the same architecture as with pre-0.5 but with the added benefits of using a standard protocol. Using a stand-alone STOMP message queue broker gives you the benefits of the standard protocol plus the features and performance of advanced message queue brokers.

A CLA is a legal document, which means you should read it carefully. It basically gives the projects managed by the nonprofit a license to use your contributions (you retain copyright), and warrants that you have the right to give the projects that license. Most people do this implicitly when they submit code to an open source project, but a CLA puts it in writing and hopefully makes everyone aware of their responsibilities e.g. not submitting code they didn’t write, or submitting code they wrote on their employer’s time/property without their employer’s permission to license the code to an open source project. If you are doing or have done work for any of nonprofit’s software projects on your employer’s time/property, you should:

1. Talk to your boss and make sure it’s fine that you’re working on code that will be licensed to an open source project.
2. Have them sign a corporate CLA with the nonprofit which formalizes this agreement.

As a general note, anything you create on your employer’s time/property may belong to your employer. If you want to have any rights to these creations, you should have a written contract with your employer stating the the specific terms of the agreement. You should also be careful when writing and/or contributing code that’s similar to proprietary code owned by your employer. I’ll get back on topic now, as intellectual property is a very complex issue, but it’s a good idea to read a survey such as the Software Freedom Law Center’s primer.

The Benefits of CLA’s

The main purpose of CLA’s is protecting users of the software from IP lawsuits. They also have a number of other benefits. CLA’s make it clear that contributors are under no obligation to provide support for their contribution. They make people more aware of their rights when writing code on their employer’s time/property, as mentioned above. The project itself is less likely to be attacked via lawsuits. And in general it’s good to make issues clear and explicit. CLA’s are used by many open source projects including all the projects managed by the Apache Foundation.

About the CLA

The CLA is between contributors and the project, which makes it distinct from an end user license e.g. the MIT license used by Orbited. We’re using a CLA that is very similar to the one used by the Apache Foundation. The CLA’s are available on the Development page. You should email a scanned copy of the signed agreement to orbitedprojectREMOVETHISTEXT@gmail.com. A single CLA covers Orbited as well as all the other projects managed by the nonprofit.

• Sockets in the Browser
• Independence Day: HTML5 WebSocket Liberates Comet From Hacks

Michael and Jacob will be around after the talk to chat and answer questions.

Update: We’ve scheduled a Comet BoF for Thursday 8p-9p in room E146. Stop by to chat about anything related to Comet.

This means you stop thinking of the server as something that answers questions from the end-user, and start viewing each endpoint as an equal participant. Either side can send or receive messages whenever they want. This is a vastly more flexible, powerful programming model than the request/response paradigm that is shoved down our throats. This type of server is extremely simple to implement, requires no framework or knowledge of any protocol, and is, of course, completely platform- and language- agnostic.

What are the implications of this new web programming model? For starters, it means solving formerly complex problems in minutes instead of months (see Michael’s discussion of gmail), with minimal code and zero “web programming.” Because let’s face it: “web programming” just means trying to write network code on top of a protocol designed for static document transmission. This is something you can’t even attempt without a steaming pile of hacks that produce bloated architecture with serious usability issues.

So now that we’re in this brand new retro socket world, how do we go about making something?

use existing servers
I try not to dwell on it, but there was life before Al Gore invented the world wide web — it just didn’t have any meaning. There was life because there were UNIX networks inhabited by bearded sages who use terminals for everything to this day. They wrote roughly 3.5 bagillion protocols, each with literally 100 million server implementations. Take your pick. Want a chat app? Download an IRC server. How about an in-browser MMORPG with magical node clustering and load-balancing? Download ActiveMQ (or any of 10 million other Stomp brokers), fire up Orbited’s Stomp client and you’re set.

The fact is, virtually all network applications require uninhibited bidirectional communication. This means that the second you get a browser socket, you can use any code anyone has ever written, including Code Hunter, Morse Code, and Mountain Dew Code Red; and you can interact with any type of server the same way you would using telnet. You can launch a massive application without writing a line of server code. Code, code, code.

roll your own
But no, you’re a unique snowflake, and you absolutely must write your own. That’s fine. It’s easy. Just get yourself a socket (there’s one in every language, and they’re all the same), wait for a connection, and talk to your client with socket.send and socket.recv. I’m telling you, you can write this type of server in about 5 lines, and develop it into a really fun game in 50 to 100 more.

Now, I realize that the idea of writing all your games and gizmos on top of a raw socket might make some people out there uncomfortable and a little sweaty in key areas. Naturally, no reader of this fine blog belongs to that bunch. Nevertheless, it should be noted that there are alternatives. There are seriously tons of network libraries out there. If you want a super-performant app I’d have to recommend an asynchronous contender, such as libevent, Twisted, or Grizzly. I usually use dez.

Generally, this type of application will have a listener of some kind that just sits there waiting for incoming connections. Whenever someone connects, the listener passes responsibility on to an object that reads and writes. What could be simpler?

Since this is totally custom software, we’re going to need a protocol for the connection object to speak to the Javascript client. For anything with more than a couple command types it usually makes sense to write a JSON- or XML- based protocol, because these methods are flexible and easy to parse, and because whatever language you choose, someone’s already done the dirty work for you.

the easy way out
Often, however, one or both endpoints won’t need to send anything very complex. Maybe you’re building a stock-ticker that updates a value every second, or a live message board. For these cases, you can safely use a delimiter. A delimiter is a string of characters that you know won’t ever appear elsewhere in a protocol “conversation.” Thus, the delimiter can confidently signify the end of a protocol “sentence.” Example delimiters include line break, tab, “::1337::”, and the null byte. Once you’ve chosen a delimiter, you can parse incoming messages with a very simple Javascript function.

var separate_events = function() {
    var sep = buff.indexOf(DELIM);
    if (sep == -1) {
        return;
    }
    parse_event(eval(buff.slice(0,sep)));
    buff = buff.slice(sep+DELIM.length);
    separate_events();
}

This function takes a buffer string (buff) and looks for your delimiter (DELIM). If it can’t find your delimiter, the function returns. Otherwise, it knows that the first chunk of the buffer is a complete sentence, because it ends with your delimiter and starts at index 0, where the previous delimiter left off the last time this function was called. It evals this string (buff from index 0 to DELIM’s index) and passes the result to a protocol interpreter function. At this point it shifts the buffer string forward and recurses. Once you have this function in place, you just need to feed it by appending any incoming messages to the end of the buffer.

conn.onread = read;

and

var read = function(incoming_text) {
    buff += incoming_text;
    separate_events();
}

Now you have individual messages being sent to a function called parse_event.

var parse_event = function(data) {
    alert("server says: "+data);
}

And tada! You have a basic client. I have to emphasize that it doesn’t really matter what your protocol looks like. If the application calls for it, you can just send individual letters back and forth. Alternatively, you can use XML, or have a full-fledged HTTP-like system with headers and version-variable behavior and functionality. It’s likely that your application will speak with completely different accents in different directions. Look! Tutorials: Twisted, libevent, Grizzly. Say hello to your mother for me. :-*

I must give David credit for being so forward thinking, being the first to release a browser socket. With the Orbited project, we had to undergo a lengthy process to arrive at the same conclusion he had already found. We realized that we wanted reliable delivery with message ordering guarantees, so we created a protocol that we called Comet Session Protocol (CSP). Next, we started working on an API for CSP, and decided that we might as well use HTML5’s then-named TCPConnection API. We worked with that for a while, and then realized that we weren’t actually honoring the API because we didn’t implement the server-side protocol (TCPConnection then, like WebSocket now, had an extra handshake for security, and framing.) So we went and implemented that, only to realize that we didn’t really need the TCPConnection security provided by the handshake — Orbited could provide it instead via access control! So we created a TCPSocket API which simulates a raw socket in the browser.

I must say — I am extremely impressed with David’s clear understanding of the problem domain. It took the entire Orbited core developer team a few months to follow this line of reasoning and end up where we are now.

Also of note, JP Calderone put together an alternative implementaiton using Twisted Athena, and I imagine more will soon follow. This is great news. Having multiple browser socket implementations is exactly what we need. This way, users can experiment with the various servers and choose whichever works best for them. It leaves us free to move up the stack — That is, we can begin implementing protocols on top of our basic API. We should make sure to all choose the same basic API so that any protocol implementation can actually be used with any server.

For now, the Orbited project will continue protocol work with the TCPSocket interface. I think its important to keep as close to the WebSocket API as possible. Of course, I’m open to discussion from anyone interested in joining forces or providing some advice.