Author: | tundish |
---|---|
Date: | 13th June 2007 |
Copyright: | 2007 Thuswise Ltd |
Contact: | tundish at thuswise . org . uk |
I wrote Sprinkle because I needed it quickly for a personal project. So I made it the simplest thing that could possibly work [1].
That's not to say that I'm entirely happy with it. There's lots of ways it could be better. Maybe you can help!
I found the protocol document [2] to be slightly unclear in some places, so if Sprinkle isn't doing what you expect it to, that might be by design. I haven't compared it against other brokers, so it may well have some quirks. For example, when you disconnect, you get an error message in reply before the link goes down. That's just my unilateral choice.
Also, having 'ack' set to 'client' means you get blitzed by the same messages until you acknowledge them. I can see how that might be a problem, but that seems to me to be the implication of the spec.
I have no way to test Sprinkle under heavy load, so I don't know what its limits are. If you are able to stress it in a busy environment, please do. I'd love to get some stats and find out how and when it falls over.
There are heaps of ways you could break Sprinkle if you put your mind to it. User accounts aren't checked, there's no housekeeping of transactions, and no limit on message size. A lot of the admin is simply done on the command line with file system commands.
I would like to improve on this, but I'd like to address the most likely scenarios first. I'd like to make Sprinkle fit for a benign environment where there are only broken clients, before attempting to harden it for the Internet.
So, let me know where you think the most glaring flaws are, and I'll get them fixed first.
If you find a bug in Sprinkle, send me an email and I'll look into it. If you'd rather tackle the issue yourself, here's how you should proceed:
Sprinkle comes with a utility which runs unit tests on the module. Whatever the issue, you should try to recreate it in code. Write one or more tests which set the conditions for the bug and which fail when it happens.
To run the test utility, type:
test-sprinkle.py
You should see something like:
................................. ---------------------------------------------------------------------- Ran 33 tests in 0.476s
Your tests should go in test-sprinkle.py, under a new TestCase class. See the Python documentation on unittest for more details.
Once your Unit Tests are in place, you can set about resolving the issue. When the tests pass, your work is done!
I've adopted an unmodified installation of CentOS [3], version 4.4, as my reference platform. You can use any distribution you like, but you should know that CentOS 4.4 has Python 2.3.4. If Sprinkle doesn't run on this version of Python, that's a bug right there. Also, Sprinkle should not import any modules other than those in the standard Python library.
You are most likely reading this guide with a web browser; ie: as an HTML file. The original document is actually this text file [4]
If you want to change the documentation, you need to install docutils [5], which is a package for Python. Make sure that the script rst2html.py ends up on your execution path.
To generate the documentation, just type make in the Sprinkle source directory, and docutils will take care of the rest. If you get any errors, you need to brush up on your reStructuredText [6]!
Sprinkle is released under the GPL [7], which means you should publish any alterations you make. I'd prefer it if you could send me your changes as a patch.
The way to do it is as follows. Have two copies of the Sprinkle tree. One should be as you received it. The other (with your changes) should be called, say, my_sprinkle. Now run the command:
diff -urN sprinkle-src my_sprinkle > my_patch.diff
Then you can email the output to me. If it's any bigger than a few KBytes, you should zip it up, eg:
gzip my_patch.diff
You will see that the file is compressed to one called my_patch.diff.gz.
Thanks for taking the time to look at Sprinkle. I hope you'll have fun working on it!
[1] | http://www.extremeprogramming.org/rules/simple.html |
[2] | http://stomp.codehaus.org/Protocol |
[3] | http://www.centos.org/ |
[4] | hackers.txt |
[5] | http://docutils.sourceforge.net/ |
[6] | http://docutils.sourceforge.net/rst.html |
[7] | http://www.gnu.org/copyleft/gpl.html |