ws4py is still under development and may underlie considerable structural changes in the future. But what we can see so far is a cleanly written generic pure-Python WebSocket protocol implementation that can be used for servers as well as for clients. I would like to point out that — among others — a gevent-driven server is already included. I have not seen or done any benchmarks about it, but theoretically this server should be very well performing. Overall, ws4py looks very promising.

In my playground setups, I’ve replaced gevent-websocket by ws4py. This way, I successfully ran some WebSocket communication tests between the clients implemented in Firefox 7, Chrome 14, Chrome 15 and the ws4py/gevent-based server — making use of the HyBI WebSocket protocol version 10. Together with a recent version of the perfect web-socket-js, the communication also works with older browsers like Firefox 3.

Standard conformance and performance of ws4py is tested via the Autobahn WebSocket test suite. To have a testsuite like that is extremely important in order to push the development of high-quality WebSocket libraries. You should definitely look at it if you are a WebSocket client/server developer yourself.

Another thing I would like to show to you is the table at http://en.wikipedia.org/wiki/User:Oberstet/Comparison_of_WebSocket_implementations. If maintained properly, this will always be a very good reference to get an overview about WebSocket implementations on different platforms.

In this blog post, I present a very simple “echo application” where the user sends a message from his browser to the server — which in turn sends this message back to the client. Simple so far, but the main focus while realizing this is on selecting the right tools for the task, as there is already a lot of stuff out there — some very good, undocumented and hidden things, some totally overloaded things, and some bad things. I tried to fulfill the following conditions:

• Make use of a “Flashbridge” to realize a fallback when WebSockets are not available in a browser (which is true for Firefox at the moment)
• use Python on the server side
• use the best / most solid tools available
• at the same time, use the simplest tools available that do not bring along loads of stuff that you do not need for simple applications or if you want to desing your own communication protocol anyway.

Tools for the client side

First thing, the client running in the browser has to be implemented in JavaScript, of course. I do not like JavaScript, but this is the language of the browsers (is there a chance to revolutionize this to Python syntax?). So, when you search the web you will at first find Socket.IO and jWebSocket. Socket.IO is consisting of the client “Socket.IO” and the server “Socket.IO-node” — designed to be used together. Yes, it is great — it seems mature, it already provides a lot of different protocols on top of WebSockets and it provides loads of fallback mechanisms if there are no WebSockets available on the client side. There even is a Python implementation of the server side. But my feeling was: Nope. I have no experience so far with WebSockets, so I would like to start implementing a basic core. I don’t want to use any communication protocol so far. Just sending messages as designed by the specification of WebSockets. Furthermore, I only want Flash fallback as an equivalently fast replacement, no slow backup techniques like xhr-multipart, xhr-polling, and jsonp-polling. Socket.IO overwhelms with a lot of functionality and few of documentation — making it difficult for newcomers to grasp the essentials.

A lot of above also applies for jWebSocket, so they have many things in common why I did not want to use them. And as it turned out while browsing through their sources, they have one very special thing in common:

web-socket-js

Socket.IO as well as jWebSocket both base their core WebSocket-Flash-switch on a very neat and small JavaScript library called web-socket-js written by Hiroshi Ichikawa. You can check this yourself by looking at Socket.IO’s repository and jWebSocket’s repository. If required, web-socket-js replaces the standard JavaScript new WebSocket constructor by its own implementation. This does the trick:

