ucb/README.md

   1 # Universal Content Broker (UCB)
   2
   3 Universal Content Broker (has ucps) which do things like convert files
   4 to strings in content broker world, or connect LibreOffice with
   5 various DMS and fileshare systems like WebDAV, CMIS, or GIO.
   6
   7 The UCPs implement the Universal Content Provider UNO interfaces in
   8 C++, in particular the `com.sun.star.ucb.ContentProvider` service.
   9
  10 ## WebDAV UCP
  11
  12 The WebDAV content provider is based on `libcurl` for much of the
  13 network and protocol stuff, including authentication.
  14
  15 WebDAV as implemented here is defined in an IETF RFC 4918 extensions,
  16 and the code supports both unencrypted HTTP/1.1 (IETF RFC 2616) as
  17 well as TLS 1.2 or later.
  18
  19 Our WebDAV `com.sun.star.ucb.ContentProvider` service implementation
  20 registers the `vnd.sun.star.webdav` and `http` URI schemes (and their
  21 encrypted TLS variants). See here for the specification:
  22 https://wiki.documentfoundation.org/Documentation/DevGuide/Universal_Content_Providers#The_WebDAV_Content_Provider
  23
  24 Historically, webdav had two ucps, one based on `neon`, the second one
  25 based on `serf`. Both are superseded by the current `libcurl`
  26 implementation (since LibreOffice 7.3), but in case of behavioural
  27 differences, go hunt for code differences (ucb/source/ucp/webdav-neon
  28 and ucb/source/ucp/webdav).
  29
  30 The WebDAV protocol is implemented on top of libcurl basic http GET,
  31 PUT, and POST requests (and is relatively straight-forward - see
  32 `ucb/source/ucp/webdav-curl/webdavcontent.cxx` for the main
  33 functionality), but incorporates custom handling for a number of
  34 server idiosyncrasies:
  35
  36 * Nextcloud will reply to a PROPFIND request with "100 Continue" and
  37   then after the data is uploaded it will send a "401 Unauthorized" if
  38   the auth header is missing in the headers to which it replied with
  39   "100 Continue".
  40 * Sharepoint 16 responds to PROPFIND, PROPPATCH and LOCK with
  41   "Transfer-Encoding: chunked"
  42   with "HTTP/1.1 200 OK" and an actual error message in the response *body*.
  43   * apparently setting Content-Length works better, so we use that
  44 * Sharepoint returns redirect urls that curl can't parse, so we encode
  45   them (check `WebDAVResponseParser` for the code)
  46 * Sharepoint may reply to HEAD with 200 OK but then 404 NOT FOUND to PROPFIND
  47 * Sharepoint does not appear to support Dead Properties
  48 * avoiding chunked encoding for PUT, since for Nextcloud:
  49   * Transfer-Encoding: chunked creates a 0 byte file with response
  50     "201 Created"
  51   * see upstream bug: https://github.com/nextcloud/server/issues/7995
  52
  53 To a first approximation, there are 3 parts involved in the UCP:
  54
  55 * The upper layer implements the UNO API which is called by LibreOffice, and
  56   translates the calls from generic sequence-of-any stringly typed abstractness
  57   into HTTP or WebDAV protocol calls, and does some high level protocol
  58   handling to figure out what the server supports and so on. This is
  59   independent of the low-level library.
  60 * Then there is the lower layer of the UCP, which translates the generic HTTP
  61   or WebDAV protocol calls to something that the particular third-party library
  62   can understand, hook up its callbacks for data transfer and authentication,
  63   and parse the reply XML documents.
  64 * At the bottom, there is the third-party library that implements the HTTP
  65   protocol.
  66
  67 The most important classes are:
  68 * ContentProvider: the UNO entry point/factory, creates Content instances
  69 * Content: the main UNO service, translates the UCP API to WebDAV methods,
  70   one instance per URL
  71 * DAVResourceAccess: sits between Content and CurlSession
  72 * DAVSessionFactory: creates CurlSession for DAVResourceAccess
  73 * CurlSession: low-level interfacing with libcurl
  74 * SerfLockStore: singleton used by CurlSession to store DAV lock tokens, runs
  75   a thread to refresh locks when they expire
  76 * WebDAVResponseParser: parse XML responses to LOCK, PROPFIND requests
  77 * DAVAuthListener_Impl: request credentials from UI via UNO
  78