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]

✅ All required contributors have signed the CLA for this PR. Thank you!
_{Posted by the CLA Assistant Lite bot.}