diff options
Diffstat (limited to '')
| -rw-r--r-- | ucb/README.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/ucb/README.md b/ucb/README.md new file mode 100644 index 000000000..d77656104 --- /dev/null +++ b/ucb/README.md @@ -0,0 +1,78 @@ +# Universal Content Broker (UCB) + +Universal Content Broker (has ucps) which do things like convert files +to strings in content broker world, or connect LibreOffice with +various DMS and fileshare systems like WebDAV, CMIS, or GIO. + +The UCPs implement the Universal Content Provider UNO interfaces in +C++, in particular the `com.sun.star.ucb.ContentProvider` service. + +## WebDAV UCP + +The WebDAV content provider is based on `libcurl` for much of the +network and protocol stuff, including authentication. + +WebDAV as implemented here is defined in an IETF RFC 4918 extensions, +and the code supports both unencrypted HTTP/1.1 (IETF RFC 2616) as +well as TLS 1.2 or later. + +Our WebDAV `com.sun.star.ucb.ContentProvider` service implementation +registers the `vnd.sun.star.webdav` and `http` URI schemes (and their +encrypted TLS variants). See here for the specification: +https://wiki.documentfoundation.org/Documentation/DevGuide/Universal_Content_Providers#The_WebDAV_Content_Provider + +Historically, webdav had two ucps, one based on `neon`, the second one +based on `serf`. Both are superseded by the current `libcurl` +implementation (since LibreOffice 7.3), but in case of behavioural +differences, go hunt for code differences (ucb/source/ucp/webdav-neon +and ucb/source/ucp/webdav). + +The WebDAV protocol is implemented on top of libcurl basic http GET, +PUT, and POST requests (and is relatively straight-forward - see +`ucb/source/ucp/webdav-curl/webdavcontent.cxx` for the main +functionality), but incorporates custom handling for a number of +server idiosyncrasies: + +* Nextcloud will reply to a PROPFIND request with "100 Continue" and + then after the data is uploaded it will send a "401 Unauthorized" if + the auth header is missing in the headers to which it replied with + "100 Continue". +* Sharepoint 16 responds to PROPFIND, PROPPATCH and LOCK with + "Transfer-Encoding: chunked" + with "HTTP/1.1 200 OK" and an actual error message in the response *body*. + * apparently setting Content-Length works better, so we use that +* Sharepoint returns redirect urls that curl can't parse, so we encode + them (check `WebDAVResponseParser` for the code) +* Sharepoint may reply to HEAD with 200 OK but then 404 NOT FOUND to PROPFIND +* Sharepoint does not appear to support Dead Properties +* avoiding chunked encoding for PUT, since for Nextcloud: + * Transfer-Encoding: chunked creates a 0 byte file with response + "201 Created" + * see upstream bug: https://github.com/nextcloud/server/issues/7995 + +To a first approximation, there are 3 parts involved in the UCP: + +* The upper layer implements the UNO API which is called by LibreOffice, and + translates the calls from generic sequence-of-any stringly typed abstractness + into HTTP or WebDAV protocol calls, and does some high level protocol + handling to figure out what the server supports and so on. This is + independent of the low-level library. +* Then there is the lower layer of the UCP, which translates the generic HTTP + or WebDAV protocol calls to something that the particular third-party library + can understand, hook up its callbacks for data transfer and authentication, + and parse the reply XML documents. +* At the bottom, there is the third-party library that implements the HTTP + protocol. + +The most important classes are: +* ContentProvider: the UNO entry point/factory, creates Content instances +* Content: the main UNO service, translates the UCP API to WebDAV methods, + one instance per URL +* DAVResourceAccess: sits between Content and CurlSession +* DAVSessionFactory: creates CurlSession for DAVResourceAccess +* CurlSession: low-level interfacing with libcurl +* SerfLockStore: singleton used by CurlSession to store DAV lock tokens, runs + a thread to refresh locks when they expire +* WebDAVResponseParser: parse XML responses to LOCK, PROPFIND requests +* DAVAuthListener_Impl: request credentials from UI via UNO + |