todo --------------------------------------------------------------------------

- support for X_MATCHBONES

    /m - for each bones file that you upload, it will attempt to download
    one of the same level.  (i.e. if you upload a level 4 bones file you
    will get a different level 4 bones file in exchange).  If no bones file
    is available for that level, it will revert to the default behaviour
    and download a random level instead.

    If you wish to support this behaviour for the Unix client, here's how
    it works.  The filenames of all accepted bones files are stuffed into
    a stack.  Each time round the download loop, the top filename is
    popped off the stack and passed as an argument to the X_MATCHBONES
    header, e.g. sending X_MATCHBONES:bonD0.4 will attempt to download
    bonD0.4 if possible.

- support for skipping bonescheck

    The idea behind the 'bonescheck' phase was that it'd save network
    time to send the MD5 of the file and the version info to decide
    whether the server will accept it.  However, in the common case it
    will always ask for the full file to be sent.  So simply eliminating
    the bonescheck step increases speed by ~25% (probably not so much on
    Linux systems since the bones files are bigger, and it's also less
    important since you have it set up to run under cron).

    If there is a problem with the full bones file, info error messages
    will be sent back exactly as they are from the old bonescheck

- switch to reset/ignore timestamp?

    /r - resets the 'last uploaded' timestamp (that is, prevents Hearse
    attempting to upload old bones files).  Included as a workaround for
    users who sometimes run into problems with this.

- merge in Crawl-modified version of hearse
- Windows support (see message from Darshan Shaligram from 2003-04-01 in
  +project/hearse)
- run evey 15 minutes by default, so you don't miss a bones which is
  created then used before the end of the day
    - man page
    - cron.d
    - cron.daily
- code to ensure version in hearse.spec, debian/changelog, hearse match
- simple install instructions for dependencies
- scripts to publish new versions to web page
    - bump version: hearse, hearse.spec, debian/changelog
    - tell Alexis about new X_HEARSECRC:
	echo -n "UNIX-HEARSE $version" | md5sum
    - cvs-buildpackage
    - move generated files to ../web/dist
    - pod2html hearse >! ../web/hearse.html
    - pod2html bones-info >! ../web/bones-info.html
    - cd ../web/dist
    - ln -s hearse_$version.tar.gz hearse-$version.tar.gz
    - ln -sf hearse_$version.tar.gz hearse-current.tar.gz
    - run-scanpackages
    - rpm -tb --sign hearse-$version.tar.gz &&
	mv -i /usr/src/rpm/RPMS/noarch/hearse-$version-1.noarch.rpm .
    - update web/bones-info
    - update version in index.html.m4, gmake
    - gmake -C ../web install
- rpm: Is there a way to do interactive configuration at install time?
- rpm: How do Red Hat people do the equivalent of /etc/ppp/ip-up.d?

-------------------------------------------------------------------------------

Message-ID: <014601c1fb74$755caaf0$8b0224d9@bingalybong>
From: "Alexis Manning" <alexismanning@bigfoot.com>
To: "Roderick Schertler" <roderick@argon.org>
References: <b37306f8.0205071935.78c8056d@posting.google.com> <CkhC8.38769$26.3160662@typhoon.maine.rr.com> <abc8pp$hbr4t$1@ID-105700.news.dfncis.de> <pzhelaob00.fsf@eeyore.ibcinc.com>
Subject: Re: Is Hearse safe to use with 3.4.0?
Date: Tue, 14 May 2002 19:23:34 +0100

From: "Roderick Schertler" <roderick@argon.org>
> At the risk of invoking the Curse of Hearse, I'm interested in writing a
> Unix version, particularly if it can use your server.  Would you send me
> what info I'd need to interoperate with the server, or the source for
> the client?  Thanks very much.

A brave man!

Well, someone else has offered and is currently (hopefully) perusing the
source code with an eye to get a-porting.  So we have various options:
    * You could offer to work on it with him
    * You could wait and see if he flakes / if the Curse of Hearse zaps him
    * You could work on it separately  (Although I will of course let him
know if you want to do that.  Not fair to keep people in the dark)

I am blissfully indifferent, I don't care particularly much how it's done as
long as it's done.  So let me know what you'd prefer.

In the meantime, here is some light music.

Sorry, no.  In the meantime, here is some stuff I've worked about about
Windows/Unix differences for Hearse which you may find interesting, or may
scare you off the task altogether.

