From c360bf604a01655d942b1e9962fa95617d002d2a Mon Sep 17 00:00:00 2001 From: Zooko O'Whielacronx <zooko@zooko.com> Date: Tue, 13 Jan 2009 20:51:43 -0700 Subject: [PATCH] docs: rename frontends/webapi.txt to frontends/wapi.txt rename CLI.txt to frontends/CLI.txt change a few mentions of "webapi" to "wapi" fixes #582 --- NEWS | 30 ++++++++++++------------- docs/configuration.txt | 2 +- docs/{ => frontends}/CLI.txt | 10 ++++----- docs/frontends/{webapi.txt => wapi.txt} | 12 +++++----- docs/logging.txt | 4 ++-- docs/using.html | 4 ++-- 6 files changed, 31 insertions(+), 31 deletions(-) rename docs/{ => frontends}/CLI.txt (98%) rename docs/frontends/{webapi.txt => wapi.txt} (99%) diff --git a/NEWS b/NEWS index f4674928..b741648c 100644 --- a/NEWS +++ b/NEWS @@ -30,7 +30,7 @@ By periodically checking/repairing all files and directories, objects in the Tahoe filesystem remain resistant to recoverability failures due to missing and/or broken servers. -This release includes a webapi mechanism to initiate checks on individual +This release includes a wapi mechanism to initiate checks on individual files and directories (with or without verification, and with or without automatic repair). A related mechanism is used to initiate a "deep-check" on a directory: recursively traversing the directory and its children, checking @@ -46,7 +46,7 @@ and deep-check operations. When these operations finish, they display a results page that summarizes any problems that were encountered. All long-running deep-traversal operations, including deep-check, use a start-and-poll mechanism, to avoid depending upon a single long-lived HTTP -connection. docs/frontends/webapi.txt has details. +connection. docs/frontends/wapi.txt has details. ** Configuration Changes: single INI-format tahoe.cfg file @@ -152,11 +152,11 @@ The top-level status page (/status) now has a machine-readable form, via "/status/?t=json". This includes information about the currently-active uploads and downloads, which may be useful for frontends that wish to display progress information. There is no easy way to correlate the activities -displayed here with recent webapi requests, however. +displayed here with recent wapi requests, however. Any files in BASEDIR/public_html/ (configurable) will be served in response to requests in the /static/ portion of the URL space. This will simplify the -deployment of javascript-based frontends that can still access webapi calls +deployment of javascript-based frontends that can still access wapi calls by conforming to the (regrettable) "same-origin policy". The welcome page now has a "Report Incident" button, which is tied into the @@ -192,7 +192,7 @@ moved here too. As a result, the directory page is now much simpler and cleaner, and several potentially-misleading links (like t=uri) are now gone. Slashes are discouraged in Tahoe file/directory names, since they cause -problems when accessing the filesystem through the webapi. However, there are +problems when accessing the filesystem through the wapi. However, there are a couple of accidental ways to generate such names. This release tries to make it easier to correct such mistakes by escaping slashes in several places, allowing slashes in the t=info and t=delete commands, and in the @@ -262,7 +262,7 @@ plugins that can be used to monitor a storage grid. The misc/spacetime/ directory contains a "disk watcher" daemon (startable with 'tahoe start'), which can be configured with a set of HTTP URLs -(pointing at the webapi '/statistics' page of a bunch of storage servers), +(pointing at the wapi '/statistics' page of a bunch of storage servers), and will periodically fetch disk-used/disk-available information from all the servers. It keeps this information in an Axiom database (a sqlite-based library available from divmod.org). The daemon computes time-averaged rates @@ -274,7 +274,7 @@ The misc/munin/ directory contains a new set of munin plugins disk-watcher and provide graphs of its calculations. To support the disk-watcher, the Tahoe statistics component (visible through -the webapi at the /statistics/ URL) now includes disk-used and disk-available +the wapi at the /statistics/ URL) now includes disk-used and disk-available information. Both are derived through an equivalent of the unix 'df' command (i.e. they ask the kernel for the number of free blocks on the partition that encloses the BASEDIR/storage directory). In the future, the disk-available @@ -301,7 +301,7 @@ logs) now includes a platform identifer (frequently including a linux distribution name, processor architecture, etc). Several bugs have been fixed, including one that would cause an exception (in -the logs) if a webapi download operation was cancelled (by closing the TCP +the logs) if a wapi download operation was cancelled (by closing the TCP connection, or pushing the "stop" button in a web browser). The 12GiB (approximate) immutable-file-size limitation is slowly being @@ -402,7 +402,7 @@ Tahoe is slowly acquiring convenient tools to check up on file health, examine existing shares for errors, and repair files that are not fully healthy. This release adds a mutable checker/verifier/repairer, although testing is very limited, and there are no web interfaces to trigger repair -yet. The "Check" button next to each file or directory on the webapi page +yet. The "Check" button next to each file or directory on the wapi page will perform a file check, and the "deep check" button on each directory will recursively check all files and directories reachable from there (which may take a very long time). @@ -442,7 +442,7 @@ the incidents/ directory for a second time. If no servers are available when retrieving a mutable file (like a directory), the node now reports an error instead of hanging forever. Earlier -releases would not only hang (causing the webapi directory listing to get +releases would not only hang (causing the wapi directory listing to get stuck half-way through), but the internal dirnode serialization would cause all subsequent attempts to retrieve or modify the same directory to hang as well. #463 @@ -467,7 +467,7 @@ directories, recursive copy in or out of the storage grid, hardlinks, and retrieving the raw read- or write- caps through the 'ls' command. Please read docs/CLI.txt for complete details. -** webapi: new pages, new commands +** wapi: new pages, new commands Several new pages were added to the web API: @@ -488,7 +488,7 @@ Several new options to the GET command were added: POST is now preferred over PUT for most operations which cause side-effects. -Most webapi calls now accept overwrite=, and default to overwrite=true . +Most wapi calls now accept overwrite=, and default to overwrite=true . "POST /uri/DIRCAP/parent/child?t=mkdir" is now the preferred API to create multiple directories at once, rather than ...?t=mkdir-p . @@ -520,7 +520,7 @@ method) and is less likely to lose data when several uncoordinated writers change a file at the same time. In addition, a single Tahoe process will coordinate its own writes. If you -make two concurrent directory-modifying webapi calls to a single tahoe node, +make two concurrent directory-modifying wapi calls to a single tahoe node, it will internally make one of them wait for the other to complete. This prevents auto-collision (#391). @@ -541,8 +541,8 @@ first attempt, but once any attempt succeeds, the other server connections will be retried immediately. A new "offloaded KeyGenerator" facility can be configured, to move RSA key -generation out from, say, a webapi node, into a separate process. RSA keys -can take several seconds to create, and so a webapi node which is being used +generation out from, say, a wapi node, into a separate process. RSA keys +can take several seconds to create, and so a wapi node which is being used for directory creation will be unavailable for anything else during this time. The Key Generator process will pre-compute a small pool of keys, to speed things up further. This also takes better advantage of multi-core CPUs, diff --git a/docs/configuration.txt b/docs/configuration.txt index bb53bee8..0c345af7 100644 --- a/docs/configuration.txt +++ b/docs/configuration.txt @@ -49,7 +49,7 @@ nickname = (UTF-8 string, optional) web.port = (strports string, optional) This controls where the node's webserver should listen, providing filesystem - access and node status as defined in webapi.txt . This file contains a + access and node status as defined in wapi.txt . This file contains a Twisted "strports" specification such as "3456" or "tcp:3456:interface=127.0.0.1". The 'tahoe create-client' command sets the web.port to "tcp:3456:interface=127.0.0.1" by default, and is overridable by diff --git a/docs/CLI.txt b/docs/frontends/CLI.txt similarity index 98% rename from docs/CLI.txt rename to docs/frontends/CLI.txt index aeb404c3..2c950d34 100644 --- a/docs/CLI.txt +++ b/docs/frontends/CLI.txt @@ -54,7 +54,7 @@ clients. "key-generation" service, which allows a client to offload their RSA key generation to a separate process. Since RSA key generation takes several seconds, and must be done each time a directory is created, moving it to a -separate process allows the first process (perhaps a busy webapi server) to +separate process allows the first process (perhaps a busy wapi server) to continue servicing other requests. The key generator exports a FURL that can be copied into a client node to enable this functionality. @@ -78,13 +78,13 @@ start using their changes. These commands let you exmaine a Tahoe filesystem, providing basic list/upload/download/delete/rename/mkdir functionality. They can be used as primitives by other scripts. Most of these commands are fairly thin wrappers -around webapi calls. +around wapi calls. By default, all filesystem-manipulation commands look in ~/.tahoe/ to figure -out which Tahoe node they should use. When the CLI command uses webapi calls, +out which Tahoe node they should use. When the CLI command uses wapi calls, it will use ~/.tahoe/node.url for this purpose: a running Tahoe node that -provides a webapi port will write its URL into this file. If you want to use -a node on some other host, just create ~/.tahoe/ and copy that node's webapi +provides a wapi port will write its URL into this file. If you want to use +a node on some other host, just create ~/.tahoe/ and copy that node's wapi URL into this file, and the CLI commands will contact that node instead of a local one. diff --git a/docs/frontends/webapi.txt b/docs/frontends/wapi.txt similarity index 99% rename from docs/frontends/webapi.txt rename to docs/frontends/wapi.txt index 1242c6e8..1ceca14d 100644 --- a/docs/frontends/webapi.txt +++ b/docs/frontends/wapi.txt @@ -151,7 +151,7 @@ that file with: Multiple levels of subdirectories can be handled this way: - http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/webapi.txt + http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/wapi.txt In this document, when we need to refer to a URL that references a file using this child-of-some-directory format, we'll use the following string: @@ -182,9 +182,9 @@ contain unicode filenames, and cannot contain binary strings that are not representable as such. All Tahoe operations that refer to existing files or directories must include -a suitable read- or write- cap in the URL: the webapi server won't add one +a suitable read- or write- cap in the URL: the wapi server won't add one for you. If you don't know the cap, you can't access the file. This allows -the security properties of Tahoe caps to be extended across the webapi +the security properties of Tahoe caps to be extended across the wapi interface. == Slow Operations, Progress, and Cancelling == @@ -1197,7 +1197,7 @@ GET / (introducer status) == Static Files in /public_html == -The webapi server will take any request for a URL that starts with /static +The wapi server will take any request for a URL that starts with /static and serve it from a configurable directory which defaults to $BASEDIR/public_html . This is configured by setting the "[node]web.static" value in $BASEDIR/tahoe.cfg . If this is left at the default value of @@ -1205,7 +1205,7 @@ value in $BASEDIR/tahoe.cfg . If this is left at the default value of served with the contents of the file $BASEDIR/public_html/subdir/foo.html . This can be useful to serve a javascript application which provides a -prettier front-end to the rest of the Tahoe webapi. +prettier front-end to the rest of the Tahoe wapi. == safety and security issues -- names vs. URIs == @@ -1284,7 +1284,7 @@ Coordination Directive. Tahoe nodes implement internal serialization to make sure that a single Tahoe node cannot conflict with itself. For example, it is safe to issue two -directory modification requests to a single tahoe node's webapi server at the +directory modification requests to a single tahoe node's wapi server at the same time, because the Tahoe node will internally delay one of them until after the other has finished being applied. (This feature was introduced in Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing diff --git a/docs/logging.txt b/docs/logging.txt index 9426db06..db526709 100644 --- a/docs/logging.txt +++ b/docs/logging.txt @@ -152,7 +152,7 @@ which should be sending it log events. The "flogtool filter" command, described above, is useful to cut down the potentially-large flogfiles into more a narrowly-focussed form. -Busy nodes, particularly webapi nodes which are performing recursive +Busy nodes, particularly wapi nodes which are performing recursive deep-size/deep-stats/deep-check operations, can produce a lot of log events. To avoid overwhelming the node (and using an unbounded amount of memory for the outbound TCP queue), publishing nodes will start dropping log events when @@ -192,7 +192,7 @@ but a few notes are worth stating here: clustered with its parent. For example, a download process that involves three sequential hash fetches could announce the send and receipt of those hash-fetch messages with a parent= argument that ties them to the overall - download process. However, each new webapi download request should be + download process. However, each new wapi download request should be unparented. * use the format= argument in preference to the message= argument. E.g. diff --git a/docs/using.html b/docs/using.html index dc93f32d..0e748d74 100644 --- a/docs/using.html +++ b/docs/using.html @@ -31,7 +31,7 @@ "<cite>tahoe ls tahoe:</cite>" and "<cite>tahoe cp LOCALFILE tahoe:foo.txt</cite>" to work with your filesystem. The Tahoe CLI uses the same syntax as the well-known scp and rsync tools. See <a - href="CLI.txt">CLI.txt</a> for more details.</p> + href="frontends/CLI.txt">CLI.txt</a> for more details.</p> <p>As with the WUI (and with all current interfaces to Tahoe), you are responsible for remembering directory capabilities yourself. If you @@ -48,7 +48,7 @@ <h1>The WAPI</h1> - <p>Want to program your Tahoe node to do your bidding? Easy! See <a href="webapi.txt">webapi.txt</a>.</p> + <p>Want to program your Tahoe node to do your bidding? Easy! See <a href="frontends/wapi.txt">wapi.txt</a>.</p> <p>P.S. "WAPI" is pronounced "wappy".</p> -- 2.45.2