Skip to content
This repository was archived by the owner on Dec 18, 2022. It is now read-only.

Commit c7f3a40

Browse files
05nelsonm05nelsonm
committed
clean up TorConfig and add documentation
1 parent 22c172f commit c7f3a40

File tree

1 file changed

+104
-71
lines changed
  • topl-android/src/main/java/io/matthewnelson/topl_android

1 file changed

+104
-71
lines changed

‎topl-android/src/main/java/io/matthewnelson/topl_android/TorConfig.kt

Lines changed: 104 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -18,30 +18,36 @@ import java.io.IOException
1818

1919
/**
2020
* Holds Tor configuration information.
21+
*
22+
* See [Companion.createConfig] or [Builder] to instantiate.
2123
*/
2224
class TorConfig private constructor(
2325
val geoIpFile: File,
2426
val geoIpv6File: File,
25-
torrcFile: File,
27+
mTorrcFile: File,
2628
val torExecutableFile: File,
2729
val hiddenServiceDir: File,
2830
val dataDir: File,
2931
val configDir: File,
3032
val homeDir: File,
3133

3234
/**
33-
* The <base32-encoded-fingerprint>.onion domain name for this hidden service. If the hidden service is
34-
* restricted to authorized clients only, this file also contains authorization data for all clients.
35+
* The <base32-encoded-fingerprint>.onion domain name for this hidden service.
36+
* If the hidden service is restricted to authorized clients only, this file
37+
* also contains authorization data for all clients.
3538
*
36-
* @return hostname file
37-
</base32-encoded-fingerprint> */
39+
* @return [hostnameFile] </base32-encoded-fingerprint>
40+
* */
3841
val hostnameFile: File,
3942

4043
/**
41-
* Used for cookie authentication with the controller. Location can be overridden by the CookieAuthFile config option.
42-
* Regenerated on startup. See control-spec.txt in torspec for details. Only used when cookie authentication is enabled.
44+
* Used for cookie authentication with the controller. Location can be
45+
* overridden by the CookieAuthFile config option. Regenerated on startup.
46+
* See control-spec.txt in torspec for details.
4347
*
44-
* @return
48+
* Only used when cookie authentication is enabled.
49+
*
50+
* @return [cookieAuthFile]
4551
*/
4652
val cookieAuthFile: File,
4753
val libraryPath: File,
@@ -50,9 +56,9 @@ class TorConfig private constructor(
5056
val installDir: File,
5157

5258
/**
53-
* When tor starts it waits for the control port and cookie auth files to be created before it proceeds to the
54-
* next step in startup. If these files are not created after a certain amount of time, then the startup has
55-
* failed.
59+
* When tor starts it waits for the control port and cookie auth files to be created
60+
* before it proceeds to the next step in startup. If these files are not created
61+
* after a certain amount of time, then the startup has failed.
5662
*
5763
* This method returns how much time to wait in seconds until failing the startup.
5864
*/
@@ -74,78 +80,94 @@ class TorConfig private constructor(
7480
/**
7581
* Convenience method for if you're including in your App's jniLibs directory
7682
* the `libTor.so` binary, or utilizing those maintained by this project.
83+
*
84+
* @param [context] Context
85+
* @param [configDir] context.getDir("dir_name_here", Context.MODE_PRIVATE)
86+
* @param [dataDir] if you wish it in a different location than lib/tor
7787
* */
7888
fun createConfig(context: Context, configDir: File, dataDir: File? = null): TorConfig {
79-
val nativeDir = File(context.applicationInfo.nativeLibraryDir)
80-
val builder = Builder(nativeDir, configDir)
89+
val installDir = File(context.applicationInfo.nativeLibraryDir)
90+
val builder = Builder(installDir, configDir)
8191
if (dataDir != null)
8292
builder.dataDir(dataDir)
8393
return builder.build()
8494
}
95+
96+
/**
97+
* Convenience method for setting up all of your files and directories in their
98+
* default locations.
99+
*
100+
* @param context Context
101+
* */
102+
fun createConfig(context: Context): TorConfig =
103+
createConfig(context, context.getDir("torservice", Context.MODE_PRIVATE))
85104
}
86105

87106
private val configLock = Object()
88-
private var mTorrcFile = torrcFile
89-
fun getTorrcFile(): File = mTorrcFile
107+
var torrcFile = mTorrcFile
108+
private set
90109

91110
/**
92-
* Resolves the tor configuration file. If the torrc file hasn't been set, then this method will attempt to
93-
* resolve the config file by looking in the root of the $configDir and then in $user.home directory
111+
* Resolves the tor configuration file. If the torrc file hasn't been set, then
112+
* this method will attempt to resolve the config file by looking in the root of
113+
* the $configDir and then in $user.home directory
94114
*
95-
* @return torrc file
96-
* @throws IOException if torrc file is not resolved
115+
* @throws [IOException] If torrc file is not resolved.
116+
* @throws [SecurityException] if unable to access the file.
117+
*
118+
* @return [torrcFile]
97119
*/
98-
@Throws(IOException::class)
120+
@Throws(IOException::class, SecurityException::class)
99121
fun resolveTorrcFile(): File {
100122

101123
synchronized(configLock) {
102-
if (!mTorrcFile.exists()) {
103-
var tmpTorrcFile = File(configDir,
104-
TORRC_NAME
105-
)
124+
if (!torrcFile.exists()) {
125+
var tmpTorrcFile = File(configDir, TORRC_NAME)
106126

107127
if (!tmpTorrcFile.exists()) {
108128
tmpTorrcFile = File(homeDir, ".$TORRC_NAME")
109129

110130
if (!tmpTorrcFile.exists()) {
111-
mTorrcFile = File(configDir,
112-
TORRC_NAME
113-
)
131+
torrcFile = File(configDir, TORRC_NAME)
114132

115-
if (!mTorrcFile.createNewFile()) {
133+
if (!torrcFile.createNewFile()) {
116134
throw IOException("Failed to create torrc file")
117135
}
118136

119137
} else {
120-
mTorrcFile = tmpTorrcFile
138+
torrcFile = tmpTorrcFile
121139
}
122140
} else {
123-
mTorrcFile = tmpTorrcFile
141+
torrcFile = tmpTorrcFile
124142
}
125143
}
126-
return mTorrcFile
144+
return torrcFile
127145
}
128146
}
129147

130148
override fun toString(): String {
131-
return "TorConfig{" +
132-
"geoIpFile=" + geoIpFile +
133-
", geoIpv6File=" + geoIpv6File +
134-
", torrcFile=" + mTorrcFile +
135-
", torExecutableFile=" + torExecutableFile +
136-
", hiddenServiceDir=" + hiddenServiceDir +
137-
", dataDir=" + dataDir +
138-
", configDir=" + configDir +
139-
", installDir=" + installDir +
140-
", homeDir=" + homeDir +
141-
", hostnameFile=" + hostnameFile +
142-
", cookieAuthFile=" + cookieAuthFile +
143-
", libraryPath=" + libraryPath +
144-
'}'
149+
return "TorConfig{ " +
150+
"geoIpFile=$geoIpFile, " +
151+
"geoIpv6File=$geoIpv6File, " +
152+
"torrcFile=$torrcFile, " +
153+
"torExecutableFile=$torExecutableFile, " +
154+
"hiddenServiceDir=$hiddenServiceDir, " +
155+
"dataDir=$dataDir, " +
156+
"configDir=$configDir, " +
157+
"installDir=$installDir, " +
158+
"homeDir=$homeDir, " +
159+
"hostnameFile=$hostnameFile, " +
160+
"cookieAuthFile=$cookieAuthFile, " +
161+
"libraryPath=$libraryPath }"
145162
}
146163

147164
/**
148165
* Builder for TorConfig.
166+
*
167+
* See also [Companion.createConfig] for convenience methods.
168+
*
169+
* @param [installDir] directory where the tor binaries are installed.
170+
* @param [configDir] directory where the filesystem will be setup for tor.
149171
*/
150172
class Builder(private val installDir: File, private val configDir: File) {
151173

@@ -166,12 +188,12 @@ class TorConfig private constructor(
166188
/**
167189
* Home directory of user.
168190
*
191+
* Default value: $home.user if $home.user environment property exists, otherwise
192+
* $configDir. On Android, this will always default to $configDir.
169193
*
170-
* Default value: $home.user if $home.user environment property exists, otherwise $configDir. On Android, this
171-
* will always default to $configDir.
194+
* @param [homeDir] the home directory of the user
172195
*
173-
* @param homeDir the home directory of the user
174-
* @return builder
196+
* @return [Builder]
175197
*/
176198
fun homeDir(homeDir: File): Builder {
177199
this.mHomeDir = homeDir
@@ -184,16 +206,19 @@ class TorConfig private constructor(
184206
}
185207

186208
/**
187-
* Store data files for a hidden service in DIRECTORY. Every hidden service must have a separate directory.
188-
* You may use this option multiple times to specify multiple services. If DIRECTORY does not exist, Tor will
189-
* create it. (Note: in current versions of Tor, if DIRECTORY is a relative path, it will be relative to the
190-
* current working directory of Tor instance, not to its DataDirectory. Do not rely on this behavior; it is not
191-
* guaranteed to remain the same in future versions.)
209+
* Store data files for a hidden service in DIRECTORY. Every hidden service must
210+
* have a separate directory. You may use this option multiple times to specify
211+
* multiple services. If DIRECTORY does not exist, Tor will create it. (Note: in
212+
* current versions of Tor, if DIRECTORY is a relative path, it will be relative
213+
* to the current working directory of Tor instance, not to its DataDirectory. Do
214+
* not rely on this behavior; it is not guaranteed to remain the same in future
215+
* versions.)
192216
*
193217
* Default value: $configDir/hiddenservices
194218
*
195-
* @param directory hidden services directory
196-
* @return builder
219+
* @param [directory] hidden services directory
220+
*
221+
* @return [Builder]
197222
*/
198223
fun hiddenServiceDir(directory: File): Builder {
199224
mHiddenServiceDir = directory
@@ -205,8 +230,9 @@ class TorConfig private constructor(
205230
*
206231
* Default value: $configDir/geoip6
207232
*
208-
* @param file geoip6 file
209-
* @return builder
233+
* @param [file] geoip6 file
234+
*
235+
* @return [Builder]
210236
*/
211237
fun geoipv6(file: File): Builder {
212238
mGeoIpv6File = file
@@ -218,8 +244,9 @@ class TorConfig private constructor(
218244
*
219245
* Default value: $configDir/geoip
220246
*
221-
* @param file geoip file
222-
* @return builder
247+
* @param [file] geoip file
248+
*
249+
* @return [Builder]
223250
*/
224251
fun geoip(file: File): Builder {
225252
mGeoIpFile = file
@@ -231,8 +258,9 @@ class TorConfig private constructor(
231258
*
232259
* Default value: $configDir/lib/tor
233260
*
234-
* @param directory directory where tor runtime data is stored
235-
* @return builder
261+
* @param [directory] directory where tor runtime data is stored
262+
*
263+
* @return [Builder]
236264
*/
237265
fun dataDir(directory: File): Builder {
238266
mDataDir = directory
@@ -244,8 +272,9 @@ class TorConfig private constructor(
244272
*
245273
* Default value: $configDir/torrc
246274
*
247-
* @param file
248-
* @return
275+
* @param [file] your torrc file
276+
*
277+
* @return [Builder]
249278
*/
250279
fun torrc(file: File): Builder {
251280
mTorrcFile = file
@@ -273,23 +302,27 @@ class TorConfig private constructor(
273302
}
274303

275304
/**
276-
* When tor starts it waits for the control port and cookie auth files to be created before it proceeds to the
277-
* next step in startup. If these files are not created after a certain amount of time, then the startup has
278-
* failed.
305+
* When tor starts it waits for the control port and cookie auth files to be
306+
* created before it proceeds to the next step in startup. If these files are
307+
* not created after a certain amount of time, then the startup has failed.
279308
*
280309
* This method specifies how much time to wait until failing the startup.
281310
*
282-
* @param timeout in seconds
311+
* Default value is 15 seconds
312+
*
313+
* @param [timeoutSeconds] Int
314+
*
315+
* @return [Builder]
283316
*/
284-
fun fileCreationTimeout(timeout: Int): Builder {
285-
mFileCreationTimeout = timeout
317+
fun fileCreationTimeout(timeoutSeconds: Int): Builder {
318+
mFileCreationTimeout = timeoutSeconds
286319
return this
287320
}
288321

289322
/**
290323
* Builds torConfig and sets default values if not explicitly configured through builder.
291324
*
292-
* @return torConfig
325+
* @return [TorConfig]
293326
*/
294327
fun build(): TorConfig {
295328
if (!::mHomeDir.isInitialized) {

0 commit comments

Comments
 (0)