Features

  - The ``BFG_DEBUG_AUTHORIZATION`` envvar and the
    ``debug_authorization`` config file value now only imply debugging
    of view-invoked security checks.  Previously, information was
    printed for every call to ``has_permission`` as well, which made
    output confusing.  To debug ``has_permission`` checks and other
    manual permission checks, use the debugger and print statements in
    your own code.

  - Authorization debugging info is now only present in the HTTP
    response body oif ``debug_authorization`` is true.

  - The format of authorization debug messages was improved.

  - A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric
    ``debug_notfound`` config file value was added.  When either is
    true, and a NotFound response is returned by the BFG router
    (because a view could not be found), debugging information is
    printed to stderr.  When this value is set true, the body of
    HTTPNotFound responses will also contain the same debugging
    information.

  - ``Allowed`` and ``Denied`` responses from the security machinery
    are now specialized into two types: ACL types, and non-ACL types.
    The ACL-related responses are instances of
    ``repoze.bfg.security.ACLAllowed`` and
    ``repoze.bfg.security.ACLDenied``.  The non-ACL-related responses
    are ``repoze.bfg.security.Allowed`` and
    ``repoze.bfg.security.Denied``.  The allowed-type responses
    continue to evaluate equal to things that themselves evaluate
    equal to the ``True`` boolean, while the denied-type responses
    continue to evaluate equal to things that themselves evaluate
    equal to the ``False`` boolean.  The only difference between the
    two types is the information attached to them for debugging
    purposes.

  - Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all``
    config file value.  When either is true, all other debug-related
    flags are set true unconditionally (e.g. ``debug_notfound`` and
    ``debug_authorization``).

  Documentation

  - Added info about debug flag changes.

  - Added a section to the security chapter named "Debugging
    Imperative Authorization Failures" (for e.g. ``has_permssion``).

4 files changed, 62 insertions, 11 deletions

diff --git a/docs/api/security.rst b/docs/api/security.rst
index 58a405633..c7088656e 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -38,9 +38,14 @@
     'george', 'read')`` that means deny access.  A sequence of ACEs
     makes up an ACL.  It is a string, and it's actual value is "Deny".
 
+  .. autoclass:: ACLDenied
+     :members:
+
+  .. autoclass:: ACLAllowed
+     :members:
+
   .. autoclass:: Denied
      :members:
 
   .. autoclass:: Allowed
      :members:
-
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 9ace43048..3fe3457c0 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -27,11 +27,18 @@ application-specific configuration settings.
 |                             |                          |  See also:                          |
 |                             |                          |  :ref:`reload_templates_section`    |
 +-----------------------------+--------------------------+-------------------------------------+
-| ``BFG_DEBUG_AUTHORIZATION`` |  ``debug_authorization`` |  Print authorization failure/success|
-|                             |                          |  messages to stderr when true       |
+| ``BFG_DEBUG_AUTHORIZATION`` |  ``debug_authorization`` |  Print view authorization failure & |
+|                             |                          |  success info to stderr when true   |
 |                             |                          |  See also:                          |
 |                             |                          |  :ref:`debug_authorization_section` |
 +-----------------------------+--------------------------+-------------------------------------+
+| ``BFG_DEBUG_NOTFOUND``      |  ``debug_notfound``      |  Print view-related NotFound debug  |
+|                             |                          |  messages to stderr when true       |
+|                             |                          |  See also:                          |
+|                             |                          |  :ref:`debug_notfound_section`      |
++-----------------------------+--------------------------+-------------------------------------+
+| ``BFG_DEBUG_ALL``           |  ``debug_all``           |  Turns all debug_* settings on.     |
++-----------------------------+--------------------------+-------------------------------------+
 
 Examples
 --------
@@ -58,3 +65,10 @@ If you started your application this way, your :mod:`repoze.bfg`
 application would behave in the same manner as if you had placed the
 respective settings in the ``[app:main]`` section of your
 application's ``.ini`` file.
+
+If you want to turn all ``debug`` settings (every debug setting that
+starts with ``debug_``). on in one fell swoop, you can use
+``BFG_DEBUG_ALL=1`` as an environment variable setting or you may use
+``debug_all=true`` in the config file.  Note that this does not effect
+settings that do not start with ``debug_*`` such as
+``reload_templates``.
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index b57ad2958..041fff89d 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -166,19 +166,20 @@ location-awareness.
 
 .. _debug_authorization_section:
 
-Debugging Authorization Failures
---------------------------------
+Debugging View Authorization Failures
+-------------------------------------
 
-If your application in your judgment is allowing or denying access
-inappropriately, start your application under a shell using the
+If your application in your judgment is allowing or denying view
+access inappropriately, start your application under a shell using the
 ``BFG_DEBUG_AUTHORIZATION`` environment variable set to ``1``.  For
 example::
 
   $ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini
 
-When any authorization takes place, a message will be logged to the
-console (to stderr) about what ACE in which ACL permitted or denied
-the authorization based on authentication information.
+When any authorization takes place during a top-level view rendering,
+a message will be logged to the console (to stderr) about what ACE in
+which ACL permitted or denied the authorization based on
+authentication information.
 
 This behavior can also be turned on in the application ``.ini`` file
 by setting the ``debug_authorization`` key to ``true`` within the
@@ -188,3 +189,20 @@ application's configuration section, e.g.::
   use = egg:MyProject#app
   debug_authorization = true
 
+With this debug flag turned on, the response sent to the browser will
+also contain security debugging information in its body.
+
+Debugging Imperative Authorization Failures
+-------------------------------------------
+
+The ``has_permission`` API (see :ref:`security_module`) is used to
+check security within view functions imperatively.  It returns
+instances of objects that are effectively booleans.  But these objects
+are not raw ``True`` or ``False`` objects, and have information
+attached to them about why the permission was allowed or denied.  The
+object will be one of ``ACLAllowed``, ``ACLDenied``, ``Allowed``, and
+``Denied``, documented in :ref:`security_module`.  At very minimum
+these objects will have a ``msg`` attribute, which is a string
+indicating why permission was denied or allowed.  Introspecting this
+information in the debugger or via print statements when a
+``has_permission`` fails is often useful.
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index d57cf8f02..6ed2dabd1 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -129,11 +129,25 @@ code to execute:
     and the context.  If a view function is found, it is called with
     the context and the request.  It returns a response, which is fed
     back upstream.  If a view is not found, a generic WSGI
-    ``NotFound`` application is constructed.
+    ``NotFound`` application is constructed and returned.
 
 In either case, the result is returned upstream via the :term:`WSGI`
 protocol.
 
+.. _debug_notfound_section:
+
+NotFound Errors
+---------------
+
+It's useful to be able to debug ``NotFound`` errors when they occur
+unexpectedly due to an application registry misconfiguration.  To
+debug these errors, use the ``BFG_DEBUG_NOTFOUND`` environment
+variable or the ``debug_notfound`` configuration file setting.
+Details of why a view was not found will be printed to stderr, and the
+browser representation of the error will include the same information.
+See :ref:`environment_chapter` for more information about how and
+where to set these values.
+
 A Traversal Example
 -------------------