fix: Write API documentation (#54)

* fix: Write API documentation

* move api-docs.md

* document endpoints

* rename PrivateThirdPartyEndpoint:importAuthorization()

* fix GH action

* complete

* build docs in CI

* fix imports

* fix import

.github/workflows/ci.yml

@@ -16,9 +16,14 @@ jobs:
           java-version: 8
       - name: Validate Gradle wrapper
         uses: gradle/wrapper-validation-action@v1
-      - uses: eskatos/gradle-command-action@v1
+      - name: Build project
+        uses: eskatos/gradle-command-action@v1
+        with:
+          arguments: build dokkaHtml --scan
+      - name: Generate documentation
+        uses: eskatos/gradle-command-action@v1
         with:
-          arguments: build --scan
+          arguments: dokkaHtml
       # - uses: eskatos/gradle-command-action@v1
       #   with:
       #     arguments: jacocoTestCoverageVerification
@@ -48,11 +53,11 @@ jobs:
         run: |
           set -x -o nounset -o errexit -o pipefail
           cd ./build/dokka/html
-          mv ./styles ./images ./scripts navigation.html ./relaydroid/
-          find ./relaydroid/ -name '*.html' -print0 | xargs -0 sed -i 's;../styles/;styles/;g'
-          find ./relaydroid/ -name '*.html' -print0 | xargs -0 sed -i 's;../images/;images/;g'
-          find ./relaydroid/ -name '*.html' -print0 | xargs -0 sed -i 's;../scripts/;scripts/;g'
-          find ./relaydroid/ -name '*.html' -print0 | xargs -0 sed -i 's;pathToRoot = "../;pathToRoot = ";g'
+          mv ./styles ./images ./scripts navigation.html ./lib/
+          find ./lib/ -name '*.html' -print0 | xargs -0 sed -i 's;../styles/;styles/;g'
+          find ./lib/ -name '*.html' -print0 | xargs -0 sed -i 's;../images/;images/;g'
+          find ./lib/ -name '*.html' -print0 | xargs -0 sed -i 's;../scripts/;scripts/;g'
+          find ./lib/ -name '*.html' -print0 | xargs -0 sed -i 's;pathToRoot = "../;pathToRoot = ";g'
           sed -i 's;href="relaydroid/;href=";g' ./relaydroid/navigation.html
 
       - name: Release

build.gradle

@@ -15,7 +15,6 @@ buildscript {
 
 plugins {
     id("org.jetbrains.kotlin.jvm") version "$kotlinVersion"
-    id("org.jetbrains.dokka") version "1.4.20"
     id('idea')
 }
 
@@ -33,15 +32,6 @@ java {
     withSourcesJar()
 }
 
-dokkaHtml.configure {
-    dokkaSourceSets {
-        configureEach {
-            reportUndocumented.set(true)
-            includes.from("api-docs.md")
-        }
-    }
-}
-
 gradleEnterprise {
     buildScan {
         termsOfServiceUrl = "https://gradle.com/terms-of-service"

gradle.properties

@@ -1,15 +1,13 @@
 ## For more details on how to configure your build environment visit
 # http://www.gradle.org/docs/current/userguide/build_environment.html
-#
-# Specifies the JVM arguments used for the daemon process.
-# The setting is particularly useful for tweaking memory settings.
-# Default value: -Xmx1024m -XX:MaxPermSize=256m
-# org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
-#
+
+org.gradle.jvmargs=-Xmx4096M -XX:MaxPermSize=512m
+
 # When configured, Gradle will run in incubating parallel mode.
 # This option should only be used with decoupled projects. More details, visit
 # http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
 # org.gradle.parallel=true
+
 #Mon Feb 01 16:19:46 WET 2021
 android.useAndroidX=true
 

lib/api-docs.md

@@ -0,0 +1,13 @@
+# Module lib
+
+# Package tech.relaycorp.relaydroid
+
+Root package for the endpoint library.
+
+# Package tech.relaycorp.relaydroid.endpoint
+
+Handling of first- and third-party endpoints.
+
+# Package tech.relaycorp.relaydroid.messaging
+
+Handling of service messages.

lib/build.gradle

@@ -4,6 +4,7 @@ plugins {
   id 'kotlin-kapt'
   id 'maven-publish'
   id 'org.jlleitschuh.gradle.ktlint' version "10.0.0"
+  id 'org.jetbrains.dokka' version "1.4.20"
 }
 
 apply from: 'jacoco.gradle'
@@ -105,6 +106,15 @@ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
   }
 }
 
+dokkaHtml.configure {
+    dokkaSourceSets {
+        configureEach {
+            reportUndocumented.set(true)
+            includes.from("api-docs.md")
+        }
+    }
+}
+
 ktlint {
   verbose = true
   android = true

lib/src/main/java/tech/relaycorp/relaydroid/GatewayClientImpl.kt

@@ -18,8 +18,8 @@ import tech.relaycorp.relaydroid.background.ServiceInteractor
 import tech.relaycorp.relaydroid.common.Logging.logger
 import tech.relaycorp.relaydroid.messaging.IncomingMessage
 import tech.relaycorp.relaydroid.messaging.OutgoingMessage
+import tech.relaycorp.relaydroid.messaging.ReceiveMessageException
 import tech.relaycorp.relaydroid.messaging.ReceiveMessages
-import tech.relaycorp.relaydroid.messaging.ReceiveMessagesException
 import tech.relaycorp.relaydroid.messaging.RejectedMessageException
 import tech.relaycorp.relaydroid.messaging.SendMessage
 import tech.relaycorp.relaydroid.messaging.SendMessageException
@@ -30,6 +30,9 @@ import tech.relaycorp.relaynet.bindings.pdc.ServerException
 import tech.relaycorp.relaynet.messages.control.PrivateNodeRegistration
 import tech.relaycorp.relaynet.messages.control.PrivateNodeRegistrationRequest
 
+/**
+ * Private gateway client.
+ */
 public class GatewayClientImpl
 internal constructor(
     private val coroutineContext: CoroutineContext = Dispatchers.IO,
@@ -44,6 +47,9 @@ internal constructor(
 
     private var gwServiceInteractor: ServiceInteractor? = null
 
+    /**
+     * Bind to the gateway to be able to communicate with it.
+     */
     @Throws(GatewayBindingException::class)
     public suspend fun bind() {
         withContext(coroutineContext) {
@@ -66,6 +72,11 @@ internal constructor(
         }
     }
 
+    /**
+     * Unbind from the gateway.
+     *
+     * Make sure to call this when you no longer need to communicate with the gateway.
+     */
     public fun unbind() {
         gwServiceInteractor?.unbind()
         gwServiceInteractor = null
@@ -148,6 +159,10 @@ internal constructor(
     }
 
     private val incomingMessageChannel = BroadcastChannel<IncomingMessage>(1)
+
+    /**
+     * Receive messages from the gateway.
+     */
     public fun receiveMessages(): Flow<IncomingMessage> = incomingMessageChannel.asFlow()
 
     // Internal
@@ -172,7 +187,7 @@ internal constructor(
                 receiveMessages
                     .receive()
                     .collect(incomingMessageChannel::send)
-            } catch (exp: ReceiveMessagesException) {
+            } catch (exp: ReceiveMessageException) {
                 logger.log(Level.SEVERE, "Could not receive new messages", exp)
             } catch (exp: GatewayProtocolException) {
                 logger.log(Level.SEVERE, "Could not receive new messages", exp)
@@ -190,17 +205,26 @@ internal constructor(
     }
 }
 
-// General class for all exceptions deriving from interactions with the Gateway
+/**
+ * General class for all exceptions deriving from interactions with the gateway.
+ */
 public open class GatewayException(message: String, cause: Throwable? = null) :
     RelaydroidException(message, cause)
 
-// Non-recoverable protocol-level discrepancies when interacting with the Gateway
+/**
+ * Non-recoverable, protocol-level discrepancies when interacting with the gateway.
+ */
 public open class GatewayProtocolException(message: String, cause: Throwable? = null) :
     GatewayException(message, cause)
 
-// Not bound or unable to bind to the Gateway
+/**
+ * Not bound or failure to bind to the gateway.
+ */
 public class GatewayBindingException(message: String, cause: Throwable? = null) :
     GatewayException(message, cause)
 
+/**
+ * Failure to register a first-party endpoint.
+ */
 public class RegistrationFailedException(message: String, cause: Throwable? = null) :
     GatewayException(message, cause)

lib/src/main/java/tech/relaycorp/relaydroid/Relaynet.kt

@@ -13,6 +13,9 @@ public object Relaynet {
     internal const val GATEWAY_SYNC_COMPONENT =
         "tech.relaycorp.gateway.background.endpoint.GatewaySyncService"
 
+    /**
+     * Set up the endpoint library.
+     */
     public suspend fun setup(context: Context) {
         storage = StorageImpl(EncryptedDiskPersistence(context))
         gatewayClientImpl = GatewayClientImpl(
@@ -24,5 +27,9 @@ public object Relaynet {
     internal lateinit var gatewayClientImpl: GatewayClientImpl
 }
 
+/**
+ * Private gateway client.
+ */
 public val GatewayClient: GatewayClientImpl get() = Relaynet.gatewayClientImpl
+
 internal val Storage get() = Relaynet.storage

lib/src/main/java/tech/relaycorp/relaydroid/endpoint/AuthorizationBundle.kt

@@ -1,6 +1,16 @@
 package tech.relaycorp.relaydroid.endpoint
 
+/**
+ * Parcel Delivery Authorization (PDA) and support data for the grantee to use the PDA.
+ */
 public class AuthorizationBundle(
+    /**
+     * The ASN.1 DER encoding of the PDA.
+     */
     public val pdaSerialized: ByteArray,
+
+    /**
+     * The ASN.1 DER encoding of each certificate in the PDA chain (excluding the PDA itself).
+     */
     public val pdaChainSerialized: List<ByteArray>
 )

lib/src/main/java/tech/relaycorp/relaydroid/endpoint/Endpoint.kt

@@ -1,5 +1,11 @@
 package tech.relaycorp.relaydroid.endpoint
 
+/**
+ * Relaynet endpoint.
+ */
 public interface Endpoint {
+    /**
+     * The private or public address of a private or public endpoint, respectively.
+     */
     public val address: String
 }

lib/src/main/java/tech/relaycorp/relaydroid/endpoint/FirstPartyEndpoint.kt

@@ -17,6 +17,9 @@ import tech.relaycorp.relaynet.wrappers.privateAddress
 import tech.relaycorp.relaynet.wrappers.x509.Certificate
 import tech.relaycorp.relaynet.wrappers.x509.CertificateException
 
+/**
+ * An endpoint owned by the current instance of the app.
+ */
 public class FirstPartyEndpoint
 internal constructor(
     internal val keyPair: KeyPair,
@@ -26,10 +29,16 @@ internal constructor(
 
     public override val address: String get() = keyPair.public.privateAddress
 
+    /**
+     * The RSA public key of the endpoint.
+     */
     public val publicKey: PublicKey get() = keyPair.public
 
     internal val pdaChain: List<Certificate> get() = listOf(identityCertificate, gatewayCertificate)
 
+    /**
+     * Issue a PDA for a third-party endpoint.
+     */
     @Throws(CertificateException::class)
     public fun issueAuthorization(
         thirdPartyEndpoint: ThirdPartyEndpoint,
@@ -41,6 +50,9 @@ internal constructor(
         )
     }
 
+    /**
+     * Issue a PDA for a third-party endpoint using its public key.
+     */
     @Throws(CertificateException::class)
     public fun issueAuthorization(
         thirdPartyEndpointPublicKeySerialized: ByteArray,
@@ -74,6 +86,9 @@ internal constructor(
         )
     }
 
+    /**
+     * Delete the endpoint.
+     */
     @Throws(PersistenceException::class)
     public suspend fun delete() {
         Storage.identityKeyPair.delete(address)
@@ -88,6 +103,9 @@ internal constructor(
     }
 
     public companion object {
+        /**
+         * Generate endpoint and register it with the private gateway.
+         */
         @Throws(
             RegistrationFailedException::class,
             GatewayProtocolException::class,
@@ -105,10 +123,13 @@ internal constructor(
             return endpoint
         }
 
+        /**
+         * Load an endpoint by its address.
+         */
         @Throws(PersistenceException::class)
-        public suspend fun load(address: String): FirstPartyEndpoint? {
-            return Storage.identityKeyPair.get(address)?.let { keyPair ->
-                Storage.identityCertificate.get(address)?.let { certificate ->
+        public suspend fun load(privateAddress: String): FirstPartyEndpoint? {
+            return Storage.identityKeyPair.get(privateAddress)?.let { keyPair ->
+                Storage.identityCertificate.get(privateAddress)?.let { certificate ->
                     Storage.gatewayCertificate.get()?.let { gwCertificate ->
                         FirstPartyEndpoint(
                             keyPair,
@@ -122,5 +143,8 @@ internal constructor(
     }
 }
 
+/**
+ * Failure to issue a PDA.
+ */
 public class AuthorizationIssuanceException(message: String, cause: Throwable) :
     RelaydroidException(message, cause)