subversion/libsvn_ra_neon/README

   1
   2                                                                  -*- text -*-
   3
   4 Contents
   5 ========
   6
   7  * Sessions and requests
   8  * Passing errors back from neon callbacks
   9  * Library specific conventions
  10  * Error sources when dispatching a request
  11
  12
  13 \f
  14 Sessions and requests
  15 =====================
  16
  17 Both Neon and ra_neon have concepts known as 'session' and 'request'.
  18 The request concept in ra_neon parallels the one in Neon, except that
  19 ra_neon stores request-related info for the RA layer.  The session
  20 concept in ra_neon differs from the one in Neon: while the one in Neon
  21 is mainly meant to track / maintain a socket connection, the ra_neon
  22 session is the RA session opened by an RA consumer.  An ra_neon session
  23 (currently) contains 2 Neon sessions.
  24
  25 Only one request can be dispatched on a Neon session at a time; this
  26 is why there is a second Neon session, which is used by ra_neon
  27 implementations of Neon callbacks which want to retrieve information
  28 from the server concurrently with an active Neon session.  Allocation
  29 to either Neon session happens automatically.
  30
  31
  32 \f
  33 Passing errors back from neon callbacks
  34 =======================================
  35
  36 The general Neon request sequence is:
  37
  38  1. Create a session
  39  2. Create a request
  40  3. Add an in-memory or callback-provided request body, if applicable
  41  4. Add custom headers, if any
  42  5. Register one or more content consumers for the response body
  43     (ra_neon usually creates xml parsers for this purpose)
  44  6. Dispatch the request
  45     (send it to the server and process the response)
  46
  47 While in any of the registered callbacks (be it xml parser,
  48 body consumer or body provider), Subversion function calls can return
  49 their usual errors.  The Neon APIs have been wrapped to catch these
  50 and marshall them through the Neon layer, so that the dispatch routine
  51 can raise the error for normal processing.
  52
  53
  54 \f
  55 Library specific conventions
  56 ============================
  57
  58  * When a specific variable name is used frequently both to refer to
  59    ra_neon and Neon resources, the Neon resource variable is prefixed
  60    with 'ne_'.
  61
  62  * Don't use Neon functions which construct and destroy
  63    their own requests (ie: ne_simple_request, ne_lock, ne_propfind etc.).
  64
  65  * Create wrapper functions for callbacks, creating an ra_neon callback
  66    which returns an svn_error_t *, storing the returned error
  67    in the request structure.
  68
  69  * When storing an error in the request structure 'err' field,
  70    use the SVN_RA_NEON__REQ_ERR() macro.
  71
  72  * Make Neon resources which need explicit destruction live as short
  73    as possible, or register a pool cleanup to ensure destruction.
  74    Preferrably, copy the results into a pool with the necessary lifetime.
  75
  76
  77 \f
  78 Error sources when dispatching a request
  79 ========================================
  80
  81 There are a number of different error sources which all come
  82 together in svn_ra_neon__request_dispatch(), which tries to
  83 sort them out and generate the most important error.
  84
  85  1. Neon encounters a network or authentication error
  86     (all Neon errors except NE_ERROR and NE_OK)
  87  2. Neon didn't encounter an error (returns NE_OK),
  88     but the response sent contains an HTTP error (ie 404 Not found, or alike)
  89     In this situation, there are 2 possibilities:
  90     a) The response contains extended error explanation from mod_dav,
  91        which will sometimes be marked as Subversion internal error
  92     b) The response contains only the error status code.
  93  3. A callback requested cancelation because the routine it wrapped
  94     [see 'Passing back errors from Neon' about wrapping] returned an error
  95     (request body provider or response consumer, the latter
  96      are xml parser errors, most of the time).
  97
  98 In order to make callers as simple as possible, svn_ra_neon__request_dispatch()
  99 condenses all these error sources into 1 returned svn_error_t, while trying
 100 to keep the errors returned human-readable.
 101
 102 When condensing errors, these rules are used:
 103
 104  - Local errors take priority over ones received from the server
 105  - Authentication problems, network problems and other unknown
 106    errors are transformed into a generic error code + message
 107  - Locally generated errors in the callbacks are returned as is
 108  - Subversion server errors are returned when available
 109  - Protocol statuses unexpectedly returned (including 2xx codes!)
 110    result in a general error message including the status number
 111    and description
 112