[ECO-4998] feat: add logger abstraction

chat-android/build.gradle.kts

@@ -27,6 +27,7 @@ android {
     }
 
     compileOptions {
+        isCoreLibraryDesugaringEnabled = true
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17
     }
@@ -45,7 +46,7 @@ buildConfig {
 dependencies {
     api(libs.ably.android)
     implementation(libs.gson)
-
+    coreLibraryDesugaring(libs.desugar.jdk.libs)
     testImplementation(libs.junit)
     testImplementation(libs.mockk)
     testImplementation(libs.coroutine.test)

chat-android/src/main/java/com/ably/chat/ChatApi.kt

@@ -15,7 +15,11 @@ private const val PROTOCOL_VERSION_PARAM_NAME = "v"
 private const val RESERVED_ABLY_CHAT_KEY = "ably-chat"
 private val apiProtocolParam = Param(PROTOCOL_VERSION_PARAM_NAME, API_PROTOCOL_VERSION.toString())
 
-internal class ChatApi(private val realtimeClient: RealtimeClient, private val clientId: String) {
+internal class ChatApi(
+    private val realtimeClient: RealtimeClient,
+    private val clientId: String,
+    private val logger: Logger,
+) {
 
     /**
      * Get messages from the Chat Backend
@@ -134,6 +138,15 @@ internal class ChatApi(private val realtimeClient: RealtimeClient, private val c
                 }
 
                 override fun onError(reason: ErrorInfo?) {
+                    logger.error(
+                        "ChatApi.makeAuthorizedRequest(); failed to make request",
+                        contextMap = mapOf(
+                            "url" to url,
+                            "statusCode" to reason?.statusCode.toString(),
+                            "errorCode" to reason?.code.toString(),
+                            "errorMessage" to reason?.message.toString(),
+                        ),
+                    )
                     // (CHA-M3e)
                     continuation.resumeWithException(AblyException.fromErrorInfo(reason))
                 }
@@ -159,6 +172,15 @@ internal class ChatApi(private val realtimeClient: RealtimeClient, private val c
                 }
 
                 override fun onError(reason: ErrorInfo?) {
+                    logger.error(
+                        "ChatApi.makeAuthorizedPaginatedRequest(); failed to make request",
+                        contextMap = mapOf(
+                            "url" to url,
+                            "statusCode" to reason?.statusCode.toString(),
+                            "errorCode" to reason?.code.toString(),
+                            "errorMessage" to reason?.message.toString(),
+                        ),
+                    )
                     continuation.resumeWithException(AblyException.fromErrorInfo(reason))
                 }
             },

chat-android/src/main/java/com/ably/chat/ChatClient.kt

@@ -45,7 +45,17 @@ internal class DefaultChatClient(
     override val clientOptions: ClientOptions,
 ) : ChatClient {
 
-    private val chatApi = ChatApi(realtime, clientId)
+    private val logger: Logger = if (clientOptions.logHandler != null) {
+        CustomLogger(
+            clientOptions.logHandler,
+            clientOptions.logLevel,
+            LogContext(tag = "ChatClient", instanceId = generateUUID(), clientId = clientId),
+        )
+    } else {
+        AndroidLogger(clientOptions.logLevel, LogContext(tag = "ChatClient", instanceId = generateUUID(), clientId = clientId))
+    }
+
+    private val chatApi = ChatApi(realtime, clientId, logger.withContext(tag = "AblyChatAPI"))
 
     override val rooms: Rooms = DefaultRooms(
         realtimeClient = realtime,

chat-android/src/main/java/com/ably/chat/ClientOptions.kt

@@ -1,7 +1,5 @@
 package com.ably.chat
 
-import io.ably.lib.util.Log.LogHandler
-
 /**
  * Configuration options for the chat client.
  */

chat-android/src/main/java/com/ably/chat/Logger.kt

@@ -0,0 +1,119 @@
+package com.ably.chat
+
+import android.util.Log
+import java.time.LocalDateTime
+
+fun interface LogHandler {
+    fun log(message: String, level: LogLevel, throwable: Throwable?, context: LogContext)
+}
+
+data class LogContext(
+    val tag: String,
+    val clientId: String,
+    val instanceId: String,
+    val contextMap: Map<String, String> = mapOf(),
+)
+
+internal interface Logger {
+    val context: LogContext
+    fun withContext(tag: String? = null, contextMap: Map<String, String> = mapOf()): Logger
+    fun log(
+        message: String,
+        level: LogLevel,
+        throwable: Throwable? = null,
+        newTag: String? = null,
+        newContextMap: Map<String, String> = mapOf(),
+    )
+}
+
+internal fun Logger.trace(message: String, throwable: Throwable? = null, tag: String? = null, contextMap: Map<String, String> = mapOf()) {
+    log(message, LogLevel.Trace, throwable, tag, contextMap)
+}
+
+internal fun Logger.debug(message: String, throwable: Throwable? = null, tag: String? = null, contextMap: Map<String, String> = mapOf()) {
+    log(message, LogLevel.Debug, throwable, tag, contextMap)
+}
+
+internal fun Logger.info(message: String, throwable: Throwable? = null, tag: String? = null, contextMap: Map<String, String> = mapOf()) {
+    log(message, LogLevel.Info, throwable, tag, contextMap)
+}
+
+internal fun Logger.warn(message: String, throwable: Throwable? = null, tag: String? = null, contextMap: Map<String, String> = mapOf()) {
+    log(message, LogLevel.Warn, throwable, tag, contextMap)
+}
+
+internal fun Logger.error(message: String, throwable: Throwable? = null, tag: String? = null, contextMap: Map<String, String> = mapOf()) {
+    log(message, LogLevel.Error, throwable, tag, contextMap)
+}
+
+internal fun LogContext.mergeWith(tag: String? = null, contextMap: Map<String, String> = mapOf()): LogContext {
+    return LogContext(
+        tag = tag ?: this.tag,
+        instanceId = instanceId,
+        clientId = clientId,
+        contextMap = this.contextMap + contextMap,
+    )
+}
+
+internal class AndroidLogger(
+    private val minimalVisibleLogLevel: LogLevel,
+    override val context: LogContext,
+) : Logger {
+
+    override fun withContext(newTag: String?, newContextMap: Map<String, String>): Logger {
+        return AndroidLogger(
+            minimalVisibleLogLevel = minimalVisibleLogLevel,
+            context = context.mergeWith(newTag, newContextMap),
+        )
+    }
+
+    override fun log(message: String, level: LogLevel, throwable: Throwable?, newTag: String?, newContextMap: Map<String, String>) {
+        if (level.logLevelValue <= minimalVisibleLogLevel.logLevelValue) return
+        val finalContext = context.mergeWith(newTag, newContextMap)
+        val tag = finalContext.tag
+        val contextMap = finalContext.contextMap + ("instanceId" to finalContext.instanceId)
+
+        val contextString = ", context: $contextMap"
+        val formattedMessage = "[${LocalDateTime.now()}] ${level.name} ably-chat: ${message}$contextString"
+        when (level) {
+            // We use Logcat's info level for Trace and Debug
+            LogLevel.Trace -> Log.i(tag, formattedMessage, throwable)
+            LogLevel.Debug -> Log.i(tag, formattedMessage, throwable)
+            LogLevel.Info -> Log.i(tag, formattedMessage, throwable)
+            LogLevel.Warn -> Log.w(tag, formattedMessage, throwable)
+            LogLevel.Error -> Log.e(tag, formattedMessage, throwable)
+            LogLevel.Silent -> {}
+        }
+    }
+}
+
+internal class CustomLogger(
+    private val logHandler: LogHandler,
+    private val minimalVisibleLogLevel: LogLevel,
+    override val context: LogContext,
+) : Logger {
+
+    override fun withContext(tag: String?, contextMap: Map<String, String>): Logger {
+        return CustomLogger(
+            logHandler = logHandler,
+            minimalVisibleLogLevel = minimalVisibleLogLevel,
+            context = context.mergeWith(tag, contextMap),
+        )
+    }
+
+    override fun log(message: String, level: LogLevel, throwable: Throwable?, newTag: String?, newContextMap: Map<String, String>) {
+        if (level.logLevelValue <= minimalVisibleLogLevel.logLevelValue) return
+        val finalContext = context.mergeWith(newTag, newContextMap)
+        logHandler.log(
+            message = message,
+            level = level,
+            throwable = throwable,
+            context = finalContext,
+        )
+    }
+}
+
+internal class EmptyLogger(override val context: LogContext) : Logger {
+    override fun withContext(newTag: String?, newContextMap: Map<String, String>): Logger = this
+    override fun log(message: String, level: LogLevel, throwable: Throwable?, newTag: String?, newContextMap: Map<String, String>) = Unit
+}

chat-android/src/main/java/com/ably/chat/Utils.kt

@@ -5,6 +5,7 @@ import io.ably.lib.realtime.CompletionListener
 import io.ably.lib.types.AblyException
 import io.ably.lib.types.ChannelOptions
 import io.ably.lib.types.ErrorInfo
+import java.util.UUID
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 import kotlin.coroutines.suspendCoroutine
@@ -47,6 +48,8 @@ fun ChatChannelOptions(init: (ChannelOptions.() -> Unit)? = null): ChannelOption
     return options
 }
 
+fun generateUUID() = UUID.randomUUID().toString()
+
 /**
  * A value that can be evaluated at a later time, similar to `kotlinx.coroutines.Deferred` or a JavaScript Promise.
  *

chat-android/src/test/java/com/ably/chat/ChatApiTest.kt

@@ -13,7 +13,8 @@ import org.junit.Test
 class ChatApiTest {
 
     private val realtime = mockk<RealtimeClient>(relaxed = true)
-    private val chatApi = ChatApi(realtime, "clientId")
+    private val chatApi =
+        ChatApi(realtime, "clientId", logger = EmptyLogger(LogContext(tag = "TEST", instanceId = generateUUID(), clientId = "clientId")))
 
     /**
      * @nospec

chat-android/src/test/java/com/ably/chat/MessagesTest.kt

@@ -28,7 +28,8 @@ class MessagesTest {
     private val realtimeClient = mockk<RealtimeClient>(relaxed = true)
     private val realtimeChannels = mockk<Channels>(relaxed = true)
     private val realtimeChannel = spyk<Channel>(buildRealtimeChannel())
-    private val chatApi = spyk(ChatApi(realtimeClient, "clientId"))
+    private val chatApi =
+        spyk(ChatApi(realtimeClient, "clientId", EmptyLogger(LogContext(tag = "TEST", instanceId = generateUUID(), clientId = "clientId"))))
     private lateinit var messages: DefaultMessages
 
     private val channelStateListenerSlot = slot<ChannelStateListener>()

example/build.gradle.kts

@@ -37,6 +37,7 @@ android {
         }
     }
     compileOptions {
+        isCoreLibraryDesugaringEnabled = true
         sourceCompatibility = JavaVersion.VERSION_1_8
         targetCompatibility = JavaVersion.VERSION_1_8
     }
@@ -67,6 +68,7 @@ dependencies {
     implementation(libs.androidx.ui.graphics)
     implementation(libs.androidx.ui.tooling.preview)
     implementation(libs.androidx.material3)
+    coreLibraryDesugaring(libs.desugar.jdk.libs)
     testImplementation(libs.junit)
     androidTestImplementation(libs.androidx.junit)
     androidTestImplementation(libs.androidx.espresso.core)

gradle/libs.versions.toml

@@ -4,6 +4,7 @@
 [versions]
 ably-chat = "0.0.1"
 ably = "1.2.43"
+desugar-jdk-libs = "2.1.2"
 junit = "4.13.2"
 agp = "8.5.2"
 detekt = "1.23.6"
@@ -21,6 +22,7 @@ coroutine = "1.8.1"
 build-config = "5.4.0"
 
 [libraries]
+desugar-jdk-libs = { module = "com.android.tools:desugar_jdk_libs", version.ref = "desugar-jdk-libs" }
 junit = { group = "junit", name = "junit", version.ref = "junit" }
 detekt-formatting = { module = "io.gitlab.arturbosch.detekt:detekt-formatting", version.ref = "detekt" }
 ably-android = { module = "io.ably:ably-android", version.ref = "ably" }