← Back to branch summary

~ubuntu-branches/debian/sid/subversion/sid

« back to all changes in this revision

Viewing changes to subversion/libsvn_ra_neon/README

  • Committer: Package Import Robot
  • Author(s): James McCoy, Peter Samuelson, James McCoy
  • Date: 2014-01-12 19:48:33 UTC
  • mfrom: (0.2.10)
  • Revision ID: package-import@ubuntu.com-20140112194833-w3axfwksn296jn5x
Tags: 1.8.5-1
http://bugs.debian.org/725787
http://bugs.debian.org/507430
http://bugs.debian.org/734163
http://bugs.debian.org/601544
http://bugs.debian.org/687291
http://bugs.debian.org/273874
http://bugs.debian.org/690815
http://bugs.debian.org/654172
http://bugs.debian.org/678224
http://bugs.debian.org/566148
http://bugs.debian.org/734918
http://bugs.debian.org/722393
[ Peter Samuelson ]
* New upstream release.  (Closes: #725787) Rediff patches:
  - Remove apr-abi1 (applied upstream), rename apr-abi2 to apr-abi
  - Remove loosen-sqlite-version-check (shouldn't be needed)
  - Remove java-osgi-metadata (applied upstream)
  - svnmucc prompts for a changelog if none is provided. (Closes: #507430)
  - Remove fix-bdb-version-detection, upstream uses "apu-config --dbm-libs"
  - Remove ruby-test-wc (applied upstream)
  - Fix “svn diff -r N file” when file has svn:mime-type set.
    (Closes: #734163)
  - Support specifying an encoding for mod_dav_svn's environment in which
    hooks are run.  (Closes: #601544)
  - Fix ordering of “svnadmin dump” paths with certain APR versions.
    (Closes: #687291)
  - Provide a better error message when authentication fails with an
    svn+ssh:// URL.  (Closes: #273874)
  - Updated Polish translations.  (Closes: #690815)

[ James McCoy ]
* Remove all traces of libneon, replaced by libserf.
* patches/sqlite_3.8.x_workaround: Upstream fix for wc-queries-test test
  failurse.
* Run configure with --with-apache-libexecdir, which allows removing part of
  patches/rpath.
* Re-enable auth-test as upstream has fixed the problem of picking up
  libraries from the environment rather than the build tree.
  (Closes: #654172)
* Point LD_LIBRARY_PATH at the built auth libraries when running the svn
  command during the build.  (Closes: #678224)
* Add a NEWS entry describing how to configure mod_dav_svn to understand
  UTF-8.  (Closes: #566148)
* Remove ancient transitional package, libsvn-ruby.
* Enable compatibility with Sqlite3 versions back to Wheezy.
* Enable hardening flags.  (Closes: #734918)
* patches/build-fixes: Enable verbose build logs.
* Build against the default ruby version.  (Closes: #722393)

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
 
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
 
 
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
 
 
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
 
 
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