This branch exists for the resolution of issue #3380, which tracks a
much-needed overhaul of the Subversion server-side authorization
subsystem.  It is managed as a reintegrate-able branch, with regular
catch-up merges from the trunk.

THE PLAN
========

The original and current Subversion server-side authorization
subsystem allows the libsvn_repos logic to ask the server simple
questions about read access for items in the repository, basically of
the form "Can the user read path FOO?"  But read access to a given
path carries more meaning than is often necessary, combining "can read
the contents of FOO if it's a file", "can read the properties of FOO",
and "can know that FOO even exists" all into one permission check.

The aforementioned behavior is over-protective, and ultimately
detrimental to Subversion's ability to operate correctly.  Because
Subversion uses the svn_delta_editor_t interfaces all over the place
to transmit tree changes, and because that interface is tree-like in
nature, Subversion clients are forced to "anchor their edit" at the
lowest common ancestor directory of the various repository paths on
which they wish to operate.  This can cause operations on two paths
with are readable but which live in different parts of the repository
to require anchoring at a path that by the current definition is
unreadable.

Consider a repository whose root directory is full of individual
projects.  Users are granted read (and maybe write) access to the
projects they are permitted to see, but not to the root directory.  It
would be great for a given user to be able to checkout the root of the
repository and get a working copy containing only the bits he or she
is allowed to see.  But Subversion would disallow this today on the
basis that the user doesn't have "read access" to the root directory.

The work on this branch aims to bifurcate the "Can the user read path
FOO?" question into two: "Can the user know that path FOO exists?" and
"Can the user read FOO's content/properties?"  The answer to the
latter question is calculated exactly as it is today.  But the answer
to the former question differs, taking into consideration not just the
paths the user has read access to, but also the parents of those
paths.  After all, it stands to reason that if a user is allowed to
know that /project/subproject/trunk exists, no rocket science is
required to determine that /project and /project/subproject also
exist.


BRANCH STATUS
=============

A new authz-related svn-repos API has been introduced
(svn_repos_access_func_t) which attempts to unify the two existing
ones (svn_repos_authz_func_t and svn_repos_authz_callback_t) while
also adding support for the "list" (or "exist", or "directory
traversal", or ...) access type.

svn_repos.h API functions have been revved (well, in prototypes only)
to accept the new callback type.

Code has been added for wrapping old-style callbacks with the new
approach for the sake of compatibility.  So, for deprecated APIs, the
convention will be something like:

   access_func = NULL;
   access_baton = NULL;
   if (auth_read_func)
     svn_repos__upgrade_authz_func(&access_func, &access_baton,
                                   authz_read_func, authz_baton, pool);
   SVN_ERR(newer_api_func(..., access_func, access_baton, ...)

One thing cmpilato isn't happy about is that the new API permits only
a single boolean "has-access" type of answer.  This means that in
places where Subversion could gracefully degrade functionality when a
user has "list" access but not "read" access, multiple queries will
have to occur:

   for entry in dirents:
     # see if the user has read access.  if not, that's okay.  we can get
     # by with list access, but just can't show dirprops.
     if (check_access(dirpath, svn_repos_access_read, ...))
       # send the directory and its props
       send_dir(dirpath, props, ...)
     elif (check_access(dirpath, svn_repos_access_list, ...))
       # send the directory, but strip the props
       send_dir(dirpath, None, ...)

It'd be nicer if we could ask the access question once: "What level of
access does the user have to resource X (perhaps, up to and including
level Y)?"


SCARY THOUGHT
=============

If the Subversion project would simply decide that directory
properties -- or node properties in general -- where not a protectable
resource, we could dispense with much of the complication and return
to a simple read/write access question.  A directory would be readable
iff it is either explicitly readable or implicitly so by virtue of
having readable (grand?)children.  Files stick with the same policies
as have existed forever.  As it turns out, we already stretch toward
this policy in our handling of svn:mergeinfo, which we often fetch
with blatant and intentional disregard for directory accessibility
(for the stability of the whole system).