code cleanup and documentation

05nelsonm · 05nelsonm · commit 0f88af0907c0 · 2020-06-20T20:07:32.000-04:00
diff --git a/sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt b/sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt
@@ -24,9 +24,9 @@ class App: Application() {
                 "TorService Channel",
                 "Tor Channel",
                 "My Sample Application",
-                6156)
+                615)
             .setActivityToBeOpenedOnTap(MainActivity::class.java, null, null, null)
-            .applySettings()
+            .applyNotificationSettings()
             .build()
     }
 }
diff --git a/sampleapp/src/main/java/io/matthewnelson/sampleapp/MyTorSettings.kt b/sampleapp/src/main/java/io/matthewnelson/sampleapp/MyTorSettings.kt
@@ -2,6 +2,9 @@ package io.matthewnelson.sampleapp
 
 import io.matthewnelson.topl_android_settings.TorSettings
 
+/**
+ * See [TorSettings] for comments on what is what.
+ * */
 class MyTorSettings: TorSettings() {
 
     override val disableNetwork: Boolean
diff --git a/topl-android-settings/src/main/java/io/matthewnelson/topl_android_settings/TorSettings.kt b/topl-android-settings/src/main/java/io/matthewnelson/topl_android_settings/TorSettings.kt
@@ -16,7 +16,7 @@ package io.matthewnelson.topl_android_settings
  *
  *     https://2019.www.torproject.org/docs/tor-manual.html.en
  *
- * @sample [io.matthewnelson.topl_service_settings.TestTorSettings]
+ * @sample [io.matthewnelson.sampleapp.MyTorSettings]
  * */
 abstract class TorSettings: SettingsConsts() {
 
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/TorServiceController.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/TorServiceController.kt
@@ -8,13 +8,46 @@ import androidx.annotation.DrawableRes
 import androidx.localbroadcastmanager.content.LocalBroadcastManager
 import io.matthewnelson.topl_service.model.ServiceNotification
 import io.matthewnelson.topl_service.service.TorService
-import io.matthewnelson.topl_service.service.ServiceActions.ServiceAction
+import io.matthewnelson.topl_service.service.ActionConsts.ServiceAction
 import androidx.core.app.NotificationCompat.NotificationVisibility
 import io.matthewnelson.topl_android_settings.TorConfigFiles
 import io.matthewnelson.topl_android_settings.TorSettings
 
 class TorServiceController private constructor() {
 
+    /**
+     * The [TorServiceController.Builder] is where you get to customize how [TorService] works
+     * for your application. Call it in `Application.onCreate` and follow along.
+     *
+     * A note about the [TorSettings] you send this. Those are the default settings which
+     * [TorService] will fall back on if [io.matthewnelson.topl_service_prefs.TorServicePrefs]
+     * has nothing in it for that particular [io.matthewnelson.topl_service_prefs.PrefsKeys].
+     * The settings get written to the `torrc` file everytime Tor is started (I plan to make this
+     * less sledgehammer-ish in the future).
+     *
+     * To update settings while your application is running you need only to instantiate
+     * [io.matthewnelson.topl_service_prefs.TorServicePrefs] and save the data using the
+     * appropriately annotated method and [io.matthewnelson.topl_service_prefs.PrefsKeys], then
+     * restart Tor (for now... ;-D).
+     *
+     * I plan to implement a
+     * [android.content.SharedPreferences.OnSharedPreferenceChangeListener] that will do this
+     * immediately for the settings that don't require a restart, but a stable release comes first).
+     *
+     * You can see how the [TorSettings] sent here are used in [TorService] by looking at
+     * [io.matthewnelson.topl_service_settings.TorServiceSettings] and [TorService.onCreate].
+     *
+     * @param [context] Context
+     * @param [buildConfigVersion] send [BuildConfig.VERSION_CODE]. Mitigates copying of geoip
+     *   files to app updates only.
+     * @param [torSettings] [TorSettings] used to create your torrc file on startup.
+     * @param [geoipAssetPath] The path to where you have your geoip file located (ex: in
+     *   assets/common directory, send this variable "common/geoip").
+     * @param [geoip6AssetPath] The path to where you have your geoip6 file located (ex: in
+     *   assets/common directory, send this variable "common/geoip6").
+     *
+     * @sample [io.matthewnelson.sampleapp.App.setupTorServices]
+     * */
     class Builder(
         private val context: Context,
         private val buildConfigVersion: Int,
@@ -25,11 +58,36 @@ class TorServiceController private constructor() {
 
         private lateinit var torConfigFiles: TorConfigFiles
 
+        /**
+         * If you wish to customize the file structure of how Tor is installed in your app,
+         * you can do so by instantiating your own [TorConfigFiles] and customizing it via
+         * the [TorConfigFiles.Builder], or overridden method [TorConfigFiles.createConfig].
+         *
+         * By default, [TorService] will call [TorConfigFiles.createConfig] using your
+         * [Context.getApplicationContext] to set up a standard directory hierarchy for Tor
+         * to operate with.
+         *
+         * See [Builder] for code samples.
+         *
+         * @return [Builder]
+         * @see [Builder.build]
+         * */
         fun useCustomTorConfigFiles(torConfigFiles: TorConfigFiles): Builder {
             this.torConfigFiles = torConfigFiles
             return this
         }
 
+        /**
+         * Customize the service notification to your application.
+         *
+         * See [Builder] for code samples.
+         *
+         * @param [channelName] Your notification channel's name.
+         * @param [channelID] Your notification channel's ID.
+         * @param [channelDescription] Your notification channel's description.
+         * @param [notificationID] Your foreground notification's ID
+         * @return [NotificationBuilder]
+         * */
         @Throws(IllegalArgumentException::class)
         fun customizeNotification(
             channelName: String,
@@ -41,7 +99,7 @@ class TorServiceController private constructor() {
                 channelName.isNotEmpty() &&
                 channelID.isNotEmpty() &&
                 channelDescription.isNotEmpty()
-            ) { "channelName & channelID must not be empty." }
+            ) { "channelName, channelID, & channelDescription must not be empty." }
 
             return NotificationBuilder(
                 this,
@@ -52,6 +110,11 @@ class TorServiceController private constructor() {
             )
         }
 
+        /**
+         * Where you get to customize how your foreground notification will look/function.
+         *
+         * See [Builder] for code samples.
+         * */
         class NotificationBuilder(
             private val builder: Builder,
             channelName: String,
@@ -68,6 +131,16 @@ class TorServiceController private constructor() {
                     notificationID
                 )
 
+            /**
+             * For when your user taps the TorService notification.
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [clazz] The Activity to be opened when tapped.
+             * @param [intentExtrasKey]? The key for if you with to add extras in the PendingIntent.
+             * @param [intentExtras]? The extras that will be sent in the PendingIntent.
+             * @param [intentRequestCode]? The request code - Defaults to 0 if not set.
+             * */
             fun setActivityToBeOpenedOnTap(
                 clazz: Class<*>,
                 intentExtrasKey: String?,
@@ -81,54 +154,147 @@ class TorServiceController private constructor() {
                 return this
             }
 
+            /**
+             * Defaults to Orbot/TorBrowser's icon.
+             *
+             * The small icon you wish to display when Tor's State is
+             * [io.matthewnelson.topl_android_settings.TorStates.TorState.ON].
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [drawableRes] Drawable resource id.
+             * @return [NotificationBuilder]
+             * */
             fun setImageTorOn(@DrawableRes drawableRes: Int): NotificationBuilder {
                 serviceNotification.imageOn = drawableRes
                 return this
             }
 
+            /**
+             * Defaults to Orbot/TorBrowser's icon.
+             *
+             * The small icon you wish to display when Tor's State is
+             * [io.matthewnelson.topl_android_settings.TorStates.TorState.OFF].
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [drawableRes] Drawable resource id.
+             * @return [NotificationBuilder]
+             * */
             fun setImageTorOff(@DrawableRes drawableRes: Int): NotificationBuilder {
                 serviceNotification.imageOff = drawableRes
                 return this
             }
 
+            /**
+             * Defaults to Orbot/TorBrowser's icon.
+             *
+             * The small icon you wish to display when bandwidth is being used.
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [drawableRes] Drawable resource id.
+             * @return [NotificationBuilder]
+             * */
             fun setImageTorDataTransfer(@DrawableRes drawableRes: Int): NotificationBuilder {
                 serviceNotification.imageData = drawableRes
                 return this
             }
 
+            /**
+             * Defaults to Orbot/TorBrowser's icon.
+             *
+             * The small icon you wish to display when Tor is having problems.
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [drawableRes] Drawable resource id.
+             * @return [NotificationBuilder]
+             * */
             fun setImageTorErrors(@DrawableRes drawableRes: Int): NotificationBuilder {
                 serviceNotification.imageError = drawableRes
                 return this
             }
 
+            /**
+             * Defaults to white
+             *
+             * The color you wish to display when Tor's State is
+             * [io.matthewnelson.topl_android_settings.TorStates.TorState.ON].
+             *
+             * See [Builder] for code samples.
+             *
+             * @param [colorRes] Color resource id.
+             * @return [NotificationBuilder]
+             * */
             fun setColorWhenTorOn(@ColorRes colorRes: Int): NotificationBuilder {
-                serviceNotification.colorRes = colorRes
+                serviceNotification.colorWhenOn = colorRes
                 return this
             }
 
+            /**
+             * Defaults to NotificationVisibility.VISIBILITY_SECRET
+             *
+             * The visibility of your notification on the user's lock screen.
+             *
+             * See [Builder] for code samples.
+             *
+             * @return [NotificationBuilder]
+             * */
             fun setVisibility(@NotificationVisibility visibility: Int): NotificationBuilder {
                 if (visibility in -1..1)
                     serviceNotification.visibility = visibility
                 return this
             }
 
+            /**
+             * Disabled by Default
+             *
+             * Enable on the notification the ability to *restart* Tor.
+             *
+             * See [Builder] for code samples.
+             *
+             * @return [NotificationBuilder]
+             * */
             fun enableTorRestartButton(): NotificationBuilder {
                 serviceNotification.enableRestartButton = true
                 return this
             }
 
+            /**
+             * Disabled by Default
+             *
+             * Enable on the notification the ability to *stop* Tor.
+             *
+             * See [Builder] for code samples.
+             *
+             * @return [NotificationBuilder]
+             * */
             fun enableTorStopButton(): NotificationBuilder {
                 serviceNotification.enableStopButton = true
                 return this
             }
 
-            fun applySettings(): Builder {
+            /**
+             * Initialize settings.
+             *
+             * See [Builder] for code samples.
+             *
+             * @return [Builder]
+             * */
+            fun applyNotificationSettings(): Builder {
                 ServiceNotification.initialize(serviceNotification)
                 return builder
             }
 
         }
 
+        /**
+         * Initializes [TorService] setup and enables the ability to call methods in the
+         * [Companion] object.
+         *
+         * See [Builder] for code samples.
+         * */
         fun build() {
             val torConfigFiles =
                 if (::torConfigFiles.isInitialized) {
@@ -151,6 +317,9 @@ class TorServiceController private constructor() {
         }
     }
 
+    /**
+     * Where everything needed to interact with [TorService] resides.
+     * */
     companion object {
 
         private lateinit var appContext: Context
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/model/ServiceNotification.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/model/ServiceNotification.kt
@@ -13,6 +13,11 @@ import androidx.core.app.NotificationCompat.NotificationVisibility
 import io.matthewnelson.topl_service.R
 import io.matthewnelson.topl_service.service.TorService
 
+/**
+ * Everything to do with [TorService]'s notification.
+ *
+ * See [io.matthewnelson.topl_service.TorServiceController.Builder.NotificationBuilder]
+ * */
 internal class ServiceNotification(
     private val channelName: String,
     private val channelID: String,
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyEventBroadcaster.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyEventBroadcaster.kt
@@ -1,21 +1,32 @@
 package io.matthewnelson.topl_service.onionproxy
 
-import android.content.Context
 import android.util.Log
 import androidx.localbroadcastmanager.content.LocalBroadcastManager
 import io.matthewnelson.topl_android.broadcaster.DefaultEventBroadcaster
-import io.matthewnelson.topl_android_settings.TorSettings
-
-class OnionProxyEventBroadcaster(
-    private val context: Context,
-    private val torSettings: TorSettings
+import io.matthewnelson.topl_service.service.TorService
+import io.matthewnelson.topl_service_settings.TorServiceSettings
+
+/**
+ * [io.matthewnelson.topl_android.OnionProxyManager] utilizes this customized class for
+ * broadcasting things while it is operating (such as Tor's State, operation errors,
+ * debugging, etc).
+ *
+ * [OnionProxyEventListener] utilizes this class by sending it what Tor is spitting out
+ * (selectively curated, ofc).
+ *
+ * @param [torService] [TorService] for context.
+ * @param [torSettings] [TorServiceSettings]
+ * */
+internal class OnionProxyEventBroadcaster(
+    private val torService: TorService,
+    private val torSettings: TorServiceSettings
 ): DefaultEventBroadcaster(torSettings) {
 
-    private companion object {
-        const val TAG = "EventBroadcaster"
+    companion object {
+        private const val TAG = "EventBroadcaster"
     }
 
-    private val broadcastManager = LocalBroadcastManager.getInstance(context)
+    private val broadcastManager = LocalBroadcastManager.getInstance(torService.applicationContext)
 
     override fun broadcastBandwidth(upload: Long, download: Long, written: Long, read: Long) {
         Log.d(TAG, "BANDWIDTH__upload: $upload, download: $download, written: $written, read: $read")
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyEventListener.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyEventListener.kt
@@ -5,6 +5,18 @@ import io.matthewnelson.topl_android.listener.BaseEventListener
 import io.matthewnelson.topl_service.service.TorService
 import net.freehaven.tor.control.TorControlCommands
 
+/**
+ * [io.matthewnelson.topl_android.OnionProxyManager] registers this class in it's
+ * [io.matthewnelson.topl_android.OnionProxyManager.start] method such that messages from
+ * Tor get funneled here. They get modify as needed, then shipped to it's final destination.
+ *
+ * TODO: Decide whether or not I wish to ship it directly to
+ *  [io.matthewnelson.topl_service.TorServiceController.Companion] as a Flow so library
+ *  users can easily hook in, or if the EventBroadcaster should... (Might be too confusing).
+ *
+ *  @param [torService] [TorService] for context.
+ *  @param [eventBroadcaster] [OnionProxyEventBroadcaster] for broadcasting data.
+ * */
 internal class OnionProxyEventListener(
     private val torService: TorService,
     private val eventBroadcaster: OnionProxyEventBroadcaster
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyInstaller.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/onionproxy/OnionProxyInstaller.kt
diff --git a/topl-service/src/main/java/io/matthewnelson/topl_service/service/TorService.kt b/topl-service/src/main/java/io/matthewnelson/topl_service/service/TorService.kt

Original file line number	Diff line number	Diff line change
`@@ -24,9 +24,9 @@ class App: Application() {`
`24`	`24`	`"TorService Channel",`
`25`	`25`	`"Tor Channel",`
`26`	`26`	`"My Sample Application",`
`27`		`- 6156)`
	`27`	`+ 615)`
`28`	`28`	`.setActivityToBeOpenedOnTap(MainActivity::class.java, null, null, null)`
`29`		`- .applySettings()`
	`29`	`+ .applyNotificationSettings()`
`30`	`30`	`.build()`
`31`	`31`	`}`
`32`	`32`	`}`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ package io.matthewnelson.topl_android_settings`
`16`	`16`	`*`
`17`	`17`	`* https://2019.www.torproject.org/docs/tor-manual.html.en`
`18`	`18`	`*`
`19`		`- * @sample [io.matthewnelson.topl_service_settings.TestTorSettings]`
	`19`	`+ * @sample [io.matthewnelson.sampleapp.MyTorSettings]`
`20`	`20`	`* */`
`21`	`21`	`abstract class TorSettings: SettingsConsts() {`
`22`	`22`