BuilderScopeHS

A DSL builder scope for configuring TorOption.HiddenServiceDir and other applicable TorOption for Hidden Services (i.e. those options that contain the attribute TorOption.Attribute.HIDDEN_SERVICE).

TL;DR directory, version, and at least 1 port are required.

At a minimum, tor requires TorOption.HiddenServiceDir and at least 1 TorOption.HiddenServicePort be defined. Tor then uses its hard coded defaults for all other Hidden Service options, unless overridden.

This builder scope takes it further in that it also requires the definition of TorOption.HiddenServiceVersion, as well (see version).

The requirement for the version expression is because if, in a future release of the tor C library, the default value changes to a newer version (and subsequently, the old version deprecated) that may be a source of conflict if an explicit definition is not there (surprise upgrade from v3 ->v4?). In that event, kmp-tor consumers using this builder scope will be unaffected by the change to the tor C library. A conscious decision to migrate to the new version, and update usages of this builder, would need to be made.

NOTE: Any misconfiguration will result in an IllegalArgumentException when the scope goes to build.

e.g. (Minimum requirements with directory, version and port defined)

// Also available via HiddenServiceDir.asSetting
TorConfig.Builder {

    // No try/catch needed b/c minimums are met
    TorOption.HiddenServiceDir.tryConfigure {
        // Must be defined
        directory("/path/to/this/hs/dir".toFile())

        // Must be defined
        version(3)

        // At least 1 port must be defined
        port(virtual = Port.HTTPS) {
            try {
                target(unixSocket = "/path/to/server/uds.sock".toFile())
            } catch (_: UnsupportedOperationException) {
                target(port = 8443.toPort())
            }
        }

        // ...
    }
}

See also