Restructure logger implementation to reduce published API surface

Author: hermannm

api/devlog-kotlin.api

@@ -20,7 +20,6 @@ public final class dev/hermannm/devlog/LogBuilder {
 	public static final fun addLogFieldOfType-impl (Ldev/hermannm/devlog/LogEvent;Ljava/lang/String;Ljava/lang/Object;Lkotlin/reflect/KType;)V
 	public static final fun addStringLogField-impl (Ldev/hermannm/devlog/LogEvent;Ljava/lang/String;Ljava/lang/Object;)V
 	public static final synthetic fun box-impl (Ldev/hermannm/devlog/LogEvent;)Ldev/hermannm/devlog/LogBuilder;
-	public static fun constructor-impl (Ldev/hermannm/devlog/LogEvent;)Ldev/hermannm/devlog/LogEvent;
 	public fun equals (Ljava/lang/Object;)Z
 	public static fun equals-impl (Ldev/hermannm/devlog/LogEvent;Ljava/lang/Object;)Z
 	public static final fun equals-impl0 (Ldev/hermannm/devlog/LogEvent;Ldev/hermannm/devlog/LogEvent;)Z
@@ -29,22 +28,13 @@ public final class dev/hermannm/devlog/LogBuilder {
 	public static fun hashCode-impl (Ldev/hermannm/devlog/LogEvent;)I
 	public static final fun rawJsonField-impl (Ldev/hermannm/devlog/LogEvent;Ljava/lang/String;Ljava/lang/String;Z)V
 	public static synthetic fun rawJsonField-impl$default (Ldev/hermannm/devlog/LogEvent;Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)V
-	public static final fun setCause-impl (Ldev/hermannm/devlog/LogEvent;Ljava/lang/Throwable;Lorg/slf4j/Logger;)V
 	public fun toString ()Ljava/lang/String;
 	public static fun toString-impl (Ldev/hermannm/devlog/LogEvent;)Ljava/lang/String;
 	public final synthetic fun unbox-impl ()Ldev/hermannm/devlog/LogEvent;
 }
 
-public abstract interface class dev/hermannm/devlog/LogEvent {
-	public abstract fun addJsonField (Ljava/lang/String;Ljava/lang/String;)V
-	public abstract fun addStringField (Ljava/lang/String;Ljava/lang/String;)V
-	public abstract fun handlesExceptionTreeTraversal ()Z
-	public abstract fun log (Ljava/lang/String;Lorg/slf4j/Logger;)V
-	public abstract fun setCause-ARkn0dU (Ljava/lang/Throwable;Lorg/slf4j/Logger;Ldev/hermannm/devlog/LogEvent;)V
-}
-
-public final class dev/hermannm/devlog/LogEventJvm {
-	public static final fun createLogEvent (Ldev/hermannm/devlog/LogLevel;Lorg/slf4j/Logger;)Ldev/hermannm/devlog/LogEvent;
+public final class dev/hermannm/devlog/LogBuilderKt {
+	public static final fun createLogBuilder-kpOQkOI (Ldev/hermannm/devlog/LogLevel;Lorg/slf4j/Logger;)Ldev/hermannm/devlog/LogEvent;
 }
 
 public final class dev/hermannm/devlog/LogField {
@@ -97,7 +87,7 @@ public final class dev/hermannm/devlog/Logger {
 	public static final fun isInfoEnabled-impl (Lorg/slf4j/Logger;)Z
 	public static final fun isTraceEnabled-impl (Lorg/slf4j/Logger;)Z
 	public static final fun isWarnEnabled-impl (Lorg/slf4j/Logger;)Z
-	public static final fun log-impl (Lorg/slf4j/Logger;Ldev/hermannm/devlog/LogLevel;Ljava/lang/Throwable;Lkotlin/jvm/functions/Function1;)V
+	public static final fun log-aaf-xeU (Lorg/slf4j/Logger;Ldev/hermannm/devlog/LogEvent;Ljava/lang/String;Ljava/lang/Throwable;)V
 	public fun toString ()Ljava/lang/String;
 	public static fun toString-impl (Lorg/slf4j/Logger;)Ljava/lang/String;
 	public static final fun trace-impl (Lorg/slf4j/Logger;Ljava/lang/Throwable;Lkotlin/jvm/functions/Function1;)V

src/commonMain/kotlin/dev/hermannm/devlog/LogBuilder.kt

@@ -35,9 +35,8 @@ import kotlinx.serialization.serializer
  */
 @kotlin.jvm.JvmInline // Inline value class, to wrap the underlying log event without overhead
 public value class LogBuilder
-@PublishedApi
 internal constructor(
-    @PublishedApi internal val logEvent: LogEvent,
+    internal val logEvent: LogEvent,
 ) {
   /**
    * Adds a [log field][LogField] (structured key-value data) to the log.
@@ -336,7 +335,6 @@ internal constructor(
    * Checks if the log cause exception (or any of its own cause exceptions) implements the
    * [HasLoggingContext] interface, and if so, adds those fields to the log.
    */
-  @PublishedApi
   internal fun setCause(cause: Throwable, logger: PlatformLogger) {
     logEvent.setCause(cause, logger, this)
 
@@ -368,3 +366,8 @@ internal constructor(
     }
   }
 }
+
+@PublishedApi
+internal fun createLogBuilder(level: LogLevel, logger: Logger): LogBuilder {
+  return LogBuilder(createLogEvent(level, logger.underlyingLogger))
+}

src/commonMain/kotlin/dev/hermannm/devlog/LogEvent.kt

@@ -19,7 +19,6 @@ package dev.hermannm.devlog
  * `Slf4jLogEvent`. [LogEvent] is the common interface between the two, so that [LogBuilder] can
  * call this interface without having to care about the underlying implementation.
  */
-@PublishedApi
 internal interface LogEvent {
   /**
    * @param logger We pass the logger so that the implementation has access to it if necessary (our
@@ -36,11 +35,11 @@ internal interface LogEvent {
   fun log(message: String, logger: PlatformLogger)
 
   /**
-   * Normally, [LogBuilder.setCause] would traverse the tree of exceptions from a cause exception,
-   * checking for [ExceptionWithLoggingContext] and [LoggingContextProvider]. But some `LogEvent`
-   * implementations, namely our `LogbackLogEvent`, does its own exception traversal already.
-   * Instead of traversing exceptions twice, we let the log event implementation set this flag to
-   * true if it takes care of it itself.
+   * Normally, [LogBuilder.traverseExceptionTreeForLogFields] would traverse the tree of exceptions
+   * from a cause exception, checking for [ExceptionWithLoggingContext] and
+   * [LoggingContextProvider]. But some `LogEvent` implementations, namely our `LogbackLogEvent`,
+   * does its own exception traversal already. Instead of traversing exceptions twice, we let the
+   * log event implementation set this flag to true if it takes care of it itself.
    */
   fun handlesExceptionTreeTraversal(): Boolean
 }
@@ -51,4 +50,4 @@ internal interface LogEvent {
  * On the JVM, this returns an SLF4J `LoggingEvent`, or a specialized optimized version for Logback
  * if Logback is used as the logging backend.
  */
-@PublishedApi internal expect fun createLogEvent(level: LogLevel, logger: PlatformLogger): LogEvent
+internal expect fun createLogEvent(level: LogLevel, logger: PlatformLogger): LogEvent

src/commonMain/kotlin/dev/hermannm/devlog/Logger.kt

@@ -53,7 +53,7 @@ import kotlin.reflect.KClass
 @kotlin.jvm.JvmInline // Inline value class, to wrap the underlying platform logger without overhead
 public value class Logger
 internal constructor(
-    @PublishedApi internal val underlyingLogger: PlatformLogger,
+    internal val underlyingLogger: PlatformLogger,
 ) {
   /**
    * Calls the given lambda to build a log message, and logs it at [LogLevel.INFO], if enabled.
@@ -96,8 +96,10 @@ internal constructor(
       cause: Throwable? = null,
       buildLog: LogBuilder.() -> String,
   ) {
-    if (underlyingLogger.isInfoEnabled()) {
-      log(LogLevel.INFO, cause, buildLog)
+    if (isInfoEnabled) {
+      val builder = createLogBuilder(LogLevel.INFO, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
@@ -146,8 +148,10 @@ internal constructor(
       cause: Throwable? = null,
       buildLog: LogBuilder.() -> String,
   ) {
-    if (underlyingLogger.isWarnEnabled()) {
-      log(LogLevel.WARN, cause, buildLog)
+    if (isWarnEnabled) {
+      val builder = createLogBuilder(LogLevel.WARN, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
@@ -196,8 +200,10 @@ internal constructor(
       cause: Throwable? = null,
       buildLog: LogBuilder.() -> String,
   ) {
-    if (underlyingLogger.isErrorEnabled()) {
-      log(LogLevel.ERROR, cause, buildLog)
+    if (isErrorEnabled) {
+      val builder = createLogBuilder(LogLevel.ERROR, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
@@ -242,8 +248,10 @@ internal constructor(
       cause: Throwable? = null,
       buildLog: LogBuilder.() -> String,
   ) {
-    if (underlyingLogger.isDebugEnabled()) {
-      log(LogLevel.DEBUG, cause, buildLog)
+    if (isDebugEnabled) {
+      val builder = createLogBuilder(LogLevel.DEBUG, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
@@ -288,8 +296,10 @@ internal constructor(
       cause: Throwable? = null,
       buildLog: LogBuilder.() -> String,
   ) {
-    if (underlyingLogger.isTraceEnabled()) {
-      log(LogLevel.TRACE, cause, buildLog)
+    if (isTraceEnabled) {
+      val builder = createLogBuilder(LogLevel.TRACE, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
@@ -344,24 +354,23 @@ internal constructor(
       buildLog: LogBuilder.() -> String,
   ) {
     if (isEnabledFor(level)) {
-      log(level, cause, buildLog)
+      val builder = createLogBuilder(level, this)
+      val message = builder.buildLog()
+      log(builder, message, cause)
     }
   }
 
   @PublishedApi
-  internal inline fun log(
-      level: LogLevel,
+  internal fun log(
+      logBuilder: LogBuilder,
+      message: String,
       cause: Throwable?,
-      buildLog: LogBuilder.() -> String,
   ) {
-    val builder = LogBuilder(createLogEvent(level, underlyingLogger))
-    val message = builder.buildLog()
     if (cause != null) {
-      // Call this after buildLog(), so cause exception fields don't overwrite LogBuilder fields
-      builder.setCause(cause, underlyingLogger)
+      logBuilder.setCause(cause, underlyingLogger)
     }
 
-    builder.logEvent.log(message, underlyingLogger)
+    logBuilder.logEvent.log(message, underlyingLogger)
   }
 
   /**
@@ -372,7 +381,7 @@ internal constructor(
    * [Logback configuration docs](https://logback.qos.ch/manual/configuration.html#loggerElement)).
    */
   public val isErrorEnabled: Boolean
-    inline get() = underlyingLogger.isErrorEnabled()
+    get() = underlyingLogger.isErrorEnabled()
 
   /**
    * Returns true if [LogLevel.WARN] is enabled for this logger.
@@ -382,7 +391,7 @@ internal constructor(
    * [Logback configuration docs](https://logback.qos.ch/manual/configuration.html#loggerElement)).
    */
   public val isWarnEnabled: Boolean
-    inline get() = underlyingLogger.isWarnEnabled()
+    get() = underlyingLogger.isWarnEnabled()
 
   /**
    * Returns true if [LogLevel.INFO] is enabled for this logger.
@@ -392,7 +401,7 @@ internal constructor(
    * [Logback configuration docs](https://logback.qos.ch/manual/configuration.html#loggerElement)).
    */
   public val isInfoEnabled: Boolean
-    inline get() = underlyingLogger.isInfoEnabled()
+    get() = underlyingLogger.isInfoEnabled()
 
   /**
    * Returns true if [LogLevel.DEBUG] is enabled for this logger.
@@ -402,7 +411,7 @@ internal constructor(
    * [Logback configuration docs](https://logback.qos.ch/manual/configuration.html#loggerElement)).
    */
   public val isDebugEnabled: Boolean
-    inline get() = underlyingLogger.isDebugEnabled()
+    get() = underlyingLogger.isDebugEnabled()
 
   /**
    * Returns true if [LogLevel.TRACE] is enabled for this logger.
@@ -412,7 +421,7 @@ internal constructor(
    * [Logback configuration docs](https://logback.qos.ch/manual/configuration.html#loggerElement)).
    */
   public val isTraceEnabled: Boolean
-    inline get() = underlyingLogger.isTraceEnabled()
+    get() = underlyingLogger.isTraceEnabled()
 
   /**
    * Returns true if the given log level is enabled for this logger.
@@ -525,7 +534,6 @@ public expect fun getLogger(name: String): Logger
  *
  * On the JVM, we use SLF4J as the underlying logger.
  */
-@PublishedApi
 internal expect interface PlatformLogger {
   fun getName(): String
 
@@ -561,3 +569,13 @@ internal fun normalizeLoggerName(name: String?): String {
     else -> name
   }
 }
+
+/**
+ * SLF4J has the concept of a "caller boundary": the fully qualified class name of the logger class
+ * that made the log. This is used by logger implementations, such as Logback, when the user enables
+ * "caller info": showing the location in the source code where the log was made. Logback then knows
+ * to exclude stack trace elements up to this caller boundary, since the user wants to see where in
+ * _their_ code the log was made, not the location in the logging library. In our case, our boundary
+ * is the [Logger] class.
+ */
+internal const val LOGGER_CLASS_NAME = "dev.hermannm.devlog.Logger"

src/commonTest/kotlin/dev/hermannm/devlog/LoggerTest.kt

@@ -9,6 +9,7 @@ import dev.hermannm.devlog.testutils.loggerInOtherFile
 import dev.hermannm.devlog.testutils.parameterizedTest
 import io.kotest.matchers.booleans.shouldBeFalse
 import io.kotest.matchers.booleans.shouldBeTrue
+import io.kotest.matchers.nulls.shouldNotBeNull
 import io.kotest.matchers.shouldBe
 import kotlin.test.AfterTest
 import kotlin.test.Test
@@ -341,6 +342,12 @@ internal class LoggerTest {
       return
     }
   }
+
+  @Test
+  fun `LOGGER_CLASS_NAME has expected value`() {
+    val expectedName: String = Logger::class.qualifiedName.shouldNotBeNull()
+    LOGGER_CLASS_NAME shouldBe expectedName
+  }
 }
 
 private val loggerOutsideClass = getLogger()

src/jvmMain/kotlin/dev/hermannm/devlog/LogEvent.jvm.kt

@@ -22,7 +22,6 @@ import org.slf4j.event.Level as Slf4jLevel
 import org.slf4j.spi.LocationAwareLogger
 import org.slf4j.spi.LoggingEventAware
 
-@PublishedApi
 internal actual fun createLogEvent(level: LogLevel, logger: Slf4jLogger): LogEvent {
   if (LOGBACK_IS_ON_CLASSPATH && logger is LogbackLogger) {
     return LogbackLogEvent(level, logger)
@@ -55,7 +54,7 @@ internal class Slf4jLogEvent(
     logger: Slf4jLogger,
 ) : LogEvent, BaseSlf4jEvent(level.toSlf4j(), logger) {
   init {
-    this.callerBoundary = FULLY_QUALIFIED_CLASS_NAME
+    this.callerBoundary = LOGGER_CLASS_NAME
     this.timeStamp = System.currentTimeMillis()
   }
 
@@ -152,11 +151,6 @@ internal class Slf4jLogEvent(
 
   /** We don't traverse the cause exception tree in this log event implementation. */
   override fun handlesExceptionTreeTraversal(): Boolean = false
-
-  internal companion object {
-    /** See [LogbackLogEvent.FULLY_QUALIFIED_CLASS_NAME]. */
-    @JvmField internal val FULLY_QUALIFIED_CLASS_NAME = Slf4jLogEvent::class.java.name
-  }
 }
 
 internal fun LogLevel.toSlf4j(): Slf4jLevel {
@@ -173,7 +167,7 @@ internal fun LogLevel.toSlf4j(): Slf4jLevel {
 internal class LogbackLogEvent(level: LogLevel, logger: LogbackLogger) :
     LogEvent,
     BaseLogbackEvent(
-        FULLY_QUALIFIED_CLASS_NAME,
+        LOGGER_CLASS_NAME,
         logger,
         level.toLogback(),
         null, // message (we set this when finalizing the log)
@@ -223,33 +217,16 @@ internal class LogbackLogEvent(level: LogLevel, logger: LogbackLogger) :
    * [setCause].
    */
   override fun handlesExceptionTreeTraversal(): Boolean = true
+}
 
-  internal companion object {
-    /**
-     * When a [LogbackLogEvent] is constructed, we know the `logger` is a [LogbackLogger]. So when
-     * we receive the logger again in [setCause] and [log], we can safely cast it. It's fast to cast
-     * to a concrete class, so we'd rather do that than increase the allocated size of the event by
-     * adding a field.
-     */
-    @JvmStatic
-    private fun PlatformLogger.asLogbackLogger(): LogbackLogger {
-      return this as LogbackLogger
-    }
-
-    /**
-     * SLF4J has the concept of a "caller boundary": the fully qualified class name of the logger
-     * class that made the log. This is used by logger implementations, such as Logback, when the
-     * user enables "caller info": showing the location in the source code where the log was made.
-     * Logback then knows to exclude stack trace elements up to this caller boundary, since the user
-     * wants to see where in _their_ code the log was made, not the location in the logging library.
-     *
-     * In our case, the caller boundary is in fact not [dev.hermannm.devlog.Logger], but our
-     * [LogEvent] implementations. This is because all the methods on `Logger` are `inline` - so the
-     * logger method actually called by user code at runtime is [LogbackLogEvent.log] /
-     * [Slf4jLogEvent.log].
-     */
-    @JvmField internal val FULLY_QUALIFIED_CLASS_NAME = LogbackLogEvent::class.java.name
-  }
+/**
+ * When a [LogbackLogEvent] is constructed, we know the `logger` is a [LogbackLogger]. So when we
+ * receive the logger again in [LogbackLogEvent.log], we can safely cast it. It's fast to cast to a
+ * concrete class, so we'd rather do that than increase the allocated size of the event by adding a
+ * field.
+ */
+private fun PlatformLogger.asLogbackLogger(): LogbackLogger {
+  return this as LogbackLogger
 }
 
 internal fun LogLevel.toLogback(): LogbackLevel {

src/jvmMain/kotlin/dev/hermannm/devlog/Logger.jvm.kt

@@ -1,14 +1,6 @@
 @file:JvmName("LoggerJvm")
-@file:Suppress(
-    // We want `getLogger()` to be inline, so that `lookupClass()` is called in the caller's scope
-    "NOTHING_TO_INLINE",
-    // The `expect` declaration of the `PlatformLogger` interface is annotated with `@PublishedApi`,
-    // so we can use it in inline methods. Kotlin warns us that the `actual` definition should have
-    // the same annotations, but here we use a `typealias`, which doesn't work with `@PublishedApi`.
-    // But this is fine here, because we typealias `PlatformLogger` to the public SLF4J Logger,
-    // which works like `@PublishedApi`.
-    "ACTUAL_ANNOTATIONS_NOT_MATCH_EXPECT",
-)
+// We want `getLogger()` to be inline, so that `lookupClass()` is called in the caller's scope
+@file:Suppress("NOTHING_TO_INLINE")
 
 package dev.hermannm.devlog