Idiomatic Kotlin API Guide

This document describes the idiomatic Kotlin features added to the did-core module.

Overview

The module now includes:

• Builder DSLs for creating resolvers and registries
• Extension functions for fluent, functional-style operations
• Operator overloads for intuitive API usage
• Retry logic with exponential backoff

Builder DSLs

Universal Resolver Builder

import org.trustweave.did.dsl.universalResolver

val resolver = universalResolver("https://dev.uniresolver.io") {
    timeout = 60
    apiKey = "my-api-key"
    retry {
        maxRetries = 3
        initialDelayMs = 200
        maxDelayMs = 2000
    }
    protocolAdapter = StandardUniversalResolverAdapter()
}

Registry Builder

import org.trustweave.did.registry.didMethodRegistry

val registry = didMethodRegistry {
    register(KeyDidMethod(kms))
    register(WebDidMethod())
    registerAll(OtherMethod1(), OtherMethod2())
}

Operator Overloads

Registry Operators

val registry = DidMethodRegistry()

// Bracket notation for access
val method = registry["key"]

// `in` operator for checking existence
if ("key" in registry) {
    // Method is registered
}

// Assignment operator
registry["new"] = NewDidMethod()

Extension Functions

DidResolutionResult extensions

DidResolutionResult is a sealed class (not Result<T>) with three top-level cases — Success, Deactivated, and Failure — since the DID Resolution 1.0 migration. Use when, resolveOrNull / resolveOrThrow on Did, or the small did-core helpers below.

import org.trustweave.did.resolver.DidResolutionResult
import org.trustweave.did.resolver.errorType
import org.trustweave.did.resolver.errorMessage
import org.trustweave.did.resolver.hasError
import org.trustweave.did.resolver.isDeactivated
import org.trustweave.did.resolver.isNotFound
import org.trustweave.did.resolver.isSuccess

val result: DidResolutionResult = // ... from resolver.resolve(did)

// Diagnostics
if (result.isSuccess) { /* ... */ }
if (result.isDeactivated) { /* treat as revoked, not "not found" */ }
if (result.hasError) {   // true only for Failure — deactivation is NOT an error
    println(result.errorMessage)
    println(result.errorType)  // the RFC 9457 error type URI, e.g. DidErrorType.NOT_FOUND
}
if (result.isNotFound) { /* ... */ }

// Document extraction — `documentOrNull` is also available as a built-in extension
val documentOrNull: DidDocument? = when (result) {
    is DidResolutionResult.Success -> result.document
    else -> null   // Deactivated and Failure both have no document
}

val message = when (result) {
    is DidResolutionResult.Success -> "Success: ${result.document.id}"
    is DidResolutionResult.Deactivated -> "Deactivated: ${result.did.value}"
    is DidResolutionResult.Failure -> "Failed: ${result.errorMessage}"
}

Did Extensions

import org.trustweave.did.identifiers.Did
import org.trustweave.did.dsl.resolveWith
import org.trustweave.did.dsl.resolveOrNull
import org.trustweave.did.dsl.resolveOrThrow
import org.trustweave.did.dsl.resolveOrDefault

val did = Did("did:key:123")
val resolver: DidResolver = // ... resolver

// Resolve to document (throws DidException on failure)
val document = did.resolveOrThrow(resolver)
val doc = did.resolveOrNull(resolver)
val docOrDefault = did.resolveOrDefault(resolver, defaultDocument)

// Deactivation: resolveOrNull/resolveOrDefault do NOT fold a deactivated DID into
// null/the default — a revoked identity is not an absent one. Both throw
// DidException.DidResolutionFailed in that case, matching resolveOrThrow.

// With callback
did.resolveWith(resolver) { document ->
    println("Resolved: ${document.id}")
}

Retry Configuration

Default Retry

val resolver = DefaultUniversalResolver(
    baseUrl = "https://dev.uniresolver.io",
    retryConfig = RetryConfig.default()  // 3 retries, 100ms initial delay
)

No Retry

val resolver = DefaultUniversalResolver(
    baseUrl = "https://dev.uniresolver.io",
    retryConfig = RetryConfig.noRetry()
)

Aggressive Retry

val resolver = DefaultUniversalResolver(
    baseUrl = "https://dev.uniresolver.io",
    retryConfig = RetryConfig.aggressive()  // 5 retries, 200ms initial delay
)

Custom Retry

val retryConfig = RetryConfig(
    maxRetries = 5,
    initialDelayMs = 200,
    maxDelayMs = 5000,
    retryableStatusCodes = setOf(500, 502, 503, 504),
    retryableExceptions = setOf(
        java.net.ConnectException::class.java,
        java.net.SocketTimeoutException::class.java
    )
)

val resolver = DefaultUniversalResolver(
    baseUrl = "https://dev.uniresolver.io",
    retryConfig = retryConfig
)

Performance Improvements

Cached Validation

The baseUrl validation is now cached during initialization, improving performance for repeated resolutions.

Retry Logic

Automatic retry with exponential backoff for transient failures:

• Network errors (ConnectException, SocketTimeoutException)
• HTTP 5xx errors (configurable)
• Exponential backoff with jitter to avoid thundering herd

Migration Guide

Before

val registry = DidMethodRegistry()
registry.register(KeyDidMethod(kms))
val method = registry.get("key")

val resolver = DefaultUniversalResolver("https://dev.uniresolver.io")
val result = resolver.resolveDid("did:key:123")
val document = when (result) {
    is DidResolutionResult.Success -> result.document
    else -> null
}

After

val registry = didMethodRegistry {
    register(KeyDidMethod(kms))
}
val method = registry["key"]  // Operator overload

val resolver = universalResolver("https://dev.uniresolver.io") {
    timeout = 60
    retry { maxRetries = 3 }
}
val document = Did("did:key:123").resolveOrNull(resolver)
// null for not-found/invalid/error; throws DidException.DidResolutionFailed if deactivated

Best Practices

1. Use builder DSLs for complex configurations
2. Use extension functions for fluent, readable code (resolveOrThrow, resolveOrNull, resolveOrDefault)
3. Use operator overloads for intuitive API usage
4. Configure retry logic for production environments
5. Handle the sealed DidResolutionResult with when when you need per-failure behaviour