ledger-configuration: Extract the configuration from participant-stat…

…e. [KVL-1002] (#10279) * ledger-configuration: Extract configuration from participant-state. The configuration is often used without the state, and doesn't need to be versioned in the same way. CHANGELOG_BEGIN - [Integration Kit] The ledger configuration classes, ``Configuration``, ``LedgerInitialConditions``, and ``TimeModel``, have been moved from *participant-state* to a separate package named *ledger-configuration*, in the Java package ``com.daml.ledger.configuration``. You will need to update your dependencies and imports. CHANGELOG_END * participant-state: Remove the `LedgerId` aliases. * ledger-configuration: Rename `TimeModel` to `LedgerTimeModel`. This avoids confusion with the protobuf-generated `TimeModel` classes. CHANGELOG_BEGIN - [Integration Kit] ``TimeModel`` has been renamed to ``LedgerTimeModel``. If you are using the ledger configuration classes directly, you may need to update your code. CHANGELOG_END * ledger-configuration: Remove colons in LedgerInitialConditions' docs. * kvutils: Restore a missing compat import. * participant-integration-api: Add ledger-configuration to Oracle tests. * sandbox-common: Fix `--max-ledger-time-skew` docs. Co-authored-by: Miklos <[email protected]> Co-authored-by: Miklos <[email protected]>
digital-asset · Jul 15, 2021 · a9a0b70 · a9a0b70
1 parent d96b54e
commit a9a0b70
Show file tree

Hide file tree

Showing 122 changed files with 408 additions and 460 deletions.
diff --git a/ledger/indexer-benchmark/BUILD.bazel b/ledger/indexer-benchmark/BUILD.bazel
@@ -32,6 +32,7 @@ da_scala_library(
         "//language-support/scala/bindings",
         "//ledger/ledger-api-common",
         "//ledger/ledger-api-health",
+        "//ledger/ledger-configuration",
         "//ledger/ledger-resources",
         "//ledger/metrics",
         "//ledger/participant-integration-api",
@@ -61,6 +62,7 @@ da_scala_library(
         "//language-support/scala/bindings",
         "//ledger/ledger-api-common",
         "//ledger/ledger-api-health",
+        "//ledger/ledger-configuration",
         "//ledger/metrics",
         "//ledger/participant-state",
         "//ledger/participant-state/kvutils",

diff --git a/ledger/indexer-benchmark/src/app/scala/ledger/indexerbenchmark/Main.scala b/ledger/indexer-benchmark/src/app/scala/ledger/indexerbenchmark/Main.scala
@@ -13,14 +13,15 @@ import akka.stream.scaladsl.{Sink, Source}
 import com.codahale.metrics.MetricRegistry
 import com.daml.dec.DirectExecutionContext
 import com.daml.ledger.api.health.HealthStatus
-import com.daml.ledger.participant.state.kvutils.{OffsetBuilder, Raw}
-import com.daml.ledger.participant.state.kvutils.`export`.ProtobufBasedLedgerDataImporter
+import com.daml.ledger.configuration.LedgerId
 import com.daml.ledger.participant.state.kvutils.api.{
   KeyValueParticipantStateReader,
   LedgerReader,
   LedgerRecord,
 }
-import com.daml.ledger.participant.state.v1.{LedgerId, Offset, Update}
+import com.daml.ledger.participant.state.kvutils.export.ProtobufBasedLedgerDataImporter
+import com.daml.ledger.participant.state.kvutils.{OffsetBuilder, Raw}
+import com.daml.ledger.participant.state.v1.{Offset, Update}
 import com.daml.metrics.Metrics
 
 import scala.concurrent.Future

diff --git a/ledger/indexer-benchmark/src/main/scala/ledger/indexerbenchmark/IndexerBenchmark.scala b/ledger/indexer-benchmark/src/main/scala/ledger/indexerbenchmark/IndexerBenchmark.scala
@@ -12,14 +12,8 @@ import akka.stream.scaladsl.Source
 import com.codahale.metrics.{MetricRegistry, Snapshot}
 import com.daml.dec.DirectExecutionContext
 import com.daml.ledger.api.health.HealthStatus
-import com.daml.ledger.participant.state.v1.{
-  Configuration,
-  LedgerInitialConditions,
-  Offset,
-  ReadService,
-  TimeModel,
-  Update,
-}
+import com.daml.ledger.configuration.{Configuration, LedgerInitialConditions, LedgerTimeModel}
+import com.daml.ledger.participant.state.v1.{Offset, ReadService, Update}
 import com.daml.ledger.resources.{Resource, ResourceContext, ResourceOwner}
 import com.daml.lf.data.Time
 import com.daml.logging.LoggingContext.newLoggingContext
@@ -174,7 +168,7 @@ class IndexerBenchmark() {
       IndexerBenchmark.LedgerId,
       Configuration(
         generation = 0,
-        timeModel = TimeModel.reasonableDefault,
+        timeModel = LedgerTimeModel.reasonableDefault,
         maxDeduplicationTime = java.time.Duration.ofDays(1),
       ),
       Time.Timestamp.Epoch,

diff --git a/ledger/ledger-api-domain/BUILD.bazel b/ledger/ledger-api-domain/BUILD.bazel
@@ -19,7 +19,7 @@ da_scala_library(
     deps = [
         "//daml-lf/data",
         "//daml-lf/transaction",
-        "//ledger/participant-state",
+        "//ledger/ledger-configuration",
         "//libs-scala/logging-entries",
         "@maven//:io_zipkin_brave_brave",
     ],

diff --git a/ledger/ledger-api-domain/src/main/scala/com/digitalasset/ledger/api/domain.scala b/ledger/ledger-api-domain/src/main/scala/com/digitalasset/ledger/api/domain.scala
@@ -7,7 +7,7 @@ import java.time.Instant
 
 import brave.propagation.TraceContext
 import com.daml.ledger.api.domain.Event.{CreateOrArchiveEvent, CreateOrExerciseEvent}
-import com.daml.ledger.participant.state.v1.Configuration
+import com.daml.ledger.configuration.Configuration
 import com.daml.lf.command.{Commands => LfCommands}
 import com.daml.lf.data.Ref
 import com.daml.lf.data.Ref.LedgerString.ordering

diff --git a/ledger/ledger-configuration/BUILD.bazel b/ledger/ledger-configuration/BUILD.bazel
@@ -0,0 +1,52 @@
+# Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+load(
+    "//bazel_tools:scala.bzl",
+    "da_scala_library",
+    "da_scala_test_suite",
+)
+
+da_scala_library(
+    name = "ledger-configuration",
+    srcs = glob(["src/main/scala/**/*.scala"]),
+    resources = glob(["src/main/resources/**/*"]),
+    tags = ["maven_coordinates=com.daml:ledger-configuration:__VERSION__"],
+    visibility = [
+        "//visibility:public",
+    ],
+    exports = [
+        "//ledger/ledger-configuration/protobuf:ledger_configuration_proto_java",
+    ],
+    runtime_deps = [],
+    deps = [
+        "//daml-lf/data",
+        "//language-support/scala/bindings",
+        "//ledger/ledger-configuration/protobuf:ledger_configuration_proto_java",
+        "@maven//:com_google_protobuf_protobuf_java",
+    ],
+)
+
+filegroup(
+    name = "sources",
+    srcs = glob(["src/main/scala/**/*.scala"]),
+    visibility = ["//visibility:public"],
+)
+
+da_scala_test_suite(
+    name = "ledger-configuration-tests",
+    size = "small",
+    srcs = glob(["src/test/suite/scala/**/*.scala"]),
+    resources = glob(["src/test/resources/*"]),
+    scala_deps = [
+        "@maven//:org_scalatest_scalatest",
+        "@maven//:org_scalaz_scalaz_core",
+        "@maven//:org_scala_lang_modules_scala_collection_compat",
+    ],
+    deps = [
+        ":ledger-configuration",
+        "//daml-lf/data",
+        "//daml-lf/transaction",
+        "//ledger-api/grpc-definitions:ledger_api_proto_scala",
+    ],
+)
diff --git a/...er/participant-state/protobuf/BUILD.bazel → ...ledger-configuration/protobuf/BUILD.bazel b/...er/participant-state/protobuf/BUILD.bazel → ...ledger-configuration/protobuf/BUILD.bazel
@@ -8,7 +8,10 @@ proto_jars(
     srcs = ["com/daml/ledger/participant/state/ledger_configuration.proto"],
     maven_artifact_prefix = "participant-state-ledger-configuration",
     maven_group = "com.daml",
-    visibility = ["//ledger/participant-state:__subpackages__"],
+    visibility = [
+        "//ledger/ledger-configuration:__subpackages__",
+        "//ledger/participant-state:__subpackages__",
+    ],
     deps = [
         "@com_google_protobuf//:duration_proto",
     ],

diff --git a/...ticipant/state/ledger_configuration.proto → ...ticipant/state/ledger_configuration.proto b/...ticipant/state/ledger_configuration.proto → ...ticipant/state/ledger_configuration.proto
diff --git a/...t-state/protobuf/ledger_configuration.rst → ...uration/protobuf/ledger_configuration.rst b/...t-state/protobuf/ledger_configuration.rst → ...uration/protobuf/ledger_configuration.rst
@@ -16,8 +16,11 @@ Please read ``daml-lf/spec/transaction.rst`` to understand the rules
 we follow for evolving the ledger configuration.
 
 The canonical specification compliant implementation for encoding and
-decoding ledger configurations is part of the participant-state package
-in ``ledger/participant-state``.
+decoding ledger configurations is part of the ledger-configuration
+package in ``ledger/ledger-configuration``.
+
+For historical reasons, we have kept the package name as
+``com.daml.ledger.participant.state``.
 
 Version history
 ^^^^^^^^^^^^^^^

diff --git a/.../participant/state/v1/Configuration.scala → .../ledger/configuration/Configuration.scala b/.../participant/state/v1/Configuration.scala → .../ledger/configuration/Configuration.scala
@@ -1,7 +1,7 @@
 // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-package com.daml.ledger.participant.state.v1
+package com.daml.ledger.configuration
 
 import java.time.Duration
 
@@ -10,13 +10,13 @@ import scala.util.Try
 /** Ledger configuration describing the ledger's time model.
   * Emitted in [[com.daml.ledger.participant.state.v1.Update.ConfigurationChanged]].
   *
-  * @param generation The configuration generation. Monotonically increasing.
-  * @param timeModel The time model of the ledger. Specifying the time-to-live bounds for Ledger API commands.
+  * @param generation            The configuration generation. Monotonically increasing.
+  * @param timeModel             The time model of the ledger. Specifying the time-to-live bounds for Ledger API commands.
   * @param maxDeduplicationTime The maximum time window during which commands can be deduplicated.
   */
 final case class Configuration(
     generation: Long,
-    timeModel: TimeModel,
+    timeModel: LedgerTimeModel,
     maxDeduplicationTime: Duration,
 )
 
@@ -58,8 +58,8 @@ object Configuration {
         )
       }
 
-    def decodeTimeModel(tm: protobuf.LedgerTimeModel): Either[String, TimeModel] =
-      TimeModel(
+    def decodeTimeModel(tm: protobuf.LedgerTimeModel): Either[String, LedgerTimeModel] =
+      LedgerTimeModel(
         avgTransactionLatency = parseDuration(tm.getAvgTransactionLatency),
         minSkew = parseDuration(tm.getMinSkew),
         maxSkew = parseDuration(tm.getMaxSkew),
@@ -88,8 +88,8 @@ object Configuration {
         )
       }
 
-    def decodeTimeModel(tm: protobuf.LedgerTimeModel): Either[String, TimeModel] =
-      TimeModel(
+    def decodeTimeModel(tm: protobuf.LedgerTimeModel): Either[String, LedgerTimeModel] =
+      LedgerTimeModel(
         avgTransactionLatency = parseDuration(tm.getAvgTransactionLatency),
         minSkew = parseDuration(tm.getMinSkew),
         maxSkew = parseDuration(tm.getMaxSkew),

diff --git a/...nt/state/v2/LedgerInitialConditions.scala → ...nfiguration/LedgerInitialConditions.scala b/...nt/state/v2/LedgerInitialConditions.scala → ...nfiguration/LedgerInitialConditions.scala
@@ -1,15 +1,15 @@
 // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-package com.daml.ledger.participant.state.v2
+package com.daml.ledger.configuration
 
 import com.daml.lf.data.Time.Timestamp
 
 /** The initial conditions of the ledger before anything has been committed.
   *
-  * @param ledgerId: The static ledger identifier.
-  * @param config: The initial ledger configuration
-  * @param initialRecordTime: The initial record time prior to any [[Update]] event.
+  * @param ledgerId          The static ledger identifier.
+  * @param config            The initial ledger configuration
+  * @param initialRecordTime The initial record time prior to any update event.
   */
 final case class LedgerInitialConditions(
     ledgerId: LedgerId,

diff --git a/...dger/participant/state/v1/TimeModel.scala → ...edger/configuration/LedgerTimeModel.scala b/...dger/participant/state/v1/TimeModel.scala → ...edger/configuration/LedgerTimeModel.scala
@@ -1,22 +1,25 @@
 // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-package com.daml.ledger.participant.state.v1
+package com.daml.ledger.configuration
 
 import java.time.{Duration, Instant}
 
 import scala.util.Try
 
-/** The ledger time model and associated validations. Some values are given by constructor args; others are derived.
-  * @param avgTransactionLatency The expected average latency of a transaction, i.e., the average time
-  *                              from submitting the transaction to a [[WriteService]] and the transaction
-  *                              being assigned a record time.
-  * @param minSkew               The minimimum skew between ledger time and record time: lt_TX >= rt_TX - minSkew
-  * @param maxSkew               The maximum skew between ledger time and record time: lt_TX <= rt_TX + maxSkew
+/** The ledger time model and associated validations. Some values are given by constructor args;
+  * others are derived.
   *
+  * @param avgTransactionLatency The expected average latency of a transaction, i.e., the average
+  *                              time from submitting the transaction to a write service and the
+  *                              transaction being assigned a record time.
+  * @param minSkew               The minimimum skew between ledger time and record time:
+  *                              lt_TX >= rt_TX - minSkew
+  * @param maxSkew               The maximum skew between ledger time and record time:
+  *                              lt_TX <= rt_TX + maxSkew
   * @throws IllegalArgumentException if the parameters aren't valid
   */
-case class TimeModel private (
+case class LedgerTimeModel private (
     avgTransactionLatency: Duration,
     minSkew: Duration,
     maxSkew: Duration,
@@ -37,36 +40,40 @@ case class TimeModel private (
       Right(())
   }
 
-  private[state] def minLedgerTime(recordTime: Instant): Instant =
+  private[ledger] def minLedgerTime(recordTime: Instant): Instant =
     recordTime.minus(minSkew)
 
-  private[state] def maxLedgerTime(recordTime: Instant): Instant =
+  private[ledger] def maxLedgerTime(recordTime: Instant): Instant =
     recordTime.plus(maxSkew)
 
-  private[state] def minRecordTime(ledgerTime: Instant): Instant =
+  private[ledger] def minRecordTime(ledgerTime: Instant): Instant =
     ledgerTime.minus(maxSkew)
 
-  private[state] def maxRecordTime(ledgerTime: Instant): Instant =
+  private[ledger] def maxRecordTime(ledgerTime: Instant): Instant =
     ledgerTime.plus(minSkew)
 }
 
-object TimeModel {
+object LedgerTimeModel {
 
   /** A default TimeModel that's reasonable for a test or sandbox ledger application.
     * Serious applications (viz. ledger) should probably specify their own TimeModel.
     */
-  val reasonableDefault: TimeModel =
-    TimeModel(
+  val reasonableDefault: LedgerTimeModel =
+    LedgerTimeModel(
       avgTransactionLatency = Duration.ofSeconds(0L),
       minSkew = Duration.ofSeconds(30L),
       maxSkew = Duration.ofSeconds(30L),
     ).get
 
-  def apply(avgTransactionLatency: Duration, minSkew: Duration, maxSkew: Duration): Try[TimeModel] =
+  def apply(
+      avgTransactionLatency: Duration,
+      minSkew: Duration,
+      maxSkew: Duration,
+  ): Try[LedgerTimeModel] =
     Try {
       require(!avgTransactionLatency.isNegative, "Negative average transaction latency")
       require(!minSkew.isNegative, "Negative min skew")
       require(!maxSkew.isNegative, "Negative max skew")
-      new TimeModel(avgTransactionLatency, minSkew, maxSkew)
+      new LedgerTimeModel(avgTransactionLatency, minSkew, maxSkew)
     }
 }
diff --git a/ledger/ledger-configuration/src/main/scala/com/daml/ledger/configuration/package.scala b/ledger/ledger-configuration/src/main/scala/com/daml/ledger/configuration/package.scala
@@ -0,0 +1,11 @@
+// Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.daml.ledger
+
+package object configuration {
+
+  /** Identifier for the ledger, MUST match regexp [a-zA-Z0-9-]. */
+  type LedgerId = String
+
+}
diff --git a/.../participant/state/v1/TimeModelSpec.scala → ...r/configuration/LedgerTimeModelSpec.scala b/.../participant/state/v1/TimeModelSpec.scala → ...r/configuration/LedgerTimeModelSpec.scala
@@ -1,19 +1,19 @@
 // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-package com.daml.ledger.participant.state.v1
+package com.daml.ledger.configuration
 
 import java.time._
 
 import org.scalatest.matchers.should.Matchers
 import org.scalatest.wordspec.AnyWordSpec
 
-class TimeModelSpec extends AnyWordSpec with Matchers {
+class LedgerTimeModelSpec extends AnyWordSpec with Matchers {
 
   private val referenceTime = Instant.EPOCH
   private val epsilon = Duration.ofMillis(10L)
   private val timeModel =
-    TimeModel(
+    LedgerTimeModel(
       avgTransactionLatency = Duration.ZERO,
       minSkew = Duration.ofSeconds(30L),
       maxSkew = Duration.ofSeconds(30L),
@@ -92,12 +92,11 @@ class TimeModelSpec extends AnyWordSpec with Matchers {
       }
 
       "produce a valid error message" in {
-        val timeModel =
-          TimeModel(
-            avgTransactionLatency = Duration.ZERO,
-            minSkew = Duration.ofSeconds(10L),
-            maxSkew = Duration.ofSeconds(20L),
-          ).get
+        val timeModel = LedgerTimeModel(
+          avgTransactionLatency = Duration.ZERO,
+          minSkew = Duration.ofSeconds(10L),
+          maxSkew = Duration.ofSeconds(20L),
+        ).get
         val ledgerTime = "2000-01-01T12:00:00Z"
         val recordTime = "2000-01-01T12:30:00Z"
         val lowerBound = "2000-01-01T12:29:50Z"
@@ -112,8 +111,8 @@ class TimeModelSpec extends AnyWordSpec with Matchers {
     }
   }
 
-  private def createAsymmetricTimeModel(minSkew: Duration, maxSkew: Duration): TimeModel =
-    TimeModel(
+  private def createAsymmetricTimeModel(minSkew: Duration, maxSkew: Duration): LedgerTimeModel =
+    LedgerTimeModel(
       avgTransactionLatency = Duration.ZERO,
       minSkew = minSkew,
       maxSkew = maxSkew,

diff --git a/ledger/ledger-on-memory/BUILD.bazel b/ledger/ledger-on-memory/BUILD.bazel
@@ -29,6 +29,7 @@ da_scala_library(
         "//ledger/caching",
         "//ledger/ledger-api-common",
         "//ledger/ledger-api-health",
+        "//ledger/ledger-configuration",
         "//ledger/ledger-resources",
         "//ledger/metrics",
         "//ledger/participant-state",
@@ -69,6 +70,7 @@ da_scala_test_suite(
         "//ledger/caching",
         "//ledger/ledger-api-common",
         "//ledger/ledger-api-health",
+        "//ledger/ledger-configuration",
         "//ledger/ledger-resources",
         "//ledger/ledger-resources:ledger-resources-test-lib",
         "//ledger/metrics",
@@ -104,6 +106,7 @@ da_scala_library(
         "//ledger/ledger-api-auth",
         "//ledger/ledger-api-common",
         "//ledger/ledger-api-health",
+        "//ledger/ledger-configuration",
         "//ledger/ledger-resources",
         "//ledger/metrics",
         "//ledger/participant-integration-api",