1 | --- old-tahoe/docs/frontends/webapi.txt 2010-01-22 06:05:46.188000000 +0000 |
---|
2 | +++ new-tahoe/docs/frontends/webapi.txt 2010-01-22 06:05:46.257000000 +0000 |
---|
3 | @@ -70,20 +70,20 @@ |
---|
4 | these tasks. In general, everything that can be done with a PUT or DELETE can |
---|
5 | also be done with a POST. |
---|
6 | |
---|
7 | -Tahoe's web API is designed for two different consumers. The first is a |
---|
8 | -program that needs to manipulate the virtual file system. Such programs are |
---|
9 | +Tahoe's web API is designed for two different kinds of consumer. The first is |
---|
10 | +a program that needs to manipulate the virtual file system. Such programs are |
---|
11 | expected to use the RESTful interface described above. The second is a human |
---|
12 | using a standard web browser to work with the filesystem. This user is given |
---|
13 | a series of HTML pages with links to download files, and forms that use POST |
---|
14 | actions to upload, rename, and delete files. |
---|
15 | |
---|
16 | When an error occurs, the HTTP response code will be set to an appropriate |
---|
17 | -400-series code (like 404 for an unknown childname, or 400 Gone when a file |
---|
18 | -is unrecoverable due to insufficient shares), and the HTTP response body will |
---|
19 | -usually contain a few lines of explanation as to the cause of the error and |
---|
20 | -possible responses. Unusual exceptions may result in a 500 Internal Server |
---|
21 | -Error as a catch-all, with a default response body will contain a |
---|
22 | -Nevow-generated HTML-ized representation of the Python exception stack trace |
---|
23 | +400-series code (like 404 Not Found for an unknown childname, or 400 Bad Request |
---|
24 | +when the parameters to a webapi operation are invalid), and the HTTP response |
---|
25 | +body will usually contain a few lines of explanation as to the cause of the |
---|
26 | +error and possible responses. Unusual exceptions may result in a |
---|
27 | +500 Internal Server Error as a catch-all, with a default response body containing |
---|
28 | +a Nevow-generated HTML-ized representation of the Python exception stack trace |
---|
29 | that caused the problem. CLI programs which want to copy the response body to |
---|
30 | stderr should provide an "Accept: text/plain" header to their requests to get |
---|
31 | a plain text stack trace instead. If the Accept header contains */*, or |
---|
32 | @@ -108,9 +108,9 @@ |
---|
33 | read- and write- caps, which start with "URI:SSK", and give access to mutable |
---|
34 | files. |
---|
35 | |
---|
36 | -(later versions of Tahoe will make these strings shorter, and will remove the |
---|
37 | +(Later versions of Tahoe will make these strings shorter, and will remove the |
---|
38 | unfortunate colons, which must be escaped when these caps are embedded in |
---|
39 | -URLs). |
---|
40 | +URLs.) |
---|
41 | |
---|
42 | To refer to any Tahoe object through the web API, you simply need to combine |
---|
43 | a prefix (which indicates the HTTP server to use) with the cap (which |
---|
44 | @@ -195,9 +195,9 @@ |
---|
45 | representable as such. |
---|
46 | |
---|
47 | All Tahoe operations that refer to existing files or directories must include |
---|
48 | -a suitable read- or write- cap in the URL: the wapi server won't add one |
---|
49 | +a suitable read- or write- cap in the URL: the webapi server won't add one |
---|
50 | for you. If you don't know the cap, you can't access the file. This allows |
---|
51 | -the security properties of Tahoe caps to be extended across the wapi |
---|
52 | +the security properties of Tahoe caps to be extended across the webapi |
---|
53 | interface. |
---|
54 | |
---|
55 | == Slow Operations, Progress, and Cancelling == |
---|
56 | @@ -271,7 +271,7 @@ |
---|
57 | since the operation completed) will remain valid for ten minutes. |
---|
58 | |
---|
59 | Many "slow" operations can begin to use unacceptable amounts of memory when |
---|
60 | -operation on large directory structures. The memory usage increases when the |
---|
61 | +operating on large directory structures. The memory usage increases when the |
---|
62 | ophandle is polled, as the results must be copied into a JSON string, sent |
---|
63 | over the wire, then parsed by a client. So, as an alternative, many "slow" |
---|
64 | operations have streaming equivalents. These equivalents do not use operation |
---|
65 | @@ -314,7 +314,7 @@ |
---|
66 | To use the /uri/$FILECAP form, $FILECAP be a write-cap for a mutable file. |
---|
67 | |
---|
68 | In the /uri/$DIRCAP/[SUBDIRS../]FILENAME form, if the target file is a |
---|
69 | - writable mutable file, that files contents will be overwritten in-place. If |
---|
70 | + writable mutable file, that file's contents will be overwritten in-place. If |
---|
71 | it is a read-cap for a mutable file, an error will occur. If it is an |
---|
72 | immutable file, the old file will be discarded, and a new one will be put in |
---|
73 | its place. |
---|
74 | @@ -333,7 +333,7 @@ |
---|
75 | PUT /uri |
---|
76 | |
---|
77 | This uploads a file, and produces a file-cap for the contents, but does not |
---|
78 | - attach the file into the virtual drive. No directories will be modified by |
---|
79 | + attach the file into the filesystem. No directories will be modified by |
---|
80 | this operation. The file-cap is returned as the body of the HTTP response. |
---|
81 | |
---|
82 | If "mutable=true" is in the query arguments, the operation will create a |
---|
83 | @@ -347,7 +347,7 @@ |
---|
84 | |
---|
85 | Create a new empty directory and return its write-cap as the HTTP response |
---|
86 | body. This does not make the newly created directory visible from the |
---|
87 | - virtual drive. The "PUT" operation is provided for backwards compatibility: |
---|
88 | + filesystem. The "PUT" operation is provided for backwards compatibility: |
---|
89 | new code should use POST. |
---|
90 | |
---|
91 | POST /uri?t=mkdir-with-children |
---|
92 | @@ -388,8 +388,29 @@ |
---|
93 | "linkcrtime": 1202777696.7564139, |
---|
94 | "linkmotime": 1202777696.7564139, |
---|
95 | } } } ] |
---|
96 | - } |
---|
97 | + } |
---|
98 | |
---|
99 | + For forward-compatibility, a mutable directory can also contain caps in |
---|
100 | + a format that is unknown to the webapi server. When such caps are retrieved |
---|
101 | + from a mutable directory in a "ro_uri" field, they will be prefixed with |
---|
102 | + the string "ro.", indicating that they must not be decoded without |
---|
103 | + checking that they are read-only. The "ro." prefix must not be stripped |
---|
104 | + off without performing this check. (Future versions of the webapi server |
---|
105 | + will perform it where necessary.) |
---|
106 | + |
---|
107 | + If both the "rw_uri" and "ro_uri" fields are present in a given PROPDICT, |
---|
108 | + and the webapi server recognizes the rw_uri as a write cap, then it will |
---|
109 | + reset the ro_uri to the corresponding read cap and discard the original |
---|
110 | + contents of ro_uri (in order to ensure that the two caps correspond to the |
---|
111 | + same object and that the ro_uri is in fact read-only). However this may not |
---|
112 | + happen for caps in a format unknown to the webapi server. Therefore, when |
---|
113 | + writing a directory the webapi client should ensure that the contents |
---|
114 | + of "rw_uri" and "ro_uri" for a given PROPDICT are a consistent |
---|
115 | + (write cap, read cap) pair if possible. If the webapi client only has |
---|
116 | + one cap and does not know whether it is a write cap or read cap, then |
---|
117 | + it is acceptable to set "rw_uri" to that cap and omit "ro_uri". The |
---|
118 | + client must not put a write cap into a "ro_uri" field. |
---|
119 | + |
---|
120 | Note that the webapi-using client application must not provide the |
---|
121 | "Content-Type: multipart/form-data" header that usually accompanies HTML |
---|
122 | form submissions, since the body is not formatted this way. Doing so will |
---|
123 | @@ -404,59 +425,95 @@ |
---|
124 | |
---|
125 | Like t=mkdir-with-children above, but the new directory will be |
---|
126 | deep-immutable. This means that the directory itself is immutable, and that |
---|
127 | - it can only contain deep-immutable objects, like immutable files, literal |
---|
128 | - files, and deep-immutable directories. A non-empty request body is |
---|
129 | - mandatory, since after the directory is created, it will not be possible to |
---|
130 | - add more children to it. |
---|
131 | + it can only contain objects that are treated as being deep-immutable, like |
---|
132 | + immutable files, literal files, and deep-immutable directories. |
---|
133 | + |
---|
134 | + For forward-compatibility, a deep-immutable directory can also contain caps |
---|
135 | + in a format that is unknown to the webapi server. When such caps are retrieved |
---|
136 | + from a deep-immutable directory in a "ro_uri" field, they will be prefixed |
---|
137 | + with the string "imm.", indicating that they must not be decoded without |
---|
138 | + checking that they are immutable. The "imm." prefix must not be stripped |
---|
139 | + off without performing this check. (Future versions of the webapi server |
---|
140 | + will perform it where necessary.) |
---|
141 | + |
---|
142 | + The cap for each child may be given either in the "rw_uri" or "ro_uri" |
---|
143 | + field of the PROPDICT (not both). If a cap is given in the "rw_uri" field, |
---|
144 | + then the webapi server will check that it is an immutable readcap of a |
---|
145 | + *known* format, and give an error if it is not. If a cap is given in the |
---|
146 | + "ro_uri" field, then the webapi server will still check whether known |
---|
147 | + caps are immutable, but for unknown caps it will simply assume that the |
---|
148 | + cap can be stored, as described above. Note that an attacker would be |
---|
149 | + able to store any cap in an immutable directory, so this check when |
---|
150 | + creating the directory is only to help non-malicious clients to avoid |
---|
151 | + accidentally giving away more authority than intended. |
---|
152 | + |
---|
153 | + A non-empty request body is mandatory, since after the directory is created, |
---|
154 | + it will not be possible to add more children to it. |
---|
155 | |
---|
156 | POST /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir |
---|
157 | PUT /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir |
---|
158 | |
---|
159 | Create new directories as necessary to make sure that the named target |
---|
160 | ($DIRCAP/SUBDIRS../SUBDIR) is a directory. This will create additional |
---|
161 | - intermediate directories as necessary. If the named target directory already |
---|
162 | - exists, this will make no changes to it. |
---|
163 | + intermediate mutable directories as necessary. If the named target directory |
---|
164 | + already exists, this will make no changes to it. |
---|
165 | |
---|
166 | If the final directory is created, it will be empty. |
---|
167 | |
---|
168 | - This will return an error if a blocking file is present at any of the parent |
---|
169 | - names, preventing the server from creating the necessary parent directory. |
---|
170 | + This operation will return an error if a blocking file is present at any of |
---|
171 | + the parent names, preventing the server from creating the necessary parent |
---|
172 | + directory, or if it would require changing an immutable directory. |
---|
173 | |
---|
174 | The write-cap of the new directory will be returned as the HTTP response |
---|
175 | body. |
---|
176 | |
---|
177 | POST /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir-with-children |
---|
178 | |
---|
179 | - Like above, but if the final directory is created, it will be populated with |
---|
180 | - initial children from the POST request body, as described above in the |
---|
181 | - /uri?t=mkdir-with-children operation. |
---|
182 | + Like /uri?t=mkdir-with-children, but the final directory is created as a |
---|
183 | + child of an existing mutable directory. This will create additional |
---|
184 | + intermediate mutable directories as necessary. If the final directory is |
---|
185 | + created, it will be populated with initial children from the POST request |
---|
186 | + body, as described above. |
---|
187 | |
---|
188 | POST /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir-immutable |
---|
189 | |
---|
190 | - Like above, but the final directory will be deep-immutable, with the |
---|
191 | - children specified as a JSON dictionary in the POST request body. |
---|
192 | + Like /uri?t=mkdir-immutable, but the final directory is created as a child |
---|
193 | + of an existing mutable directory. The final directory will be deep-immutable, |
---|
194 | + and will be populated with the children specified as a JSON dictionary in |
---|
195 | + the POST request body. |
---|
196 | + |
---|
197 | + In Tahoe 1.6 this operation creates intermediate mutable directories if |
---|
198 | + necessary, but that behaviour should not be relied on; see ticket #920. |
---|
199 | |
---|
200 | POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=NAME |
---|
201 | |
---|
202 | - Create a new empty directory and attach it to the given existing directory. |
---|
203 | - This will create additional intermediate directories as necessary. |
---|
204 | + Create a new empty mutable directory and attach it to the given existing |
---|
205 | + directory. This will create additional intermediate directories as necessary. |
---|
206 | |
---|
207 | - The URL of this form points to the parent of the bottom-most new directory, |
---|
208 | - whereas the previous form has a URL that points directly to the bottom-most |
---|
209 | - new directory. |
---|
210 | + This operation will return an error if a blocking file is present at any of |
---|
211 | + the parent names, preventing the server from creating the necessary parent |
---|
212 | + directory, or if it would require changing any immutable directory. |
---|
213 | + |
---|
214 | + The URL of this operation points to the parent of the bottommost new directory, |
---|
215 | + whereas the /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=mkdir operation above has a URL |
---|
216 | + that points directly to the bottommost new directory. |
---|
217 | |
---|
218 | POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-with-children&name=NAME |
---|
219 | |
---|
220 | - As above, but the new directory will be populated with initial children via |
---|
221 | - the POST request body, as described in /uri?t=mkdir-with-children above. |
---|
222 | + Like /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=NAME, but the new directory will |
---|
223 | + be populated with initial children via the POST request body. |
---|
224 | Note that the name= argument must be passed as a queryarg, because the POST |
---|
225 | request body is used for the initial children JSON. |
---|
226 | |
---|
227 | POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-immutable&name=NAME |
---|
228 | |
---|
229 | - As above, but the new directory will be deep-immutable, with the children |
---|
230 | - specified as a JSON dictionary in the POST request body. Again, the name= |
---|
231 | - argument must be passed as a queryarg. |
---|
232 | + Like /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-with-children&name=NAME, but the |
---|
233 | + final directory will be deep-immutable. The children are specified as a |
---|
234 | + JSON dictionary in the POST request body. Again, the name= argument must be |
---|
235 | + passed as a queryarg. |
---|
236 | + |
---|
237 | + In Tahoe 1.6 this operation creates intermediate mutable directories if |
---|
238 | + necessary, but that behaviour should not be relied on; see ticket #920. |
---|
239 | |
---|
240 | === Get Information About A File Or Directory (as JSON) === |
---|
241 | |
---|
242 | @@ -546,7 +603,7 @@ |
---|
243 | |
---|
244 | Then the rw_uri field will be present in the information about a directory |
---|
245 | if and only if you have read-write access to that directory. The verify_uri |
---|
246 | - field will be presend if and only if the object has a verify-cap |
---|
247 | + field will be present if and only if the object has a verify-cap |
---|
248 | (non-distributed LIT files do not have verify-caps). |
---|
249 | |
---|
250 | ==== About the metadata ==== |
---|
251 | @@ -622,11 +679,11 @@ |
---|
252 | link points. |
---|
253 | |
---|
254 | 4. Also, quite apart from Tahoe, you might be confused about the meaning of |
---|
255 | - the 'ctime' in unix local filesystems, which people sometimes think means |
---|
256 | - file creation time, but which actually means, in unix local filesystems, the |
---|
257 | + the 'ctime' in UNIX local filesystems, which people sometimes think means |
---|
258 | + file creation time, but which actually means, in UNIX local filesystems, the |
---|
259 | most recent time that the file contents or the file metadata (such as owner, |
---|
260 | permission bits, extended attributes, etc.) has changed. Note that although |
---|
261 | - 'ctime' does not mean file creation time in Unix, it does mean link creation |
---|
262 | + 'ctime' does not mean file creation time in UNIX, it does mean link creation |
---|
263 | time in Tahoe, unless the "tahoe backup" command has been used on that link, |
---|
264 | in which case it means something about the local filesystem file which |
---|
265 | corresponds to the Tahoe file which is pointed at by the link. It means |
---|
266 | @@ -634,7 +691,6 @@ |
---|
267 | Windows) or file-contents-or-metadata-update-time of the local file (if |
---|
268 | "tahoe backup" was run on a different operating system). |
---|
269 | |
---|
270 | - |
---|
271 | === Attaching an existing File or Directory by its read- or write- cap === |
---|
272 | |
---|
273 | PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri |
---|
274 | @@ -658,10 +714,15 @@ |
---|
275 | if there is already an object at the given location, rather than |
---|
276 | overwriting the existing object. To allow the operation to overwrite a |
---|
277 | file, but return an error when trying to overwrite a directory, use |
---|
278 | - "replace=only-files" (this behavior is closer to the traditional unix "mv" |
---|
279 | + "replace=only-files" (this behavior is closer to the traditional UNIX "mv" |
---|
280 | command). Note that "true", "t", and "1" are all synonyms for "True", and |
---|
281 | "false", "f", and "0" are synonyms for "False", and the parameter is |
---|
282 | case-insensitive. |
---|
283 | + |
---|
284 | + Note that this operation does not take its child cap in the form of |
---|
285 | + separate "rw_uri" and "ro_uri" fields. Therefore, it cannot accept a |
---|
286 | + child cap in a format unknown to the webapi server, because the server |
---|
287 | + is not able to attenuate an unknown write cap to a read cap. |
---|
288 | |
---|
289 | === Adding multiple files or directories to a parent directory at once === |
---|
290 | |
---|
291 | @@ -678,7 +739,9 @@ |
---|
292 | "childinfo" is a dictionary that contains "rw_uri", "ro_uri", and |
---|
293 | "metadata" keys. You can take the output of "GET /uri/$DIRCAP1?t=json" and |
---|
294 | use it as the input to "POST /uri/$DIRCAP2?t=set_children" to make DIR2 |
---|
295 | - look very much like DIR1. |
---|
296 | + look very much like DIR1 (except for any existing children of DIR2 that |
---|
297 | + were not overwritten, and any existing "tahoe" metadata keys as described |
---|
298 | + below). |
---|
299 | |
---|
300 | When the set_children request contains a child name that already exists in |
---|
301 | the target directory, this command defaults to overwriting that child with |
---|
302 | @@ -695,7 +758,6 @@ |
---|
303 | the section above entitled "Get Information About A File Or Directory (as |
---|
304 | JSON)", in the "About the metadata" subsection. |
---|
305 | |
---|
306 | - |
---|
307 | === Deleting a File or Directory === |
---|
308 | |
---|
309 | DELETE /uri/$DIRCAP/[SUBDIRS../]CHILDNAME |
---|
310 | @@ -715,7 +777,7 @@ |
---|
311 | The object will only become completely unreachable once 1: there are no |
---|
312 | reachable directories that reference it, and 2: nobody is holding a read- |
---|
313 | or write- cap to the object. (This behavior is very similar to the way |
---|
314 | - hardlinks and anonymous files work in traditional unix filesystems). |
---|
315 | + hardlinks and anonymous files work in traditional UNIX filesystems). |
---|
316 | |
---|
317 | This operation will not modify more than a single directory. Intermediate |
---|
318 | directories which were implicitly created by PUT or POST methods will *not* |
---|
319 | @@ -844,7 +906,7 @@ |
---|
320 | POST /uri?t=upload |
---|
321 | |
---|
322 | This uploads a file, and produces a file-cap for the contents, but does not |
---|
323 | - attach the file into the virtual drive. No directories will be modified by |
---|
324 | + attach the file into the filesystem. No directories will be modified by |
---|
325 | this operation. |
---|
326 | |
---|
327 | The file must be provided as the "file" field of an HTML encoded form body, |
---|
328 | @@ -874,9 +936,9 @@ |
---|
329 | |
---|
330 | POST /uri/$DIRCAP/[SUBDIRS../]?t=upload |
---|
331 | |
---|
332 | - This uploads a file, and attaches it as a new child of the given directory. |
---|
333 | - The file must be provided as the "file" field of an HTML encoded form body, |
---|
334 | - produced in response to an HTML form like this: |
---|
335 | + This uploads a file, and attaches it as a new child of the given directory, |
---|
336 | + which must be mutable. The file must be provided as the "file" field of an |
---|
337 | + HTML-encoded form body, produced in response to an HTML form like this: |
---|
338 | <form action="." method="POST" enctype="multipart/form-data"> |
---|
339 | <input type="hidden" name="t" value="upload" /> |
---|
340 | <input type="file" name="file" /> |
---|
341 | @@ -919,9 +981,10 @@ |
---|
342 | POST /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=upload |
---|
343 | |
---|
344 | This also uploads a file and attaches it as a new child of the given |
---|
345 | - directory. It is a slight variant of the previous operation, as the URL |
---|
346 | - refers to the target file rather than the parent directory. It is otherwise |
---|
347 | - identical: this accepts mutable= and when_done= arguments too. |
---|
348 | + directory, which must be mutable. It is a slight variant of the previous |
---|
349 | + operation, as the URL refers to the target file rather than the parent |
---|
350 | + directory. It is otherwise identical: this accepts mutable= and when_done= |
---|
351 | + arguments too. |
---|
352 | |
---|
353 | POST /uri/$FILECAP?t=upload |
---|
354 | |
---|
355 | @@ -949,20 +1012,21 @@ |
---|
356 | |
---|
357 | POST /uri/$DIRCAP/[SUBDIRS../]?t=delete&name=CHILDNAME |
---|
358 | |
---|
359 | - This instructs the node to delete a child object (file or subdirectory) from |
---|
360 | - the given directory. Note that the entire subtree is removed. This is |
---|
361 | - somewhat like "rm -rf" (from the point of view of the parent), but other |
---|
362 | - references into the subtree will see that the child subdirectories are not |
---|
363 | - modified by this operation. Only the link from the given directory to its |
---|
364 | - child is severed. |
---|
365 | + This instructs the node to remove a child object (file or subdirectory) from |
---|
366 | + the given directory, which must be mutable. Note that the entire subtree is |
---|
367 | + unlinked from the parent. Unlike deleting a subdirectory in a UNIX local |
---|
368 | + filesystem, the subtree need not be empty; if it isn't, then other references |
---|
369 | + into the subtree will see that the child subdirectories are not modified by |
---|
370 | + this operation. Only the link from the given directory to its child is severed. |
---|
371 | |
---|
372 | === Renaming A Child === |
---|
373 | |
---|
374 | POST /uri/$DIRCAP/[SUBDIRS../]?t=rename&from_name=OLD&to_name=NEW |
---|
375 | |
---|
376 | - This instructs the node to rename a child of the given directory. This is |
---|
377 | - exactly the same as removing the child, then adding the same child-cap under |
---|
378 | - the new name. This operation cannot move the child to a different directory. |
---|
379 | + This instructs the node to rename a child of the given directory, which must |
---|
380 | + be mutable. This has a similar effect to removing the child, then adding the |
---|
381 | + same child-cap under the new name, except that it preserves metadata. This |
---|
382 | + operation cannot move the child to a different directory. |
---|
383 | |
---|
384 | This operation will replace any existing child of the new name, making it |
---|
385 | behave like the UNIX "mv -f" command. |
---|
386 | @@ -1584,7 +1648,7 @@ |
---|
387 | |
---|
388 | == Static Files in /public_html == |
---|
389 | |
---|
390 | -The wapi server will take any request for a URL that starts with /static |
---|
391 | +The webapi server will take any request for a URL that starts with /static |
---|
392 | and serve it from a configurable directory which defaults to |
---|
393 | $BASEDIR/public_html . This is configured by setting the "[node]web.static" |
---|
394 | value in $BASEDIR/tahoe.cfg . If this is left at the default value of |
---|
395 | @@ -1592,7 +1656,7 @@ |
---|
396 | served with the contents of the file $BASEDIR/public_html/subdir/foo.html . |
---|
397 | |
---|
398 | This can be useful to serve a javascript application which provides a |
---|
399 | -prettier front-end to the rest of the Tahoe wapi. |
---|
400 | +prettier front-end to the rest of the Tahoe webapi. |
---|
401 | |
---|
402 | |
---|
403 | == safety and security issues -- names vs. URIs == |
---|
404 | @@ -1635,6 +1699,17 @@ |
---|
405 | child's name and the child's URI are included in the results of listing the |
---|
406 | parent directory, so it isn't any harder to use the URI for this purpose. |
---|
407 | |
---|
408 | +The read and write caps in a given directory node are separate URIs, and |
---|
409 | +can't be assumed to point to the same object even if they were retrieved in |
---|
410 | +the same operation (although the webapi server attempts to ensure this |
---|
411 | +in most cases). If you need to rely on that property, you should explicitly |
---|
412 | +verify it. More generally, you should not make assumptions about the |
---|
413 | +internal consistency of the contents of mutable directories. As a result |
---|
414 | +of the signatures on mutable object versions, it is guaranteed that a given |
---|
415 | +version was written in a single update, but -- as in the case of a file -- |
---|
416 | +the contents may have been chosen by a malicious writer in a way that is |
---|
417 | +designed to confuse applications that rely on their consistency. |
---|
418 | + |
---|
419 | In general, use names if you want "whatever object (whether file or |
---|
420 | directory) is found by following this name (or sequence of names) when my |
---|
421 | request reaches the server". Use URIs if you want "this particular object". |
---|
422 | @@ -1670,7 +1745,7 @@ |
---|
423 | |
---|
424 | Tahoe nodes implement internal serialization to make sure that a single Tahoe |
---|
425 | node cannot conflict with itself. For example, it is safe to issue two |
---|
426 | -directory modification requests to a single tahoe node's wapi server at the |
---|
427 | +directory modification requests to a single tahoe node's webapi server at the |
---|
428 | same time, because the Tahoe node will internally delay one of them until |
---|
429 | after the other has finished being applied. (This feature was introduced in |
---|
430 | Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing |
---|
431 | |
---|
432 | --- old-tahoe/relnotes.txt 2010-01-22 06:05:46.198000000 +0000 |
---|
433 | +++ new-tahoe/relnotes.txt 2010-01-22 06:05:46.261000000 +0000 |
---|
434 | @@ -1,7 +1,7 @@ |
---|
435 | -ANNOUNCING Tahoe, the Lofty-Atmospheric Filesystem, v1.5 |
---|
436 | +ANNOUNCING Tahoe, the Lofty-Atmospheric Filesystem, v1.6 |
---|
437 | |
---|
438 | The Tahoe-LAFS team is pleased to announce the immediate |
---|
439 | -availability of version 1.5 of Tahoe, the Lofty Atmospheric |
---|
440 | +availability of version 1.6 of Tahoe, the Lofty Atmospheric |
---|
441 | File System. |
---|
442 | |
---|
443 | Tahoe-LAFS is the first cloud storage technology which offers |
---|
444 | @@ -29,15 +29,20 @@ |
---|
445 | |
---|
446 | COMPATIBILITY |
---|
447 | |
---|
448 | -Version 1.5 is fully compatible with the version 1 series of |
---|
449 | -Tahoe-LAFS. Files written by v1.5 clients can be read by |
---|
450 | -clients of all versions back to v1.0. v1.5 clients can read |
---|
451 | -files produced by clients of all versions since v1.0. v1.5 |
---|
452 | -servers can serve clients of all versions back to v1.0 and v1.5 |
---|
453 | +Version 1.6 is fully compatible with the version 1 series of |
---|
454 | +Tahoe-LAFS. Files written by v1.6 clients can be read by |
---|
455 | +clients of all versions back to v1.0. v1.6 clients can read |
---|
456 | +files produced by clients of all versions since v1.0. v1.6 |
---|
457 | +servers can serve clients of all versions back to v1.0 and v1.6 |
---|
458 | clients can use servers of all versions back to v1.0. |
---|
459 | |
---|
460 | -This is the sixth release in the version 1 series. The version |
---|
461 | -1 series of Tahoe-LAFS will be actively supported and |
---|
462 | +In addition, version 1.6 improves forward-compatibility with |
---|
463 | +planned future cap formats, allowing updates to a directory |
---|
464 | +containing both current and future caps, without loss of |
---|
465 | +information. |
---|
466 | + |
---|
467 | +This is the seventh major release in the version 1 series. The |
---|
468 | +version 1 series of Tahoe-LAFS will be actively supported and |
---|
469 | maintained for the forseeable future, and future versions of |
---|
470 | Tahoe-LAFS will retain the ability to read and write files |
---|
471 | compatible with Tahoe-LAFS v1. |
---|