(function() {
 
  if (window.WebSocket) return;
 [...]
}

If WebSockets are supported by the browser natively, then they are used natively and web-socket-js does not do anything more than return;. If the browser lacks support, a Flash plugin Hiroshi wrote is loaded, providing the same API as the original JavaScript WebSocket. This API is implemented in the [...] of the code snippet above.

This is the way I want to start learning WebSockets: using the original API and with a lot of browser support. Decision made: on the client side, I use web-socket-js.

Tools for the server side

Answer upfront this time: gevent in combination with gevent-websocket. Gevent is a nicely performing networking library for Python, based on the brilliant idea of greenlets. It allows you to write extremely simple server code. Gevent-websocket is just a very small piece of code on top of this, basically saving you from implementing the WebSocket handshake yourself.

The code

Let’s start with websocket_echoserver.py:

from geventwebsocket.handler import WebSocketHandler
from gevent import pywsgi
import gevent
 
 
def handle_echo_client(ws):
    while True:
        msg = ws.wait()
        if msg == "quit":
            ws.close_connection()
            break
        ws.send(msg)
 
 
def app(environ, start_response):
    if environ['PATH_INFO'] == "/echo":
        handle_echo_client(environ['wsgi.websocket'])
    else:
        print "404, PATH_INFO: %s" %  environ["PATH_INFO"]
        start_response("404 Not Found", [])
        return []
 
 
server = pywsgi.WSGIServer(('', 8087), app, handler_class=WebSocketHandler)
server.serve_forever()

It listens on localhost:8087 for incoming connections. WebSocket connections are accepted and handled. If the requested resource is /echo, the greenlet handle_echo_client() deals with the client. I think it is obvious what this function does. To reach this server, the client has to connect to ws://yourhost:8087/echo.

Now the client side. Call this HTML code in your browser (make sure to set the paths to the JavaScript sources and SWF file correctly and keep everything under the same domain):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/transitional.dtd">
<html>
<head>
<title>websocket client: send/receive test</title>
<script type="text/javascript" src=".........../web-socket-js/swfobject.js"></script>
<script type="text/javascript" src=".........../web-socket-js/web_socket.js"></script>
<script type="text/javascript">
WEB_SOCKET_SWF_LOCATION = "............/web-socket-js/WebSocketMain.swf";
function log(msg) {
    var d = new Date();
    var hour = d.getHours();
    var min = d.getMinutes();
    var sec = d.getSeconds();
    var msec = d.getMilliseconds();
    var time = hour + ":" + min + ":" + sec + ":" + msec
    document.getElementById('foo').innerHTML += time + ": " + msg + "<br />";
    }
 
function ws_init(url) {
    log("connecting to " + url + "...")
    ws = new WebSocket(url);
    ws.onopen = function() {
        log("connection established.");
        };
    ws.onmessage = function(e) {
        log("message received: '" + e.data + "'");
        };
    ws.onclose = function() {
        log("connection closed.");
        };
    }
 
function ws_send(msg) {
    log("send: " + msg);
    ws.send(msg);
    }
 
function ws_close() {
    log("closing connection..");
    ws.close();
    }
</script>
</head>
<body>
<form name="input_form">
<table>
<tr>
    <td>host/resource:</td>
    <td><input type="text" name="host" size="50" value="ws://host:port/resource"></td>
    <td><input type="button" value="connect" onclick="ws_init(document.input_form.host.value)"></td>
    <td><input type="button" value="disconnect" onclick="ws_close()"></td>
</tr>
<tr>
    <td>msg:</td>
    <td><input type="text" name="msg" size="50"></td>
    <td><input type="button" value="send" onclick="ws_send(document.input_form.msg.value)"></td>
</tr>
</table>
</form>
<div id="foo"> </div>
</body>
</html>

What is used here is the standard JavaScript WebSocket API. For me, this HTML renders as:

Now… maybe you opened this in Chrome. Then, WebSocket support is natively included and activated. In Firefox, it is disabled. There the Flashbridge would come into play. But Flash does not just send and receive data to and from anywhere. It at first asks the host who delivered the SWF file with whom it is allowed to exchange data: it expects to get a so-called socket policy file from the server, after asking him for this on port 843. Yeah, just accept this — it is not a bad idea that the internet communication of Flash plugins is restricted. Anyway, you have to set up a server listening on port 843 to provide this policy. I have made a blog post for setting up a Flash socket policy server in Python based on gevent. I just assume that you have set up such a server. Then, our HTML code from above works (at least for me) under Firefox 4+, Chrome 6+ and Internet Explorer 9. Enter your echo server’s details (ws://yourhost:8087/echo) and play around with it. For me, it looks like that:

Isn’t that great? It works. The latency times between send and receive are pretty low (at least for such small words to send): they are comparable with the ping latencies I measured against the same server. The Flashbridge transparantly does its job in Firefox and Internet Explorer and introduces around 5 ms more latency.

Conclusion

The tools used for this test (gevent, gevent-websocket and web-socket-js) are solid, perform very good and are very simple to use. The code executed in the browser uses the standard WebSocket API. But, due to web-socket-js and its nice Flashbridge, it works in all browsers supporting Flash. gevent-websocket and web-socket-js do not provide more functionality than simple message passing over WebSockets, which was desired.

If you just want to use/see the results of the investigation, scroll down to the ideal solutions. Otherwise, you should make yourself briefly familiar with eofbit, failbit, badbit of the ios class.

All the code shown in this post can be downloaded.

What we want and have to do: obeying the two rules of ifstream iteration (ideal solution snippets)

We want to iteratively process the lines read from a file by means of an ifstream (reasons here). Therefore, we try to open a file by invoking ifstream s ("file"). To try to get a line from the file, we use std::getline(s, line), where line is a std::string to store the data to. In a loop we want to process the data read from the file, line by line, via process(line). Of course, we only want to call process(line), if the last getline() stored meaningful data in line. We also want to get the last line of the file, even if it is not terminated by a newline character.

After the investigation described below, I am pretty sure that the simplest rock-solid language construct for this task is:

string line;
ifstream f ("file");
while(getline(f, line)) {
    process(&line);
    }

This is so simple and at the same time good, because it is the shortest approach following the two basic rules we must follow when using std::getline() (or any other IO operation):

• Before processing data obtained from the stream, check for errors reported by getline() (or other IO operations).

• If getline() (or …) has set failbit or badbit, do not process the data. eofbit is not required to be checked in the loop and does not necessarily have to prevent data processing.

The origin of these rules will become clearer while reading the rest of the article.

Only two rules, to follow — isn’t that easy? Anyway, this often is not done, as you can infer from the links in the introduction. In fact, not following these rules lead to the bug in POV-Ray also mentioned in the introduction.

How does the simple code snippet above follow these rules? The loop, in fact, at first tries to obtain data from the stream via IO operation getline(). It is totally okay to try this even on a bad/empty/non-existing file, because it just tries and afterwards sets the stream’s error bits correctly, as defined here. After getline(), failbit and badbit are checked via the ifstream’s bool operator (this works because getline() returns the stream object). Only if none of these bits are set you can be sure that there is data in line. In this case the loop body is evaluated. It processes the data obtained from the stream. Then, it is tried to read the next line… and so on. The point is that for each iteration the chronological order of IO operation, error check, and data processing is correct. If you wonder why we do not have to check the eofbit within the loop: this will be answered during the discussion below.

Now, what happens if the file is empty? Or if it does not even exist? If it is a directory? If we are not allowed to access it? The code snippet above can deal with all types of errors transparently. That is very good so far. But what to do if we want to additionally get some meaningful error messages? This is the best we can do:

string line;
ifstream f ("file");
if (!f.is_open())
    perror("error while opening file");
while(getline(f, line)) {
    process(&line);
    }
if (f.bad())
    perror("error while reading file");

Why? Discussed in the next part.

How to catch errors specifically? Testing ifstream’s behavior

Let me start with

Two important things to know:

• Consider a call to std::getline() detecting the end of file. It then sets eofbit. But: “Notice that some eofbit cases will also set failbit.” (reference). This will be very important and we will figure out in which cases exactly we have either only eofbit or both, eofbit and failbit set.

• perror() evaluates the current setting of errno and prints a meaningful error message. errno is a global error variable which is set by low-level functions of your current operating system. This errno setting is sticky: it stays until the next error is happening, overwriting the state of the last error. Therefore, perror() must only be called in a context that for sure has updated errno right before. Otherwise, the printed error message may not make any sense at all in the current context.

As you already can imagine, for providing meaningful error messages, it is required to understand when exactly the eof, fail and badbit are set. Also, one has to know when exactly it is safe to call perror() in the context of stream methods. Unfortunately, at this point we enter system-dependecy and the documentations are bad. Hence, I implemented a test to see how my test system behaves, which is a 2.6.27 Linux. I will provide all source files and it will be very easy for you to reproduce this test on your system.

The test:

The test can be summarized as follows:
Consider ifstream s ("file"). It checks the state of

• s.is_open()
• s.fail() (same as !s: check for failbit and badbit)
• s.bad() (check for only badbit)
• s.eof() (check for only eofbit)
• errno (evaluated via perror())

while opening/reading

• a non-existent file
• an empty file
• an existing file with content
• an existing file with the last line not ended by a newline character (can be considered as invalid file format, since lines are mostly considered to be newline-terminated, not newline-separated).
• a file with content that is opened by another process for reading
• a file with content that is opened by another process for writing
• a file that the test program has no access to
• a directory

Basically, the test evaluates the named quantities at all interesting points and especially after calls to std::getline().

Technically, the test consists of:

• The C++ source of a test program with a lot of debug output expecting an input filename as first commandline argument.

• A shellscript that is compiling the C++ source code of the test program and setting up the test files for the test. It then runs the test program for all different input filenames.

This is the source of the shellscript readfile_tests.sh:

#!/bin/bash
 
COMPILATION_SOURCE=$1
NE_FILE="na"
EMPTY_FILE="empty_file"
ONE_LINE_FILE="one_line_file"
INVALID_LINE_FILE="invalid_line_file"
FILE_READ="file_read"
FILE_WRITTEN="file_written"
FILE_DENIED="/root/.bashrc"
DIR="dir"
 
# compile test program, resulting in a.out executable
g++ $COMPILATION_SOURCE
 
# create test files / directories and put them in the desired state
touch $EMPTY_FILE
if [[ ! -d $DIR ]]; then
    mkdir $DIR
fi
echo "rofl" > $ONE_LINE_FILE
echo -ne "validline\ninvalidline" > $INVALID_LINE_FILE
echo "i am opened to read from" > $FILE_READ
python -c 'import time; f = open("'$FILE_READ'"); time.sleep(4)' &
echo "i am opened to write to" > $FILE_WRITTEN
python -c 'import time; f = open("'$FILE_WRITTEN'", "a"); time.sleep(4)' &
 
# execute test cases
echo "******** testing on non-existent file.."
./a.out $NE_FILE
echo
echo "******** testing on empty file.."
./a.out $EMPTY_FILE
echo
echo "******** testing on valid file with one line content"
./a.out $ONE_LINE_FILE
echo
echo "******** testing on a file with one valid and one invalid line"
./a.out $INVALID_LINE_FILE
echo
echo "******** testing on a file that is read by another process"
./a.out $FILE_READ
echo
echo "******** testing on a file that is written to by another process"
./a.out $FILE_WRITTEN
echo
echo "******** testing on a /root/.bashrc (access should be denied)"
./a.out $FILE_DENIED
echo
echo "******** testing on a directory"
./a.out $DIR

This is the source of the C++ program readfile_debug.cpp:

#include <iostream>
#include <fstream>
#include <string>
using namespace std;
 
 
int check_error_bits(ifstream* f) {
    int stop = 0;
    if (f->eof()) {
        perror("stream eofbit. error state");
        // EOF after std::getline() is not the criterion to stop processing
        // data: In case there is data between the last delimiter and EOF,
        // getline() extracts it and sets the eofbit.
        stop = 0;
        }
    if (f->fail()) {
        perror("stream failbit (or badbit). error state");
        stop = 1;
        }
    if (f->bad()) {
        perror("stream badbit. error state");
        stop = 1;
        }
    return stop;
    }
 
 
int main(int argc, char* argv[]) {
    string line;
    int getlinecount = 1;
    if(argc != 2) {
        cerr << "provide one argument" << endl;
        return 1;
        }
    cout << "* trying to open and read: " << argv[1] << endl;
    ifstream f (argv[1]);
    perror("error state after ifstream constructor");
    if (!f.is_open())
        perror("is_open() returned false. error state");
    else
        cout << "is_open() returned true." << endl;
    cout << "* checking error bits once before first getline" << endl;
    check_error_bits(&f);
    while(1) {
        cout << "* perform getline() # " << getlinecount << endl;
        getline(f, line);
        cout << "* checking error bits after getline" << endl;
        if (check_error_bits(&f)) {
            cout << "* skip operation on data, break loop" << endl;
            break;
            }
        // This is the actual operation on the data obtained and we want to
        // protect it from errors during the last IO operation on the stream
        cout << "data line " << getlinecount << ": " << line << endl;
        getlinecount++;
        }
    f.close();
    return 0;
    }

Let’s run it:

$ ./readfile_tests.sh readfile_debug.cpp

The output:

******** testing on non-existent file..
* trying to open and read: na
error state after ifstream constructor: No such file or directory
is_open() returned false. error state: No such file or directory
* checking error bits once before first getline
stream failbit (or badbit). error state: No such file or directory
* perform getline() # 1
* checking error bits after getline
stream failbit (or badbit). error state: No such file or directory
* skip operation on data, break loop
 
******** testing on empty file..
* trying to open and read: empty_file
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
stream eofbit. error state: Success
stream failbit (or badbit). error state: Success
* skip operation on data, break loop
 
******** testing on valid file with one line content
* trying to open and read: one_line_file
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
data line 1: rofl
* perform getline() # 2
* checking error bits after getline
stream eofbit. error state: Success
stream failbit (or badbit). error state: Success
* skip operation on data, break loop
 
******** testing on a file with one valid and one invalid line
* trying to open and read: invalid_line_file
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
data line 1: validline
* perform getline() # 2
* checking error bits after getline
stream eofbit. error state: Success
data line 2: invalidline
* perform getline() # 3
* checking error bits after getline
stream eofbit. error state: Success
stream failbit (or badbit). error state: Success
* skip operation on data, break loop
 
******** testing on a file that is read by another process
* trying to open and read: file_read
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
data line 1: i am opened to read from
* perform getline() # 2
* checking error bits after getline
stream eofbit. error state: Success
stream failbit (or badbit). error state: Success
* skip operation on data, break loop
 
******** testing on a file that is written to by another process
* trying to open and read: file_written
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
data line 1: i am opened to write to
* perform getline() # 2
* checking error bits after getline
stream eofbit. error state: Success
stream failbit (or badbit). error state: Success
* skip operation on data, break loop
 
******** testing on a /root/.bashrc (access should be denied)
* trying to open and read: /root/.bashrc
error state after ifstream constructor: Permission denied
is_open() returned false. error state: Permission denied
* checking error bits once before first getline
stream failbit (or badbit). error state: Permission denied
* perform getline() # 1
* checking error bits after getline
stream failbit (or badbit). error state: Permission denied
* skip operation on data, break loop
 
******** testing on a directory
* trying to open and read: dir
error state after ifstream constructor: Success
is_open() returned true.
* checking error bits once before first getline
* perform getline() # 1
* checking error bits after getline
stream failbit (or badbit). error state: Is a directory
stream badbit. error state: Is a directory
* skip operation on data, break loop

The test results (important things to know 2):

There are many things to learn from this output. The following conclusions are only a subset. All this makes makes a lot of sense:

• The ifstream s ("file") constructor sets errno in case of a non existing file.

• is_open() does not set errno.

• is_open() does not catch the case when trying to open a directory.

• is_open() only catches the non-existing-file-case.

-> is_open() after ifstream constructor in combination with perror() works, but only for catching this one case: non existing file.

• getline() does only change errno in case of trying to read from a directory. In all other test cases it does not change errno.

• In almost any case, the eofbit hast been set at the same time as the failbit (which may happen as stated above). A closer look reveals that the failbit is only set by getline() if it did not manage to extract any data at all. The eofbit on the other hand means that getline() reached EOF while searching the next line delimiter: If there is data between the last delimiter and EOF, getline() extracts this data and sets eofbit.

• The badbit was only set for the directory case.

-> !s or s.fail() (equivalent, both are sensitive to badbit and failbit), must not be used in combination with perror(), because it may print error messages which are wrong in the current context.

-> Only a badbit check and therefore s.bad() seems to be safe to use together with perror().

-> In order to process residual data between the last line delimiter and EOF, a positive eofbit must not prevent data processing.

Ideal solutions

With the knowledge from above, ideal code solutions in form of ready-to-compile-examples can be proposed for two cases:

• one, in which error messages are not important

• one, in which we do the best we can to extract error messages

Ideal solution including meaningful error messages

Basically, the result from the above’s test is that with C++’s standard means there is not so much we can do to catch specific errors. The following source of readfile_stable_errors.cpp seems to be the best:

#include <iostream>
#include <fstream>
#include <string>
using namespace std;
 
 
void process(string* line) {
    cout << "line read: " << *line << endl;
    }
 
 
int main(int argc, char* argv[]) {
    string line;
    if(argc != 2) {
        cerr << "provide one argument" << endl;
        return 1;
        }
    string filename(argv[1]);
    cout << "* trying to open and read: " << filename << endl;
    ifstream f (argv[1]);
    // After this opening attempt, we can safely use perror() in case 
    // f.is_open() returns false.
    if (!f.is_open())
        perror(("error while opening file " + filename).c_str());
    // Now read the file via std::getline, while trying to provide as
    // meaningful error messages as possible. Rules obeyed:
    //   - first the IO operation, then error check, then data processing
    //   - failbit and badbit prevent data processing, eofbit does not
    while(getline(f, line)) {
        process(&line);
        }
    // Only in case of the badbit, we can assume that some lower
    // level system API function has set errno. Then, perror() can be used.
    if (f.bad())
        perror(("error while reading file " + filename).c_str());
    f.close();
    return 0;
    }

Of course this can be run against the test shellscript from above:

./readfile_tests.sh readfile_stable_errors.cpp

The output:

******** testing on non-existent file..
* trying to open and read: na
error while opening file na: No such file or directory
 
******** testing on empty file..
* trying to open and read: empty_file
 
******** testing on valid file with one line content
* trying to open and read: one_line_file
line read: rofl
 
******** testing on a file with one valid and one invalid line
* trying to open and read: invalid_line_file
line read: validline
line read: invalidline
 
******** testing on a file that is read by another process
* trying to open and read: file_read
line read: i am opened to read from
 
******** testing on a file that is written to by another process
* trying to open and read: file_written
line read: i am opened to write to
 
******** testing on a /root/.bashrc (access should be denied)
* trying to open and read: /root/.bashrc
error while opening file /root/.bashrc: Permission denied
 
******** testing on a directory
* trying to open and read: dir
error while reading file dir: Is a directory

Congratulations, “no such file or directory”, “is a directory”, and “permission denied” are catched. Also, the data in the “invalid” line was read.

Ideal solution without printing error messages:

The following source of readfile_stable_no_errors.cpp deals with all errors transparently and extracts residual data from an “invalid” last line:

#include <iostream>
#include <fstream>
#include <string>
using namespace std;
 
 
void process(string* line) {
    cout << "line read: " << *line << endl;
    }
 
 
int main(int argc, char* argv[]) {
    string line;
    if(argc != 2) {
        cerr << "provide one argument" << endl;
        return 1;
        }
    cout << "* trying to open and read: " << argv[1] << endl;
    ifstream f (argv[1]);
    // Note that we can omit checking for f.is_open(), because
    // all errors will be catched correctly by f.fail() (!f) and
    // we do not want to print error messages here.
    // Also note that during the loop, the following rules are obeyed:
    //   - first the IO operation, then error check, then data processing
    //   - failbit and badbit prevent data processing, eofbit does not
    while(getline(f, line)) {
        process(&line);
        }
    f.close();
    return 0;
    }

The test:

./readfile_tests.sh readfile_stable_no_errors.cpp

Output:

******** testing on non-existent file..
* trying to open and read: na
 
******** testing on empty file..
* trying to open and read: empty_file
 
******** testing on valid file with one line content
* trying to open and read: one_line_file
line read: rofl
 
******** testing on a file with one valid and one invalid line
* trying to open and read: invalid_line_file
line read: validline
line read: invalidline
 
******** testing on a file that is read by another process
* trying to open and read: file_read
line read: i am opened to read from
 
******** testing on a file that is written to by another process
* trying to open and read: file_written
line read: i am opened to write to
 
******** testing on a /root/.bashrc (access should be denied)
* trying to open and read: /root/.bashrc
 
******** testing on a directory
* trying to open and read: dir

The intention of this program is to never fail due to stream opening/IO errors. This succeeds: whenever there is data to extract, it extracts data. All other cases are transparently handled correctly.

Remember, all code shown here can be downloaded.

I hope that this article helps someone. Please let me know if I have to correct some things and if we can do better (thanks again to Alexandre at this point).

By using gevent, you automatically get one of the highest performing Python servers you can get for this purpose. Due to the greenlet concept, it is able to handle a huge amount of concurrent connections without any threading overhead. Due to benchmarks like this, the server should be faster than comparable Python solutions (based on e.g. Twisted or Eventlet) while almost reaching the level of optimized C/C++ solutions. Of course, all this performance is not really necessary for a Flash policy server, but it is good to know what we are dealing with.

Now, the code. It is already “bloated” with comments and logging functionality. Due to the use of gevent, the server code itself is very simple:

#!/usr/bin/env python
 
# Flash access policy server based on gevent
# Jan-Philip Gehrcke, June 2011
 
# Listen on port 843; send acess policy to client; disconnect.
 
 
from gevent.server import StreamServer
import datetime
import socket
 
 
# Should we log something? Where to?
LOG = 1
LOGFILE = "flash_access_policy_server.log"
 
# The policy that is sent to the clients.
POLICY = """<cross-domain-policy><allow-access-from domain="*" to-ports="*" /></cross-domain-policy>\0"""
 
# The string the client has to send in order to receive the policy.
POLICYREQUEST = "<policy-file-request/>"
 
 
# This function is called for each incoming connection
# (in a non-blocking fashion in a greenlet)
def client_handle(sock, address):
    log("%s:%s: Connection accepted." % address)
    # send and read functions should not wait longer than three seconds
    sock.settimeout(3)
    try:
        # try to receive at most 128 bytes (`POLICYREQUEST` is shorter)
        input = sock.recv(128)
        if input.startswith(POLICYREQUEST):
            sock.sendall(POLICY)
            log("%s:%s: Policy sent. Closing connection." % address)
        else:
            log("%s:%s: Crap received. Closing connection." % address)
    except socket.timeout:
        log("%s:%s: Timed out. Closing." % address)
    sock.close()
 
 
# Write `msg` to file and stdout, prepended by a date/time string
def log(msg):
    if LOG:
        l = "%s: %s" % (datetime.datetime.now().isoformat(), msg)
        lf.write("%s\n" % l)
        print l
 
 
if __name__ == '__main__':
    if LOG:
        lf = open(LOGFILE, "a")
    server = StreamServer(('0.0.0.0', 843), client_handle)
    log('Starting server...')
    server.serve_forever()

Note that the policy in this case is not very sophisticated and basically allows everything;-)

Just use the command set_name, as it is described in the PyMOL wiki:

set_name old_name, new_name