Developer SDK

Kotlin examples

Install the SDK · View source on GitHub ↗

provider/src/main/kotlin/Main.kt

kotlin
// The Kotlin provider example: a console app for Windows, macOS and Linux
// that runs a URnetwork provider for the developer's network and shows its
// status (PROVIDER_CONTRACT.md). It provides publicly with the scoped client
// credential that the developer's backend issued for this installation; the
// payout wallet is mapped by the backend and is only displayed here.
//
// Usage: urnetwork-provider [run] | --self-test | --version. All installation
// state is in the private directory named by URNETWORK_PROVIDER_STATE_DIR
// (InstallationState.kt).
//
// Exit codes, for supervisors: 0 stopped on request, 78 configuration or
// credential problem (restarting does not help), 1 any other failure.
import java.io.IOException
import java.io.PrintStream
import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit
import java.util.concurrent.atomic.AtomicInteger
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.seconds

const val exitStopped = 0
const val exitFailure = 1

// sysexits EX_CONFIG
const val exitConfig = 78

const val usage = "usage: urnetwork-provider [run] | --self-test | --version"

// how long Ctrl-C or SIGTERM waits for the provider to stop before the process
// exits anyway
private val stopTimeout = 15.seconds

// no exit code decided yet; exit codes are 0 to 255
private const val noExitCode = -1

/** Exits with the code of the command. */
fun main(args: Array<String>) {
    exitProcess(runCommand(args.toList(), System.getenv("URNETWORK_PROVIDER_STATE_DIR"), System.out, System.err))
}

/** Runs one command and returns the exit code. stateDir is the value of URNETWORK_PROVIDER_STATE_DIR. */
fun runCommand(args: List<String>, stateDir: String?, out: PrintStream, err: PrintStream): Int {
    when {
        args == listOf("--self-test") -> {
            try {
                runSelfTest()
            } catch (e: Exception) {
                err.println("provider self-test failed: ${describeFailure(e)}")
                return exitFailure
            }
            out.println("provider self-test passed")
            return exitStopped
        }
        args == listOf("--version") -> {
            try {
                out.println(ProviderSession.sdkVersion())
            } catch (e: LinkageError) {
                err.println("could not load the URnetwork SDK runtime: ${describeFailure(e)}")
                return exitFailure
            } catch (e: RuntimeException) {
                err.println("could not load the URnetwork SDK runtime: ${describeFailure(e)}")
                return exitFailure
            }
            return exitStopped
        }
        args.isEmpty() || args == listOf("run") -> return runProvider(stateDir, out, err)
        else -> {
            err.println(usage)
            return exitConfig
        }
    }
}

/** Provides until Ctrl-C, SIGTERM or a credential that the server rejects. */
private fun runProvider(stateDir: String?, out: PrintStream, err: PrintStream): Int {
    out.println(consentDisclaimer)
    val config = try {
        loadProviderConfig(stateDir)
    } catch (e: ConfigException) {
        err.println(e.message)
        return exitConfig
    }
    // from here on Ctrl-C and SIGTERM stop the provider and exit with 0, also
    // while the native runtime loads and the device starts
    val session = ProviderSession(config, out, err)
    val stopHook = StopHook(session, Runtime.getRuntime()::halt)
    Runtime.getRuntime().addShutdownHook(Thread(stopHook::stop, "provider-stop"))
    var exitCode = exitFailure
    try {
        exitCode = startAndRun(config, session, out, err)
    } finally {
        try {
            session.close()
        } catch (e: RuntimeException) {
            err.println("could not close the provider: ${describeFailure(e)}")
            exitCode = exitFailure
        } catch (e: LinkageError) {
            err.println("could not close the provider: ${describeFailure(e)}")
            exitCode = exitFailure
        }
        stopHook.closed(exitCode)
    }
    return exitCode
}

/**
 * Loads the native runtime, starts providing and shows the status until a stop. A stop requested
 * before the device starts ends here with 0.
 */
private fun startAndRun(config: ProviderConfig, session: ProviderSession, out: PrintStream, err: PrintStream): Int {
    if (session.stopRequested) {
        return exitStopped
    }
    try {
        ProviderSession.configureSdkLogs(config.stateDir.resolve(logDirName))
    } catch (e: Exception) {
        err.println("could not set the sdk log directory: ${describeFailure(e)}")
        return exitFailure
    } catch (e: LinkageError) {
        err.println("could not set the sdk log directory: ${describeFailure(e)}")
        return exitFailure
    }
    if (session.stopRequested) {
        return exitStopped
    }
    try {
        session.start()
    } catch (e: Exception) {
        err.println("could not start the provider: ${describeFailure(e)}")
        return exitFailure
    } catch (e: LinkageError) {
        err.println("could not start the provider: ${describeFailure(e)}")
        return exitFailure
    }
    out.println("provider client ${config.clientId}, instance ${config.instanceId}")
    return try {
        session.run()
    } catch (e: RuntimeException) {
        err.println("the provider failed: ${describeFailure(e)}")
        exitFailure
    } catch (e: LinkageError) {
        err.println("the provider failed: ${describeFailure(e)}")
        exitFailure
    }
}

/** The message of a failure, without a stack trace. */
fun describeFailure(e: Throwable): String {
    // a runtime that fails to load surfaces from the sdk class's initializer
    val cause = if (e is ExceptionInInitializerError) e.cause ?: e else e
    if (cause is IOException) {
        return describe(cause)
    }
    return cause.message ?: cause.javaClass.name
}

/**
 * The shutdown hook that the JVM runs after Ctrl-C or SIGTERM, and after main's own exit. After a
 * signal it stops the provider (or keeps it from starting), waits for main to close it and ends the
 * process with 0, where the JVM would exit with the signal's status (130 or 143): supervisors read 0
 * as a requested stop. When main has closed the session first, it ends the process with main's exit
 * code, such as 78 after the server rejected the credential. It always ends the process itself
 * (halt is Runtime.halt), so the signal's status never escapes, even when a signal and main's exit
 * race.
 */
class StopHook(private val session: ProviderSession, private val halt: (Int) -> Unit) {
    private val closedLatch = CountDownLatch(1)

    // main's exit code once main has closed the session; noExitCode before
    private val mainExitCode = AtomicInteger(noExitCode)

    /** Runs in the JVM's shutdown and ends the process. */
    fun stop() {
        var exitCode = mainExitCode.get()
        if (exitCode == noExitCode) {
            // a signal came before main closed the session
            session.requestStop()
            try {
                closedLatch.await(stopTimeout.inWholeMilliseconds, TimeUnit.MILLISECONDS)
            } catch (e: InterruptedException) {
                Thread.currentThread().interrupt()
            }
            exitCode = exitStopped
        }
        halt(exitCode)
    }

    /** Main has closed the session and exits with exitCode, unless a signal came first. */
    fun closed(exitCode: Int) {
        mainExitCode.compareAndSet(noExitCode, exitCode)
        closedLatch.countDown()
    }
}