TorSession

Minimal lifecycle interface for driving (or mocking) an embedded Tor instance.

protocol TorSession : Sendable

Overview

TorSession is the seam between swift-tor’s concrete TorClient actor and downstream code that wants to exercise Tor’s lifecycle without paying the real-world cost of it. A production conformer launches tor_run_main() on a dedicated thread, negotiates with the Tor network (guard selection, consensus download, circuit build — typically 30–60 s), and exposes the SOCKS endpoint when complete. A test conformer returns a fabricated endpoint immediately, pushes synthetic TorEvent values through its events stream, and never touches the network.

The surface is deliberately narrow: one method each for start/stop/wait, one async-get property for the SOCKS endpoint, and one stream property for lifecycle events. Anything richer (GETINFO, addOnion, URLSession proxy helpers) lives on TorClient directly and is out of scope for mocking through this protocol.

Note

Conformance is Sendable — all methods are async (or async throws) and all properties are async getters, so implementations are free to use actor isolation, Mutex, or any other serialisation strategy for internal state.

Important

Mock conformers should preserve causal ordering: a call to waitUntilBootstrapped(timeout:) must observe at least one start() before returning successfully, otherwise downstream state machines that assume “bootstrapped implies started” will drift.