yarrg/README.devel

   1 Format for submissions to the YARRG server
   2 ------------------------------------------
   3
   4 The yarrg server takes submissions as HTTP requests to one of:
   5  http://upload.yarrg.chiark.net/commod-update-receiver          main server
   6  http://upload.yarrg.chiark.net/test/commod-update-receiver     testing copy
   7
   8 The HTTP request should be a CGI form submission as if from the
   9 following form:
  10   <form enctype="multipart/form-data">
  11   <input name="clientname">
  12   <input name="clientversion">
  13   <input name="clientfixes">
  14   <input name="timestamp">
  15   <input name="ocean">
  16   <input name="island">
  17   <input type="file" name="data">
  18
  19 The fields are as follows:
  20
  21   Information about your upload client.  These are checked by the
  22   upload server to make sure the client is approved and is not out of
  23   date.
  24
  25     clientname
  26         The name of the upload client; different clients maintained
  27         by different people have different names.  Please talk to
  28         the yarrg server maintainer to have your client added to
  29         the approved list.
  30     clientversion
  31         Version number of the specific version of the upload client.
  32         Should be ideally generated from your version control system
  33         if you have one.
  34     clientfixes
  35         Space-separated list of features your client supports and
  36         fixes for bugs which that specific version has had applied.
  37         Should be empty at first :-).
  38
  39   Information about the upload:
  40
  41     ocean
  42         The ocean name.  Must be in the correct mixture of lower
  43         and upper case letters, eg `Midnight'.
  44
  45     island
  46         The full island name.  Must be the full name in the
  47         correct mixture of lower and upper case, eg `Alpha Island'.
  48
  49     timestamp
  50         Oldest age of any data in this upload.  Your client should
  51         collect a timestamp from the yarrg server (see below) before
  52         starting the screenscraping, and then include the value here.
  53         The syntax is a string of digits.  Please do not use your
  54         local computer clock to generate it.
  55
  56   The upload data itself:
  57
  58     data
  59         Should be a file upload with filename `deduped.tsv.gz'.
  60         The Content-Type should be application/octet-stream.
  61
  62         The actual data should be a gzipped tab-separated-values file
  63         with Unix line endings.  Each line should be:
  64            commodity stallname buyprice buyqty sellprice sellqty
  65         with tabs in between each item.  This is just as the data
  66         appears in the Puzzle Pirates trade commodities interfance.
  67         If there is no buy offer, or no sell offer, supply empty
  68         strings.  Where the YPP client says `>1000', pass exactly
  69         that string.
  70
  71         Commodity names must be the full name as displayed in the YPP
  72         screen; they are checked against the master yarrg database.
  73         Each commodity/stall pair should appear only once in the data.
  74
  75 When you submit this successfully you should get
  76    400 Bad commodity update
  77    with a text/plain document giving the error
  78 or
  79    200 OK
  80    with a text/plain document starting with `OK'.  (If you get `200
  81    OK' but the document doesn't start `OK' something has gone wrong.)
  82 In either case you should show the resulting text to your user.
  83
  84
  85 In order to fetch a timestamp, submit this form:
  86   <form enctype="multipart/form-data">
  87   <input name="clientname">
  88   <input name="clientversion">
  89   <input name="clientfixes">
  90   <input name="requesttimestamp" value="y">
  91
  92 The return value will be a text/plain document of the form
  93   OK <digits>.
  94 Strip the OK and the full stop and then use that as the value
  95 for `timestamp'.
  96
  97
  98 Format for emails from the yarrg exploder
  99 -----------------------------------------
 100
 101 Uploads checked and accepted by the yarrg server are distributed by
 102 email to operator(s) of databases doing interesting commodity stuff.
 103 Currently there's only one such database, the yarrg pirate trader
 104 website.  (Work in progress.)
 105
 106 But if you want to get copies, please just email us saying what you
 107 plan to do.
 108
 109 These emails are MIME multipart/mixed documents, with two parts you
 110 should look for:
 111
 112 One important part looks like this:
 113
 114   Content-Type: text/plain; charset="utf-8"; name="metadata"
 115   Content-Disposition: inline; filename="metadata"
 116
 117 This part is a text file giving metadata about the upload in a simple
 118 textual format.  Each line has a keyword at the beginning, a single
 119 tab character, and then a value.  The keywords are:
 120
 121     Passed through from the client (after checking):
 122       clientname clientversion clientfixes
 123       ocean island timestamp
 124
 125     Information about the server which processed the request:
 126       servername serverversion serverfixes
 127       instance
 128
 129     Aggregated information about the client and server versions:
 130       clientspec serverspec
 131     each is the three values name, version, fixes, separated by tabs.
 132
 133 `instance' specifies which installation of the upload server
 134 generated the email.  There are two official yarrg servers, with
 135 instance values of `yarrg.chiark.net' and `yarrg.chiark.net/test'.
 136 You must check this value.
 137
 138 For convenience of your email filtering, the instance value is
 139 reproduced in the Subject line of the whole email.
 140
 141 The other important part looks like this:
 142
 143   Content-Type: application/octet-stream; name="deduped.tsv.gz"
 144   Content-Disposition: attachment; filename="deduped.tsv.gz"
 145
 146 Your email processor should look at the names attached to the parts,
 147 not at the order.  Future updates may send out emails with additional
 148 parts, or additional metadata keywords, so your software should ignore
 149 any such additional information.
 150
 151
 152 Contacting the yarrg server operator
 153 ------------------------------------
 154
 155 Talk to Aristarchus on Midnight, or ask any officer of the crew
 156 Special Circumstances, or email ijackson@chiark.greenend.org.uk.