user management: document limits (#13040)

* user management: document limits

CHANGELOG_BEGIN
CHANGELOG_END

Co-authored-by: Pawel Batko <pawel.batko@digitalasset.com>

docs/source/app-dev/services.rst

@@ -210,7 +210,10 @@ In contrast to parties, users are local to a participant node.
 The relation between a participant node's users and Daml parties is best understood by analogy to classical databases:
 a participant node's users are analogous to database users while Daml parties are analogous to database roles; and further, the rights granted to a user are analogous to the user's assigned database roles.
 
-For more information, refer to :ref:`the API reference documentation <com.daml.ledger.api.v1.admin.UserManagementService>` for how to list, create, and delete users and their rights.
+For more information, consult the :ref:`the API reference documentation <com.daml.ledger.api.v1.admin.UserManagementService>` for how to list, create, and delete users and their rights.
+See the :ref:`UserManagementFeature descriptor <com.daml.ledger.api.v1.UserManagementFeature>` to learn about limits of the user management service, e.g., the maximum number of rights per user.
+The feature descriptor can be retrieved using the :ref:`Version service <version-service>`.
+
 Read the :doc:`Authorization documentation </app-dev/authorization>` to understand how Ledger API requests are authorized, and how to use user management to dynamically change an application's rights.
 
 .. _package-service:
@@ -252,7 +255,7 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
 Version service
 ============================
 
-Use the **version service** to retrieve information about the Ledger API version.
+Use the **version service** to retrieve information about the Ledger API version and what optional features are supported by the ledger server.
 
 For full details, see :ref:`the proto documentation for the service <com.daml.ledger.api.v1.VersionService>`.
 

ledger-api/grpc-definitions/com/daml/ledger/api/v1/version_service.proto

@@ -60,10 +60,14 @@ message FeaturesDescriptor {
 message UserManagementFeature {
   // Whether the Ledger API server provides the user management service.
   bool supported = 1;
+
   // The maximum number of rights that can be assigned to a single user.
-  // Value of 0 means that no rights per user limit is enforced.
+  // Servers MUST support at least 100 rights per user.
+  // A value of 0 means that the server enforces no rights per user limit.
   int32 max_rights_per_user = 2;
+
   // The maximum number of users the server can return in a single response (page).
-  // Value of 0 means that no page size limit is enforced.
+  // Servers MUST support at least a 100 users per page.
+  // A value of 0 means that the server enforces no page size limit.
   int32 max_users_page_size = 3;
 }

ledger/ledger-runner-common/src/main/scala/com/daml/ledger/runner/common/Config.scala

@@ -665,6 +665,15 @@ object Config {
           .action((value, config: Config[Extra]) =>
             config.withUserManagementConfig(_.copy(maxUsersPageSize = value))
           )
+        checkConfig(c => {
+          val v = c.userManagementConfig.maxUsersPageSize
+          if (v == 0 || v >= 100) {
+            success
+          } else {
+            failure(s"max-users-page-size must be either 0 or greater than 99, was: $v")
+          }
+        })
+
         opt[Unit]('s', "static-time")
           .optional()
           .hidden() // Only available for testing purposes

ledger/ledger-runner-common/src/test/scala/com/daml/ledger/runner/common/ConfigSpec.scala

@@ -6,12 +6,11 @@ package com.daml.ledger.runner.common
 import com.daml.ledger.api.tls.{SecretsUrl, TlsConfiguration, TlsVersion}
 import com.daml.lf.data.Ref
 import io.netty.handler.ssl.ClientAuth
-import org.scalatest.OptionValues
+import org.scalatest.{Assertion, OptionValues}
 import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should.Matchers
 import org.scalatest.prop.TableDrivenPropertyChecks
 import scopt.OptionParser
-
 import java.io.File
 import java.time.Duration
 
@@ -57,13 +56,18 @@ final class ConfigSpec
       getEnvVar = getEnvVar,
     )
 
-  private def configParserSimple(parameters: Seq[String] = Seq.empty): Option[Config[Unit]] =
+  private def configParserSimple(parameters: Iterable[String] = Seq.empty): Option[Config[Unit]] =
     configParser(
       Seq(
         dumpIndexMetadataCommand,
         "some-jdbc-url",
       ) ++ parameters
     )
+
+  private def checkOptionFail(parameters: Iterable[String]): Assertion = {
+    configParserSimple(parameters) shouldBe None
+  }
+
   behavior of "Runner"
 
   it should "succeed when server's private key is encrypted and secret-url is provided" in {
@@ -325,6 +329,26 @@ final class ConfigSpec
         "123",
       )
     ).value.userManagementConfig.maxUsersPageSize shouldBe 123
+    // values in range [1, 99] are disallowed
+    checkOptionFail(
+      Array(
+        "--max-users-page-size",
+        "1",
+      )
+    )
+    checkOptionFail(
+      Array(
+        "--max-users-page-size",
+        "99",
+      )
+    )
+    // negative values are disallowed
+    checkOptionFail(
+      Array(
+        "--max-users-page-size",
+        "-1",
+      )
+    )
   }
 
   private def parsingFailure(): Nothing = fail("Config parsing failed.")

ledger/sandbox-common/src/main/scala/platform/sandbox/cli/CommonCliBase.scala

@@ -418,6 +418,14 @@ class CommonCliBase(name: LedgerName) {
         .action((value, config: SandboxConfig) =>
           config.withUserManagementConfig(_.copy(maxUsersPageSize = value))
         )
+      checkConfig(c => {
+        val v = c.userManagementConfig.maxUsersPageSize
+        if (v == 0 || v >= 100) {
+          success
+        } else {
+          failure(s"max-users-page-size must be either 0 or greater than 99, was: $v")
+        }
+      })
 
       com.daml.cliopts.Metrics.metricsReporterParse(this)(
         (setter, config) => config.copy(metricsReporter = setter(config.metricsReporter)),

ledger/sandbox-common/src/test/lib/scala/platform/sandbox/cli/CommonCliSpecBase.scala

@@ -429,6 +429,26 @@ abstract class CommonCliSpecBase(
         ),
         _.withUserManagementConfig(_.copy(maxUsersPageSize = 123)),
       )
+      // values in range [1, 99] are disallowed
+      checkOptionFail(
+        Array(
+          "--max-users-page-size",
+          "1",
+        )
+      )
+      checkOptionFail(
+        Array(
+          "--max-users-page-size",
+          "99",
+        )
+      )
+      // negative values are disallowed
+      checkOptionFail(
+        Array(
+          "--max-users-page-size",
+          "-1",
+        )
+      )
     }
 
   }