[tahoe-lafs-trac-stream] [tahoe-lafs] #1732: consider changes to webapi "Move" API before release

[tahoe-lafs]

#1732: consider changes to webapi "Move" API before release
-------------------------------+-------------------------------------------
     Reporter:  warner         |      Owner:  warner
         Type:  enhancement    |     Status:  new
     Priority:  critical       |  Milestone:  1.10.0
    Component:  code-          |    Version:  1.9.1
  frontend-web                 |   Keywords:  forward-compatibility blocker
   Resolution:                 |
Launchpad Bug:                 |
-------------------------------+-------------------------------------------

Comment (by davidsarah):

 OK, I think this is what we have now:
 {{{

 Relinking a Child
 -----------------

 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=rename&from_name=OLD``
        ``&to_dir=$NEWDIRCAP/[NEWSUBDIRS../]&to_name=NEW``
        ``[&replace=true|false|only-files]``    (Tahoe >= v1.10)

  This instructs the node to relink a child of the given source directory,
  into a different directory and/or to a different name. The source and
  destination directories must be writeable. {{{to_dir}}} may be the same
  as the source directory and {{{to_name}}} may be the same as
 {{{from_name}}},
  but {{{to_dir}}} and {{{to_name}}} are always required. If the
 destination
  link (directory and name) is the same as the source link, the operation
 has
  no effect.

  Metadata from the source directory entry is preserved. Multiple levels of
  descent in the source and destination paths are supported.

  This operation will return an HTTP 404 "Not Found" error if
  ``$DIRCAP/[SUBDIRS../]``, the child being moved, or the destination
  directory does not exist. It will return an HTTP 400 "Bad Request" error
  if any entry in the source or destination paths is not a directory.

  The default behavior is to overwrite any existing object at the
 destination
  (replace=true). To prevent this (and make the operation return an error
  instead of overwriting), add a "replace=false" argument. With
 replace=false,
  this operation will return an HTTP 409 "Conflict" error if there is
 already
  an object at the destination, rather than overwriting the existing
 object.
  To allow the operation to overwrite a file, but return an HTTP 409 error
  when trying to overwrite a directory, use "replace=only-files" (this
 behavior
  is closer to the traditional UNIX "mv" command). Note that "true", "t",
 and
  "1" are all synonyms for "True"; "false", "f", and "0" are synonyms for
  "False"; and the parameter is case-insensitive.

  When relinking into a different directory, for safety, the child is not
  unlinked from the old directory until it has been successfully linked
 into
  the new directory. This implies that in case of a crash or failure, the
  child will not be lost, but could be linked at both the old and new
  locations.

  The source link should not be the same as any link (directory and child
 name)
  in the ``to_dir`` path. This restriction is not enforced, but it may be
  enforced in a future version. If it were violated then the result would
 be
  to create a cycle in the directory structure that is not necessarily
 reachable
  from the root of the destination path (``$NEWDIRCAP``), which could
 result in
  data loss, as described in ticket `#943`_.

 .. _`#943`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/943
 }}}

 (I just added the bit about #943.)

-- 
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1732#comment:39>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage