feat(external-call): Add HTTP extension service client

[trusch]

Summary

This PR adds the HTTP client infrastructure for making external service calls. It provides an implementation with retry logic, authentication, TLS support, and connection pooling.

Requires #441

Changes

Configuration (ExtensionServiceConfig.scala)

final case class ExtensionServiceConfig(
    name: String,                           // Extension identifier
    host: String,                           // Service hostname
    port: Int,                              // Service port
    useTls: Boolean = false,                // Enable HTTPS
    tlsInsecure: Boolean = false,           // Skip cert validation
    jwt: Option[String] = None,             // JWT token (inline)
    jwtFile: Option[String] = None,         // JWT token (from file)
    connectTimeout: Duration = 500.millis,  // Connection timeout
    requestTimeout: Duration = 8.seconds,   // Request timeout
    maxTotalTimeout: Duration = 25.seconds, // Max total time including retries
    maxRetries: Int = 3,                    // Max retry attempts
    retryInitialDelay: Duration = 1.second, // Initial retry delay
    retryMaxDelay: Duration = 10.seconds,   // Max retry delay (exponential backoff)
    requestIdHeader: String = "X-Request-Id",
    declaredFunctions: Seq[DeclaredFunction] = Seq.empty
)

Service Interface (ExtensionService.scala)

trait ExtensionServiceClient {
  def call(
      functionId: String,
      config: Bytes,
      input: Bytes,
      mode: ExecutionMode  // Submission vs Validation
  )(implicit tc: TraceContext): Future[Either[ExtensionCallError, Bytes]]
}

sealed trait ExtensionCallError
case class SimpleError(message: String) extends ExtensionCallError
case class RetryableError(message: String, retryAfter: Option[Duration]) extends ExtensionCallError

HTTP Client (HttpExtensionServiceClient.scala)

Features:

• Connection pooling: Shared HttpClient across calls
• Retry logic: Exponential backoff with jitter
• Rate limiting: Respects Retry-After header (429, 503)
• Authentication: JWT Bearer token support
• TLS: HTTPS with optional insecure mode
• Tracing: Request ID header for distributed tracing
• Mode header: Indicates submission vs validation mode

class HttpExtensionServiceClient(
    config: ExtensionServiceConfig,
    httpClient: HttpClient,
    loggerFactory: NamedLoggerFactory
) extends ExtensionServiceClient {

  override def call(...): Future[Either[ExtensionCallError, Bytes]] = {
    val request = buildRequest(functionId, config, input, mode)
    executeWithRetry(request, remainingRetries = config.maxRetries)
  }
}

Service Manager (ExtensionServiceManager.scala)

class ExtensionServiceManager(
    configs: Map[String, ExtensionServiceConfig],
    httpClient: HttpClient,
    loggerFactory: NamedLoggerFactory
) {
  private val clients: Map[String, ExtensionServiceClient] =
    configs.map { case (name, config) =>
      name -> new HttpExtensionServiceClient(config, httpClient, loggerFactory)
    }

  def getClient(extensionId: String): Option[ExtensionServiceClient] =
    clients.get(extensionId)
}

Validator (ExtensionValidator.scala)

Validates DAR packages against extension configuration:

• Checks that all referenced extensions are configured
• Validates function config hashes match
• Reports warnings for missing extensions (non-fatal for observers)

Engine Bridge (ExtensionServiceExternalCallHandler.scala)

class ExtensionServiceExternalCallHandler(
    manager: ExtensionServiceManager
) extends ExternalCallHandler {

  override def handleExternalCall(
      extensionId: String,
      functionId: String,
      config: Bytes,
      input: Bytes,
      mode: ExecutionMode
  ): Future[Either[String, Bytes]] = {
    manager.getClient(extensionId) match {
      case Some(client) => client.call(functionId, config, input, mode)
      case None => Future.successful(Left(s"Unknown extension: $extensionId"))
    }
  }
}

Engine Config (CantonEngineConfig.scala)

• Added extensions configuration section

Canton Configuration Example

canton.participants.participant1 {
  ledger-api.extensions {
    services {
      price-oracle {
        host = "oracle.example.com"
        port = 443
        useTls = true
        jwt = "eyJ..."
        requestTimeout = 5s
        maxRetries = 3
        declaredFunctions = [
          { functionId = "get-price", configHash = "abc123" }
        ]
      }
    }
  }
}

Testing

This will be covered by integration tests in the daml repo.

[github-actions]

🎉 Thank you for your contribution! It appears you have not yet signed the Agreement DA Contributor License Agreement (CLA), which is required for your changes to be incorporated into an Open Source Software (OSS) project. Please kindly read the and reply on a new comment with the following text to agree:

---

I have hereby read the Digital Asset CLA and agree to its terms

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}