chiark / gitweb /
6409300edd590d677f612a4ecc80118b105ccd0c
[ypp-sc-tools.web-live.git] / 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 interface.
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.
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.