New Couchbase Lite C 3.2.2

Author: corentinmb

.gitignore

@@ -2,6 +2,7 @@
 Cargo.lock
 
 .vscode
+.idea
 
 # MacOS directory conf
 .DS_Store

Cargo.toml

@@ -2,7 +2,7 @@
 name = "couchbase_lite"
 description = "Rust bindings for Couchbase Lite C"
 # The first three numbers correspond to the Couchbase Lite C release, the fourth number corresponds to the Rust release
-version = "3.2.1-0"
+version = "3.2.2-0"
 
 edition = "2024"
 

README.md

@@ -47,10 +47,10 @@ The different releases can be found in [this page][CBL_DOWNLOAD_PAGE].
 When a new C release is available, a new Rust release must be created. Running the following script will download and setup the libraries locally:
 
 ```shell
-$ ./update_cblite_c.sh -v 3.2.1
+$ ./update_cblite_c.sh -v 3.2.2
 ```
 
-If the script fails on MacOS, you might need to install wget or a recent bash version:
+If the script fails (for example `declare: -A: invalid option`, you'll need bash >= version 4) on MacOS, you might need to install wget or a recent bash version:
 
 ```shell
 $ brew install wget
@@ -119,7 +119,7 @@ $ LSAN_OPTIONS=suppressions=san.supp RUSTFLAGS="-Zsanitizer=address" cargo +nigh
 
 [CBL_DOCS]: https://docs.couchbase.com/couchbase-lite/current/introduction.html
 
-[CBL_API_REFERENCE]: https://docs.couchbase.com/mobile/3.2.1/couchbase-lite-c/C/html/modules.html
+[CBL_API_REFERENCE]: https://docs.couchbase.com/mobile/3.2.2/couchbase-lite-c/C/html/modules.html
 
 [CBL_EDITIONS_DIFF]: https://www.couchbase.com/products/editions/
 

libcblite_community/include/cbl++/CouchbaseLite.hh

@@ -24,6 +24,7 @@
 #include "Collection.hh"
 #include "Database.hh"
 #include "Document.hh"
+#include "LogSinks.hh"
 #include "Prediction.hh"
 #include "Query.hh"
 #include "QueryIndex.hh"

libcblite_community/include/cbl++/LogSinks.hh

@@ -0,0 +1,56 @@
+//
+// LogSinks.hh
+//
+// Copyright (c) 2025 Couchbase, Inc All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// VOLATILE API: Couchbase Lite C++ API is not finalized, and may change in
+// future releases.
+
+#pragma once
+#include "cbl/CBLLogSinks.h"
+
+CBL_ASSUME_NONNULL_BEGIN
+
+namespace cbl {
+    class LogSinks {
+    public:
+        static void setConsole(const CBLConsoleLogSink& sink) {
+            CBLLogSinks_SetConsole(sink);
+        }
+        
+        static CBLConsoleLogSink console() {
+            return CBLLogSinks_Console();
+        }
+        
+        static void setCustom(const CBLCustomLogSink& sink) {
+            CBLLogSinks_SetCustom(sink);
+        }
+                
+        static CBLCustomLogSink custom() {
+            return CBLLogSinks_CustomSink();
+        }
+                
+        static void setFile(const CBLFileLogSink& sink) {
+            CBLLogSinks_SetFile(sink);
+        }
+                
+        static CBLFileLogSink file() {
+            return CBLLogSinks_File();
+        }
+    };
+}
+
+CBL_ASSUME_NONNULL_END

libcblite_community/include/cbl/CBLDefaults.h

@@ -65,6 +65,21 @@ CBL_PUBLIC extern const uint32_t kCBLDefaultLogFileMaxRotateCount;
 
 /** @} */
 
+/** \name CBLFileLogSink
+    @{
+*/
+
+/** [false] Plaintext is not used, and instead binary encoding is used in log files */
+CBL_PUBLIC extern const bool kCBLDefaultFileLogSinkUsePlaintext;
+
+/** [524288] 512 KiB for the size of a log file */
+CBL_PUBLIC extern const size_t kCBLDefaultFileLogSinkMaxSize;
+
+/** [2] 2 files preserved during each log rotation */
+CBL_PUBLIC extern const uint32_t kCBLDefaultFileLogSinkMaxKeptFiles;
+
+/** @} */
+
 /** \name CBLFullTextIndexConfiguration
     @{
 */

libcblite_community/include/cbl/CBLLog.h

@@ -18,32 +18,14 @@
 
 #pragma once
 #include "CBLBase.h"
+#include "CBLLogSinks.h"
 
 CBL_CAPI_BEGIN
 
-
-/** \defgroup logging   Logging
+/** \defgroup logging_deprecated   Logging (Deprecated)
      @{
-    Managing messages that Couchbase Lite logs at runtime. */
-
-/** Subsystems that log information. */
-typedef CBL_ENUM(uint8_t, CBLLogDomain) {
-    kCBLLogDomainDatabase,
-    kCBLLogDomainQuery,
-    kCBLLogDomainReplicator,
-    kCBLLogDomainNetwork
-};
-
-/** Levels of log messages. Higher values are more important/severe. Each level includes the lower ones. */
-typedef CBL_ENUM(uint8_t, CBLLogLevel) {
-    kCBLLogDebug,        ///< Extremely detailed messages, only written by debug builds of CBL.
-    kCBLLogVerbose,      ///< Detailed messages about normally-unimportant stuff.
-    kCBLLogInfo,         ///< Messages about ordinary behavior.
-    kCBLLogWarning,      ///< Messages warning about unlikely and possibly bad stuff.
-    kCBLLogError,        ///< Messages about errors
-    kCBLLogNone          ///< Disables logging entirely.
-};
-
+    Managing messages that Couchbase Lite logs at runtime.
+ */
 
 /** Formats and writes a message to the log, in the given domain at the given level.
     \warning This function takes a `printf`-style format string, with extra parameters to match the format placeholders, and has the same security vulnerabilities as other `printf`-style functions.
@@ -55,7 +37,8 @@ typedef CBL_ENUM(uint8_t, CBLLogLevel) {
     @param level  The severity of the message. If this is lower than the current minimum level for the domain
                  (as set by \ref CBLLog_SetConsoleLevel), nothing is logged.
     @param format  A `printf`-style format string. `%` characters in this string introduce parameters,
-                 and corresponding arguments must follow. */
+                 and corresponding arguments must follow.
+    @warning  <b>Deprecated :</b> No alternative for this function and this function will be removed in the future release. */
 void CBL_Log(CBLLogDomain domain,
              CBLLogLevel level,
              const char *format, ...) CBLAPI __printflike(3, 4);
@@ -64,56 +47,55 @@ void CBL_Log(CBLLogDomain domain,
     @param domain  The log domain to associate this message with.
     @param level  The severity of the message. If this is lower than the current minimum level for the domain
                  (as set by \ref CBLLog_SetConsoleLevel), nothing is logged.
-    @param message  The exact message to write to the log. */
+    @param message  The exact message to write to the log.
+    @warning  <b>Deprecated :</b> No alternative for this function and this function will be removed in the future release.*/
 void CBL_LogMessage(CBLLogDomain domain,
                     CBLLogLevel level,
                     FLSlice message) CBLAPI;
 
-
-
 /** \name Console Logging and Custom Logging
     @{ */
 
-/** A logging callback that the application can register.
-    @param domain  The domain of the message
-    @param level  The severity level of the message.
-    @param message  The actual formatted message. */
-typedef void (*CBLLogCallback)(CBLLogDomain domain,
-                               CBLLogLevel level,
-                               FLString message);
+/** A logging callback that the application can register. */
+typedef CBLLogSinkCallback CBLLogCallback;
 
 /** Gets the current log level for debug console logging.
-    Only messages at this level or higher will be logged to the console. */
+    Only messages at this level or higher will be logged to the console.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_Console instead. */
 CBLLogLevel CBLLog_ConsoleLevel(void) CBLAPI;
 
 /** Sets the detail level of logging.
-    Only messages whose level is ≥ the given level will be logged to the console. */
+    Only messages whose level is ≥ the given level will be logged to the console.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_SetConsole instead. */
 void CBLLog_SetConsoleLevel(CBLLogLevel) CBLAPI;
 
 /** Gets the current log level for debug console logging.
-    Only messages at this level or higher will be logged to the callback. */
+    Only messages at this level or higher will be logged to the callback.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_CustomSink instead. */
 CBLLogLevel CBLLog_CallbackLevel(void) CBLAPI;
 
 /** Sets the detail level of logging.
-    Only messages whose level is ≥ the given level will be logged to the callback. */
+    Only messages whose level is ≥ the given level will be logged to the callback.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_SetCustom instead. */
 void CBLLog_SetCallbackLevel(CBLLogLevel) CBLAPI;
 
-/** Gets the current log callback. */
+/** Gets the current log callback.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_CustomSink instead. */
 CBLLogCallback CBLLog_Callback(void) CBLAPI;
 
-/** Sets the callback for receiving log messages. If set to NULL, no messages are logged to the console. */
+/** Sets the callback for receiving log messages. If set to NULL, no messages are logged to the console.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_SetCustom instead. */
 void CBLLog_SetCallback(CBLLogCallback _cbl_nullable callback) CBLAPI;
 
 /** @} */
 
-
-
 /** \name Log File Configuration
     @{ */
 
 /** The properties for configuring logging to files.
     @warning `usePlaintext` results in significantly larger log files and higher CPU usage that may slow
-            down your app; we recommend turning it off in production. */
+            down your app; we recommend turning it off in production.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_SetFile instead. */
 typedef struct {
     CBLLogLevel level;       ///< The minimum level of message to write (Required).
 
@@ -132,10 +114,12 @@ typedef struct {
     bool usePlaintext;
 } CBLLogFileConfiguration;
 
-/** Gets the current file logging configuration, or NULL if none is configured. */
+/** Gets the current file logging configuration, or NULL if none is configured.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_File instead. */
 const CBLLogFileConfiguration* _cbl_nullable CBLLog_FileConfig(void) CBLAPI;
 
-/** Sets the file logging configuration, and begins logging to files. */
+/** Sets the file logging configuration, and begins logging to files.
+    @warning  <b>Deprecated :</b> Use CBLLogSinks_SetFile instead. */
 bool CBLLog_SetFileConfig(CBLLogFileConfiguration, CBLError* _cbl_nullable outError) CBLAPI;
 
 /** @} */

libcblite_community/include/cbl/CBLLogSinks.h

@@ -0,0 +1,120 @@
+//
+// CBLLogSink.h
+//
+// Copyright © 2024 Couchbase. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#pragma once
+#include "CBLBase.h"
+
+CBL_CAPI_BEGIN
+
+/** \defgroup logging   Logging (Deprecated)
+     @{
+     Manages Couchbase Lite logging configuration, with three log sinks:
+     - **Console Log Sink**: Enabled by default at the **warning** level for all domains.
+     - **Custom Log Sink**: Logs to a user-defined callback.
+     - **File Log Sink**: Logs to files with customizable settings.
+ */
+
+/** The severity level of log messages */
+typedef CBL_ENUM(uint8_t, CBLLogLevel) {
+    kCBLLogDebug,               ///< Debug-level messages with highly detailed information, Available only in debug builds of Couchbase Lite.
+    kCBLLogVerbose,             ///< Verbose messages providing detailed operational information.
+    kCBLLogInfo,                ///< Info messages about normal application behavior.
+    kCBLLogWarning,             ///< Warning messages indicating potential issues or unusual conditions.
+    kCBLLogError,               ///< Error messages indicating a failure or problem that occurred.
+    kCBLLogNone                 ///< Disables logging entirely. No messages will be logged.
+};
+
+/** Subsystems for logging messages. */
+typedef CBL_ENUM(uint8_t, CBLLogDomain) {
+    kCBLLogDomainDatabase,      ///< Logging domain for the database subsystem.
+    kCBLLogDomainQuery,         ///< Logging domain for the query subsystem.
+    kCBLLogDomainReplicator,    ///< Logging domain for the replicator subsystem.
+    kCBLLogDomainNetwork        ///< Logging domain for the network subsystem.
+};
+
+/** A bitmask representing a set of logging domains.
+ *
+ *  Use this bitmask to specify one or more logging domains by combining the
+ *  constants with the bitwise OR operator (`|`). This is helpful for enabling
+ *  or filtering logs for specific domains. */
+typedef CBL_OPTIONS(uint16_t, CBLLogDomainMask) {
+    kCBLLogDomainMaskDatabase   = 1 << kCBLLogDomainDatabase,
+    kCBLLogDomainMaskQuery      = 1 << kCBLLogDomainQuery,
+    kCBLLogDomainMaskReplicator = 1 << kCBLLogDomainReplicator,
+    kCBLLogDomainMaskNetwork    = 1 << kCBLLogDomainNetwork,
+    kCBLLogDomainMaskAll        = 0xFF
+};
+
+/** A callback function for a custom log sink.
+    @param domain  The domain of the message
+    @param level  The severity level of the message.
+    @param message  The actual formatted message. */
+typedef void (*CBLLogSinkCallback)(CBLLogDomain domain, CBLLogLevel level, FLString message);
+
+/** Console log sink configuration for logging to the cosole. */
+typedef struct {
+    CBLLogLevel level;                          ///< The minimum level of message to write (Required).
+    CBLLogDomainMask domains;                   ///< Bitmask for enabled log domains. Use zero for all domains.
+} CBLConsoleLogSink;
+
+/** Custom log sink configuration for logging to a user-defined callback. */
+typedef struct {
+    CBLLogLevel level;                          ///< The minimum level of message to write (Required).
+    CBLLogSinkCallback _cbl_nullable callback;  ///< Custom log callback (Required).
+    CBLLogDomainMask domains;                   ///< Bitmask for enabled log domains. Use zero for all domains.
+} CBLCustomLogSink;
+
+/** File log sink configuration for logging to files. */
+typedef struct {
+    CBLLogLevel level;                          ///< The minimum level of message to write (Required).
+    FLString directory;                         ///< The directory where log files will be created (Required).
+    
+    /** The maximum number of files to save per log level.
+        The default is \ref kCBLDefaultFileLogSinkMaxKeptFiles. */
+    uint32_t maxKeptFiles;
+    
+    /** The size in bytes at which a file will be rotated out (best effort).
+        The default is \ref kCBLDefaultFileLogSinkMaxSize. */
+    size_t maxSize;
+    
+    /** Whether or not to log in plaintext as opposed to binary. Plaintext logging is slower and bigger.
+        The default is \ref kCBLDefaultFileLogSinkUsePlaintext. */
+    bool usePlaintext;
+} CBLFileLogSink;
+
+/** Set the console log sink. To disable the console log sink, set the log level to kCBLLogNone. */
+void CBLLogSinks_SetConsole(CBLConsoleLogSink sink) CBLAPI;
+
+/** Get the current console log sink. The console log sink is enabled at the warning level for all domains by default. */
+CBLConsoleLogSink CBLLogSinks_Console(void) CBLAPI;
+
+/** Set the custom log sink. To disable the custom log sink, set the log level to kCBLLogNone. */
+void CBLLogSinks_SetCustom(CBLCustomLogSink sink) CBLAPI;
+
+/** Get the current custom log sink. The custom log sink is disabled by default. */
+CBLCustomLogSink CBLLogSinks_CustomSink(void) CBLAPI;
+
+/** Set the file log sink. To disable the file log sink, set the log level to kCBLLogNone. */
+void CBLLogSinks_SetFile(CBLFileLogSink sink) CBLAPI;
+
+/** Get the current custom log sink. The file log sink is disabled by default. */
+CBLFileLogSink CBLLogSinks_File(void) CBLAPI;
+
+CBL_CAPI_END
+
+/** @} */