1 Format for submissions to the YARRG server
2 ------------------------------------------
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
8 The HTTP request should be a CGI form submission as if from the
10 <form enctype="multipart/form-data">
11 <input name="clientname">
12 <input name="clientversion">
13 <input name="clientfixes">
14 <input name="timestamp">
17 <input type="file" name="data">
19 The fields are as follows:
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
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
31 Version number of the specific version of the upload client.
32 Should be ideally generated from your version control system
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 :-).
39 Information about the upload:
42 The ocean name. Must be in the correct mixture of lower
43 and upper case letters, eg `Midnight'.
46 The full island name. Must be the full name in the
47 correct mixture of lower and upper case, eg `Alpha Island'.
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.
56 The upload data itself:
59 Should be a file upload with filename `deduped.tsv.gz'.
60 The Content-Type should be application/octet-stream.
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
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.
75 When you submit this successfully you should get
76 400 Bad commodity update
77 with a text/plain document giving the error
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.
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">
92 The return value will be a text/plain document of the form
94 Strip the OK and the full stop and then use that as the value
98 Format for emails from the yarrg exploder
99 -----------------------------------------
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
106 But if you want to get copies, please just email us saying what you
109 These emails are MIME multipart/mixed documents, with two parts you
112 One important part looks like this:
114 Content-Type: text/plain; charset="utf-8"; name="metadata"
115 Content-Disposition: inline; filename="metadata"
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:
121 Passed through from the client (after checking):
122 clientname clientversion clientfixes
123 ocean island timestamp
125 Information about the server which processed the request:
126 servername serverversion serverfixes
129 Aggregated information about the client and server versions:
130 clientspec serverspec
131 each is the three values name, version, fixes, separated by tabs.
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.
138 For convenience of your email filtering, the instance value is
139 reproduced in the Subject line of the whole email.
141 The other important part looks like this:
143 Content-Type: application/octet-stream; name="deduped.tsv.gz"
144 Content-Disposition: attachment; filename="deduped.tsv.gz"
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.
152 Contacting the yarrg server operator
153 ------------------------------------
155 Talk to Aristarchus on Midnight, or ask any officer of the crew
156 Special Circumstances, or email ijackson@chiark.greenend.org.uk.