Cheers,

-- A.
====

How Hearse works:
--------------------

The Hearse client is simple.  A couple of bits of data are stored in the
registry, including the date the user last uploaded bones, and a per-user
token.  If the user hasn't used Hearse before, he is prompted for his email
address and the server offers him a per-user token in exchange.  This is
stuffed into the registry and sent with all subsequent requests, and is used
to track who uploaded what bones file (so no one gets the same bones file
twice), and used to selectively block abusive users of the system.  The
per-user token is 32 characters of gibberish, if you care.

After that's out of the way, the process is dirt simple:
    Loop over all bones files that are newer than the last bones date
        Generate an MD5 hash for that file
        Ask the server if it's OK
        If the server says "Yup", submit the bones file
   End loop
   If any bones files were submitted
     Loop
       Ask the server for a bones file
     Repeat until it says No
     Update the last bones date

That's it.  It does get a leetle more complicated, but not much.  A list of
all bones files in that directory is generated and sent to the server during
the download phase so you're not offered a bones file that you already have.
All the communication is done by hitting variations of a fixed URL and
passing arguments as HTTP headers.  Any errors (e.g. "No more bones for
you") are handled by the server passing back a header that indicates that
the body is an error message that should be displayed.

Headers are:
X_USERTOKEN:  per user token
X_HEARSECRC: MD5 hash of the Hearse executable, used to determine whether a
newer version is available.  We'll work out something appropriate to be sent
for Unix.  Sending 'noupdate' will prevent any update being offered.
X_BONESCRC: MD5 hash of the current bones file
X_VER1           Ugly and non-extensible way of sending the bonesfile "magic
number" information.
X_VER2           Done this way to allow for the possibility of masking the
parts of the version
X_VER3           struct that don't really matter at some point in the dim
and distant.
X_VER4
X_ERROR        Was there an error?  If present, is the body some text that
should be displayed (INFO), or should the body be displayed then the client
terminate?  (FATAL)
X_FILENAME  Name of the bonesfile in the body of the message
X_USERLEVELS    Comma delimited listed of the bonesfiles that the user
already has -- don't offer them bonD0.5 if they already have a bonD0.5
X_GIVEINFO    A crappily named header.  Not currently used, but set with the
uploaded first bones file of that session.  The idea is that it could be
used to trigger a Message of the Day or some such.
X_CLIENTID    Always set to PC-HEARSE, unused.  For future expansion.  Yours
could say "UNIX-HEARSE", so if different server behaviour was needed for the
two clients, it could be easily coded.
X_FORCEUPDATE    Server demands that you update to the latest version to use
Hearse.  Windows versions auto-update.


Hearse and Unix
-----------------

The *'s indicate current thinking on the subject, not set in stone at all.
Things in square brackets are really server-side issues that I've just put
in to remind me.  Let me know any particular part makes no sense, or if it
sounds like I've missed something.


Hearse stores a per-user token which is sent with every request to the
server.  This is so that people don't download the same bones file more than
once.  It's also used to track users in case of abuse.  Should this be
per-site on Unix rather than per-user?
 * Per-site is probably better.  The only user who can create a wizard bones
file under Unix is root, so it's likely to be safe.  Worst case, whole site
has to be banned.


File ownership issues
 * Hearse will likely have to run setuid nethack so it can access bones
files.


Hearse has AutoUpdate functionality.  Best way to handle this under Unix?
 * Simplest would probably be to display the error message returned from the
server and quit.  They'll have to download the latest source.
 [Also worth having the server email all the users when an incompatible
version of Hearse is released]


Waaah!  Byte ordering
 * Unlikely to be a problem since the magic numbers will also have their
byte order buggered.  Just make sure the version info is read in byte by
byte, not DWORD by DWORD :)


Hearse stores various bits of data in the registry.  What to do?
 * Have a /etc/hearse.conf file that stores:
  - location of nethack bones
  - Hearse server address [note: this is hardcoded into the client for the
Windows version.  Ewww]
  - File access/owner modes to set on downloaded bones
  - Date of last bones upload
 * Possible race conditions on this file if multiple users run Hearse
simultaneously?

-------------------------------------------------------------------------------

$Id: Notes,v 1.13 2005/03/13 14:35:15 roderick Exp $
