Connected client and Async

C/Cpp_include/c4.hh

@@ -33,3 +33,4 @@
 #include "c4Query.hh"
 #include "c4Replicator.hh"
 #include "c4Socket.hh"
+#include "c4ConnectedClient.hh"

C/Cpp_include/c4ConnectedClient.hh

@@ -0,0 +1,125 @@
+//
+// c4ConnectedClient.hh
+//
+// Copyright 2022-Present Couchbase, Inc.
+//
+// Use of this software is governed by the Business Source License included
+// in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
+// in that file, in accordance with the Business Source License, use of this
+// software will be governed by the Apache License, Version 2.0, included in
+// the file licenses/APL2.txt.
+//
+
+#pragma once
+#include "c4Base.hh"
+#include "Async.hh"
+#include "c4ConnectedClientTypes.h"
+#include "fleece/Fleece.h"
+
+C4_ASSUME_NONNULL_BEGIN
+
+struct C4ConnectedClient  : public fleece::RefCounted,
+                            public fleece::InstanceCountedIn<C4Database>,
+                            C4Base
+{
+    /// Creates a new ConnectedClient
+    /// \note It will automatically starts the client, no need to call `start()`.
+    ///
+    /// @param params  Connected Client parameters.
+    /// @result A new \ref C4ConnectedClient, or NULL on failure.
+    static Retained<C4ConnectedClient> newClient(const C4ConnectedClientParameters &params);
+
+    /// The current connection status.
+    virtual litecore::actor::Async<C4ConnectedClientStatus> getStatus() const =0;
+
+    /// The HTTP response headers.
+    virtual alloc_slice getResponseHeaders() const noexcept =0;
+
+#ifdef COUCHBASE_ENTERPRISE
+    /// The server's TLS certificate.
+    virtual C4Cert* C4NULLABLE getPeerTLSCertificate() const =0;
+#endif
+
+    /// Result of a successful `getDoc()` call.
+    struct DocResponse {
+        alloc_slice docID, revID, body;
+        bool deleted;
+    };
+
+    /// Gets the current revision of a document from the server.
+    /// You can set the `unlessRevID` parameter to avoid getting a redundant copy of a
+    /// revision you already have.
+    /// @param docID  The document ID.
+    /// @param collectionID  The name of the document's collection, or `nullslice` for default.
+    /// @param unlessRevID  If non-null, and equal to the current server-side revision ID,
+    ///                   the server will return error {WebSocketDomain, 304}.
+    /// @param asFleece  If true, the response's `body` field is Fleece; if false, it's JSON.
+    /// @result An async value that, when resolved, contains either a `DocResponse` struct
+    ///          or a C4Error.
+    virtual litecore::actor::Async<DocResponse> getDoc(slice docID,
+                                                       slice collectionID,
+                                                       slice unlessRevID,
+                                                       bool asFleece)=0;
+
+    /// Pushes a new document revision to the server.
+    /// @param docID  The document ID.
+    /// @param collectionID  The name of the document's collection, or `nullslice` for default.
+    /// @param parentRevID The ID of the parent revision on the server,
+    ///                      or `nullslice` if this is a new document.
+    /// @param revisionFlags  Flags of this revision.
+    /// @param fleeceData  The document body encoded as Fleece (without shared keys!)
+    /// @return An async value that, when resolved, contains new revisionID or the status as a C4Error
+    virtual litecore::actor::Async<std::string> putDoc(slice docID,
+                                                       slice collectionID,
+                                                       slice parentRevID,
+                                                       C4RevisionFlags revisionFlags,
+                                                       slice fleeceData)=0;
+
+    /// Callback for \ref getAllDocIDs.
+    /// @param ids  A vector of docIDs; empty on the final call.
+    /// @param error  NULL or a pointer to an error.
+    using AllDocsReceiver = std::function<void(const std::vector<slice>& ids,
+                                               const C4Error* C4NULLABLE error)>;
+
+    /// Requests a list of all document IDs, or optionally only those matching a pattern.
+    /// The docIDs themselves are passed to a callback.
+    /// The callback will be called zero or more times with a non-empty vector of docIDs,
+    /// then once with an empty vector and an optional error.
+    /// @param collectionID  The ID of the collection to observe.
+    /// @param globPattern  Either `nullslice` or a glob-style pattern string (with `*` or
+    ///                     `?` wildcards) for docIDs to match.
+    /// @param callback  The callback to receive the docIDs.
+    virtual void getAllDocIDs(slice collectionID,
+                              slice globPattern,
+                              AllDocsReceiver callback) =0;
+
+    /// Callback for \ref query.
+    /// @param rowJSON  A row of the result, encoded as a JSON object.
+    ///             On the final call, will be `nullslice`.
+    /// @param rowDict  The row parsed as a Fleece Dict, if you requested it.
+    /// @param error  NULL or, on the final call, a pointer to an error.
+    using QueryReceiver = std::function<void(FLSlice rowJSON,
+                                             FLDict rowDict,
+                                             const C4Error* C4NULLABLE error)>;
+
+    /// Runs a query on the server and gets the results.
+    /// The callback will be called one or more times; see its documentation for details.
+    /// @param name  The name by which the query has been registered on the server;
+    ///              or a full query string beginning with "SELECT " or "{".
+    /// @param parameters  A Dict mapping query parameter names to values.
+    /// @param rowsAsFleece  True if you want the rows to be Fleece-encoded, false for JSON.
+    /// @param receiver  A callback that will be invoked for each row of the result,
+    ///                  and/or if there's an error.
+    virtual void query(slice name,
+                       FLDict C4NULLABLE parameters,
+                       bool rowsAsFleece,
+                       QueryReceiver receiver) =0;
+
+    /// Tells a connected client to start.
+    virtual void start()=0;
+
+    /// Tells a replicator to stop.
+    virtual void stop()=0;
+};
+
+C4_ASSUME_NONNULL_END

C/Cpp_include/c4Document.hh

@@ -146,12 +146,6 @@ struct C4Document : public fleece::RefCounted,
     /// Returns the Document instance, if any, that contains the given Fleece value.
     static C4Document* C4NULLABLE containingValue(FLValue) noexcept;
 
-    static bool isOldMetaProperty(slice propertyName) noexcept;
-    static bool hasOldMetaProperties(FLDict) noexcept;
-
-    static alloc_slice encodeStrippingOldMetaProperties(FLDict properties,
-                                                        FLSharedKeys);
-
     // Special property names & values:
 
     /** The Dict property that identifies it as a special type of object.

C/Cpp_include/c4EnumUtil.hh

@@ -11,6 +11,7 @@
 //
 
 #pragma once
+#include "c4Compat.h"
 #include <type_traits>
 
 /// Declares `++` and `--` functions for an `enum class`.

C/Doxyfile

@@ -597,7 +597,7 @@ SORT_MEMBERS_CTORS_1ST = NO
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -2039,6 +2039,7 @@ INCLUDE_FILE_PATTERNS  =
 
 PREDEFINED             = DOXYGEN_PARSING=1 \
                          C4API= \
+                         C4API_BEGIN_DECLS= \
                          C4NULLABLE= \
                          C4NONNULL= \
                          C4_RETURNS_NONNULL= \

C/DoxygenDependencies.txt

@@ -1,23 +1,32 @@
-$(SRCROOT)/../C/include/c4.h
+$(SRCROOT)/../C/Doxyfile
 $(SRCROOT)/../C/include/c4Base.h
 $(SRCROOT)/../C/include/c4BlobStore.h
+$(SRCROOT)/../C/include/c4BlobStoreTypes.h
 $(SRCROOT)/../C/include/c4Certificate.h
+$(SRCROOT)/../C/include/c4CertificateTypes.h
 $(SRCROOT)/../C/include/c4Collection.h
 $(SRCROOT)/../C/include/c4Compat.h
+$(SRCROOT)/../C/include/c4ConnectedClient.h
+$(SRCROOT)/../C/include/c4ConnectedClientTypes.h
 $(SRCROOT)/../C/include/c4Database.h
 $(SRCROOT)/../C/include/c4DatabaseTypes.h
 $(SRCROOT)/../C/include/c4DocEnumerator.h
 $(SRCROOT)/../C/include/c4DocEnumeratorTypes.h
 $(SRCROOT)/../C/include/c4Document+Fleece.h
 $(SRCROOT)/../C/include/c4Document.h
+$(SRCROOT)/../C/include/c4DocumentStruct.h
 $(SRCROOT)/../C/include/c4DocumentTypes.h
+$(SRCROOT)/../C/include/c4Error.h
 $(SRCROOT)/../C/include/c4Index.h
 $(SRCROOT)/../C/include/c4IndexTypes.h
 $(SRCROOT)/../C/include/c4Listener.h
+$(SRCROOT)/../C/include/c4ListenerTypes.h
+$(SRCROOT)/../C/include/c4Log.h
 $(SRCROOT)/../C/include/c4Observer.h
 $(SRCROOT)/../C/include/c4PredictiveQuery.h
 $(SRCROOT)/../C/include/c4Query.h
 $(SRCROOT)/../C/include/c4QueryTypes.h
 $(SRCROOT)/../C/include/c4Replicator.h
 $(SRCROOT)/../C/include/c4ReplicatorTypes.h
 $(SRCROOT)/../C/include/c4Socket.h
+$(SRCROOT)/../C/include/c4SocketTypes.h

C/c4.exp

@@ -417,5 +417,11 @@ _FLDictIterator_End
 _FLValue_IsEqual
 _FLValue_ToJSON5
 
+_c4client_new
+_c4client_getDoc
+_c4client_start
+_c4client_stop
+_c4client_putDoc
+
 # Apple specific
 _FLEncoder_WriteNSObject

C/c4CAPI.cc

@@ -21,6 +21,7 @@
 #include "c4Query.hh"
 #include "c4QueryImpl.hh"
 #include "c4Replicator.hh"
+#include "LegacyAttachments.hh"
 
 #include "c4.h"
 #include "c4Private.h"
@@ -1102,12 +1103,12 @@ FLSharedKeys c4db_getFLSharedKeys(C4Database *db) noexcept {
 
 
 bool c4doc_isOldMetaProperty(C4String prop) noexcept {
-    return C4Document::isOldMetaProperty(prop);
+    return legacy_attachments::isOldMetaProperty(prop);
 }
 
 
 bool c4doc_hasOldMetaProperties(FLDict doc) noexcept {
-    return C4Document::hasOldMetaProperties(doc);
+    return legacy_attachments::hasOldMetaProperties(doc);
 }
 
 
@@ -1152,7 +1153,7 @@ bool c4doc_blobIsCompressible(FLDict blobDict) {
 
 C4SliceResult c4doc_encodeStrippingOldMetaProperties(FLDict doc, FLSharedKeys sk, C4Error *outError) noexcept {
     return tryCatch<C4SliceResult>(outError, [&]{
-        return C4SliceResult(C4Document::encodeStrippingOldMetaProperties(doc, sk));
+        return C4SliceResult(legacy_attachments::encodeStrippingOldMetaProperties(doc, sk));
     });
 }
 

C/c4Document.cc

@@ -361,19 +361,3 @@ C4RevisionFlags C4Document::revisionFlagsFromDocFlags(C4DocumentFlags docFlags)
 C4Document* C4Document::containingValue(FLValue value) noexcept {
     return C4Collection::documentContainingValue(value);
 }
-
-
-bool C4Document::isOldMetaProperty(slice propertyName) noexcept {
-    return legacy_attachments::isOldMetaProperty(propertyName);
-}
-
-
-bool C4Document::hasOldMetaProperties(FLDict dict) noexcept {
-    return legacy_attachments::hasOldMetaProperties((const fleece::impl::Dict*)dict);
-}
-
-
-alloc_slice C4Document::encodeStrippingOldMetaProperties(FLDict properties, FLSharedKeys sk) {
-    return legacy_attachments::encodeStrippingOldMetaProperties((const fleece::impl::Dict*)properties,
-                                                                (fleece::impl::SharedKeys*)sk);
-}

C/c4Error.cc

@@ -225,31 +225,30 @@ C4Error C4Error::fromException(const exception &x) noexcept {
 
 __cold
 C4Error C4Error::fromCurrentException() noexcept {
-    // This rigamarole recovers the current exception being thrown...
-    auto xp = std::current_exception();
-    if (xp) {
-        try {
-            std::rethrow_exception(xp);
-        } catch(const std::exception& x) {
-            // Now we have the exception, so we can record it in outError:
-            return C4Error::fromException(x);
-        } catch (...) { }
+    return fromException(error::convertCurrentException());
+}
+
+
+static string getMessage(const C4Error &c4err) {
+    auto info = ErrorTable::instance().copy(c4err);
+    return info ? info->message : "";
+}
+
+
+namespace litecore {
+    // Declared in Error.hh
+    error::error(const C4Error &c4err)
+    :error(error::Domain(c4err.domain), c4err.code, getMessage(c4err))
+    {
+        if (auto info = ErrorTable::instance().copy(c4err))
+            backtrace = info->backtrace;
     }
-    return ErrorTable::instance().makeError(
-                                            LiteCoreDomain, kC4ErrorUnexpectedError,
-                                            {"Unknown C++ exception", Backtrace::capture(1)});
 }
 
 
 [[noreturn]] __cold
 void C4Error::raise() const {
-    if (auto info = ErrorTable::instance().copy(*this); info) {
-        error e(error::Domain(domain), code, info->message);
-        e.backtrace = info->backtrace;
-        throw e;
-    } else {
-        error::_throw(error::Domain(domain), code);
-    }
+    throw litecore::error(*this);
 }
 
 

C/c4_ee.exp

@@ -458,6 +458,12 @@ _FLDictIterator_End
 _FLValue_IsEqual
 _FLValue_ToJSON5
 
+_c4client_new
+_c4client_getDoc
+_c4client_start
+_c4client_stop
+_c4client_putDoc
+
 
 _c4db_URINameFromPath
 

C/include/c4.h

@@ -25,3 +25,4 @@
 #include "c4Query.h"
 #include "c4Replicator.h"
 #include "c4Socket.h"
+#include "c4ConnectedClient.h"

C/include/c4Base.h

@@ -27,10 +27,10 @@ C4API_BEGIN_DECLS
 
 // Corresponds to Couchbase Lite product version number, with 2 digits for minor and patch versions.
 // i.e. `10000 * MajorVersion + 100 * MinorVersion + PatchVersion`
-#define LITECORE_VERSION 30000
+#define LITECORE_VERSION 30100
 
 // This number has no absolute meaning but is bumped whenever the LiteCore public API changes.
-#define LITECORE_API_VERSION 351
+#define LITECORE_API_VERSION 352
 
 
 /** \defgroup Base  Data Types and Base Functions
@@ -117,6 +117,9 @@ typedef struct C4Cert C4Cert;
 /** Opaque handle to a namespace of documents in an opened database. */
 typedef struct C4Collection C4Collection;
 
+/** Opaque reference to a Connected Client. */
+typedef struct C4ConnectedClient C4ConnectedClient;
+
 /** A collection-observer reference. */
 typedef struct C4CollectionObserver C4CollectionObserver;
 
@@ -182,6 +185,8 @@ static inline C4Cert* C4NULLABLE
     c4cert_retain(C4Cert* C4NULLABLE r) C4API       {return (C4Cert*)c4base_retain(r);}
 static inline C4Collection* C4NULLABLE
     c4coll_retain(C4Collection* C4NULLABLE r) C4API {return (C4Collection*)c4base_retain(r);}
+static inline C4ConnectedClient* C4NULLABLE
+    c4client_retain(C4ConnectedClient* C4NULLABLE r) C4API {return (C4ConnectedClient*)c4base_retain(r);}
 static inline C4Database* C4NULLABLE
     c4db_retain(C4Database* C4NULLABLE r) C4API     {return (C4Database*)c4base_retain(r);}
 static inline C4KeyPair* C4NULLABLE
@@ -197,6 +202,7 @@ CBL_CORE_API C4Socket* C4NULLABLE
     c4socket_retain(C4Socket* C4NULLABLE) C4API;
 
 static inline void c4cert_release   (C4Cert* C4NULLABLE r) C4API       {c4base_release(r);}
+static inline void c4client_release (C4ConnectedClient* C4NULLABLE r) C4API {c4base_release(r);}
 static inline void c4coll_release   (C4Collection* C4NULLABLE r) C4API {c4base_release(r);}
 static inline void c4db_release     (C4Database* C4NULLABLE r) C4API   {c4base_release(r);}
 static inline void c4keypair_release(C4KeyPair* C4NULLABLE r) C4API    {c4base_release(r);}