| 1 |
$Id: Spec.2002-05-14,v 1.1 2005-10-06 10:52:43 roderick Exp $ |
| 2 |
|
| 3 |
Message-ID: <014601c1fb74$755caaf0$8b0224d9@bingalybong> |
| 4 |
From: "Alexis Manning" <[email protected]> |
| 5 |
To: "Roderick Schertler" <[email protected]> |
| 6 |
References: <[email protected]> <[email protected]> <[email protected]> <[email protected]> |
| 7 |
Subject: Re: Is Hearse safe to use with 3.4.0? |
| 8 |
Date: Tue, 14 May 2002 19:23:34 +0100 |
| 9 |
|
| 10 |
From: "Roderick Schertler" <[email protected]> |
| 11 |
> At the risk of invoking the Curse of Hearse, I'm interested in writing a |
| 12 |
> Unix version, particularly if it can use your server. Would you send me |
| 13 |
> what info I'd need to interoperate with the server, or the source for |
| 14 |
> the client? Thanks very much. |
| 15 |
|
| 16 |
A brave man! |
| 17 |
|
| 18 |
Well, someone else has offered and is currently (hopefully) perusing the |
| 19 |
source code with an eye to get a-porting. So we have various options: |
| 20 |
* You could offer to work on it with him |
| 21 |
* You could wait and see if he flakes / if the Curse of Hearse zaps him |
| 22 |
* You could work on it separately (Although I will of course let him |
| 23 |
know if you want to do that. Not fair to keep people in the dark) |
| 24 |
|
| 25 |
I am blissfully indifferent, I don't care particularly much how it's done as |
| 26 |
long as it's done. So let me know what you'd prefer. |
| 27 |
|
| 28 |
In the meantime, here is some light music. |
| 29 |
|
| 30 |
Sorry, no. In the meantime, here is some stuff I've worked about about |
| 31 |
Windows/Unix differences for Hearse which you may find interesting, or may |
| 32 |
scare you off the task altogether. |
| 33 |
|
| 34 |
Cheers, |
| 35 |
|
| 36 |
-- A. |
| 37 |
==== |
| 38 |
|
| 39 |
How Hearse works: |
| 40 |
-------------------- |
| 41 |
|
| 42 |
The Hearse client is simple. A couple of bits of data are stored in the |
| 43 |
registry, including the date the user last uploaded bones, and a per-user |
| 44 |
token. If the user hasn't used Hearse before, he is prompted for his email |
| 45 |
address and the server offers him a per-user token in exchange. This is |
| 46 |
stuffed into the registry and sent with all subsequent requests, and is used |
| 47 |
to track who uploaded what bones file (so no one gets the same bones file |
| 48 |
twice), and used to selectively block abusive users of the system. The |
| 49 |
per-user token is 32 characters of gibberish, if you care. |
| 50 |
|
| 51 |
After that's out of the way, the process is dirt simple: |
| 52 |
Loop over all bones files that are newer than the last bones date |
| 53 |
Generate an MD5 hash for that file |
| 54 |
Ask the server if it's OK |
| 55 |
If the server says "Yup", submit the bones file |
| 56 |
End loop |
| 57 |
If any bones files were submitted |
| 58 |
Loop |
| 59 |
Ask the server for a bones file |
| 60 |
Repeat until it says No |
| 61 |
Update the last bones date |
| 62 |
|
| 63 |
That's it. It does get a leetle more complicated, but not much. A list of |
| 64 |
all bones files in that directory is generated and sent to the server during |
| 65 |
the download phase so you're not offered a bones file that you already have. |
| 66 |
All the communication is done by hitting variations of a fixed URL and |
| 67 |
passing arguments as HTTP headers. Any errors (e.g. "No more bones for |
| 68 |
you") are handled by the server passing back a header that indicates that |
| 69 |
the body is an error message that should be displayed. |
| 70 |
|
| 71 |
Headers are: |
| 72 |
X_USERTOKEN: per user token |
| 73 |
X_HEARSECRC: MD5 hash of the Hearse executable, used to determine whether a |
| 74 |
newer version is available. We'll work out something appropriate to be sent |
| 75 |
for Unix. Sending 'noupdate' will prevent any update being offered. |
| 76 |
X_BONESCRC: MD5 hash of the current bones file |
| 77 |
X_VER1 Ugly and non-extensible way of sending the bonesfile "magic |
| 78 |
number" information. |
| 79 |
X_VER2 Done this way to allow for the possibility of masking the |
| 80 |
parts of the version |
| 81 |
X_VER3 struct that don't really matter at some point in the dim |
| 82 |
and distant. |
| 83 |
X_VER4 |
| 84 |
X_ERROR Was there an error? If present, is the body some text that |
| 85 |
should be displayed (INFO), or should the body be displayed then the client |
| 86 |
terminate? (FATAL) |
| 87 |
X_FILENAME Name of the bonesfile in the body of the message |
| 88 |
X_USERLEVELS Comma delimited listed of the bonesfiles that the user |
| 89 |
already has -- don't offer them bonD0.5 if they already have a bonD0.5 |
| 90 |
X_GIVEINFO A crappily named header. Not currently used, but set with the |
| 91 |
uploaded first bones file of that session. The idea is that it could be |
| 92 |
used to trigger a Message of the Day or some such. |
| 93 |
X_CLIENTID Always set to PC-HEARSE, unused. For future expansion. Yours |
| 94 |
could say "UNIX-HEARSE", so if different server behaviour was needed for the |
| 95 |
two clients, it could be easily coded. |
| 96 |
X_FORCEUPDATE Server demands that you update to the latest version to use |
| 97 |
Hearse. Windows versions auto-update. |
| 98 |
|
| 99 |
|
| 100 |
Hearse and Unix |
| 101 |
----------------- |
| 102 |
|
| 103 |
The *'s indicate current thinking on the subject, not set in stone at all. |
| 104 |
Things in square brackets are really server-side issues that I've just put |
| 105 |
in to remind me. Let me know any particular part makes no sense, or if it |
| 106 |
sounds like I've missed something. |
| 107 |
|
| 108 |
|
| 109 |
Hearse stores a per-user token which is sent with every request to the |
| 110 |
server. This is so that people don't download the same bones file more than |
| 111 |
once. It's also used to track users in case of abuse. Should this be |
| 112 |
per-site on Unix rather than per-user? |
| 113 |
* Per-site is probably better. The only user who can create a wizard bones |
| 114 |
file under Unix is root, so it's likely to be safe. Worst case, whole site |
| 115 |
has to be banned. |
| 116 |
|
| 117 |
|
| 118 |
File ownership issues |
| 119 |
* Hearse will likely have to run setuid nethack so it can access bones |
| 120 |
files. |
| 121 |
|
| 122 |
|
| 123 |
Hearse has AutoUpdate functionality. Best way to handle this under Unix? |
| 124 |
* Simplest would probably be to display the error message returned from the |
| 125 |
server and quit. They'll have to download the latest source. |
| 126 |
[Also worth having the server email all the users when an incompatible |
| 127 |
version of Hearse is released] |
| 128 |
|
| 129 |
|
| 130 |
Waaah! Byte ordering |
| 131 |
* Unlikely to be a problem since the magic numbers will also have their |
| 132 |
byte order buggered. Just make sure the version info is read in byte by |
| 133 |
byte, not DWORD by DWORD :) |
| 134 |
|
| 135 |
|
| 136 |
Hearse stores various bits of data in the registry. What to do? |
| 137 |
* Have a /etc/hearse.conf file that stores: |
| 138 |
- location of nethack bones |
| 139 |
- Hearse server address [note: this is hardcoded into the client for the |
| 140 |
Windows version. Ewww] |
| 141 |
- File access/owner modes to set on downloaded bones |
| 142 |
- Date of last bones upload |
| 143 |
* Possible race conditions on this file if multiple users run Hearse |
| 144 |
simultaneously? |