Module reactor

The onion service publisher reactor.

Generates and publishes hidden service descriptors in response to various events.

Reactor::run is the entry-point of the reactor. It starts the reactor, and runs until Reactor::run_once returns ShutdownStatus::Terminate or a fatal error occurs. ShutdownStatus::Terminate is returned if any of the channels the reactor is receiving events from is closed (i.e. when the senders are dropped).

Publisher status

The publisher has an internal PublishStatus, distinct from its State, which is used for onion service status reporting.

The main loop of the reactor reads the current PublishStatus from publish_status_rx, and responds by generating and publishing a new descriptor if needed.

See PublishStatus and Reactor::publish_status_rx for more details.

When do we publish?

We generate and publish a new descriptor if

• the introduction points have changed
• the onion service configuration has changed in a meaningful way (for example, if the restricted_discovery configuration or its Anonymity has changed. See OnionServiceConfigPublisherView).
• there is a new consensus
• it is time to republish the descriptor (after we upload a descriptor, we schedule it for republishing at a random time between 60 minutes and 120 minutes in the future)

Onion service status

With respect to OnionServiceStatus reporting, the following state transitions are possible:

                update_publish_status(UploadScheduled|AwaitingIpts|RateLimited)
               +---------------------------------------+
               |                                       |
               |                                       v
               |                               +---------------+
               |                               | Bootstrapping |
               |                               +---------------+
               |                                       |
               |                                       |           uploaded to at least
               |  not enough HsDir uploads succeeded   |        some HsDirs from each ring
               |         +-----------------------------+-----------------------+
               |         |                             |                       |
               |         |              all HsDir uploads succeeded            |
               |         |                             |                       |
               |         v                             v                       v
               |  +---------------------+         +---------+        +---------------------+
               |  | DegradedUnreachable |         | Running |        |  DegradedReachable  |
+----------+   |  +---------------------+         +---------+        +---------------------+
| Shutdown |-- |         |                           |                        |
+----------+   |         |                           |                        |
               |         |                           |                        |
               |         |                           |                        |
               |         +---------------------------+------------------------+
               |                                     |   invalid authorized_clients
               |                                     |      after handling config change
               |                                     |
               |                                     v
               |     run_once() returns an error +--------+
               +-------------------------------->| Broken |
                                                 +--------+

We can also transition from Broken, DegradedReachable, or DegradedUnreachable back to Bootstrapping (those transitions were omitted for brevity).

Macros

watch_path 🔒

Add path to the specified watcher.

Structs

HsDirUploadStatus 🔒

The outcome of uploading a descriptor to a particular HsDir.

Immutable 🔒

The immutable, shared state of the descriptor publisher reactor.

Inner 🔒

The mutable state of a Reactor.

PublisherBackoffSchedule 🔒

The backoff schedule for the task that publishes descriptors.

Reactor 🔒

A reactor for the HsDir Publisher

Real 🔒

The real version of the mockable state of the reactor.

TimePeriodContext 🔒

The part of the reactor state that changes with every time period.

TimePeriodUploadResult 🔒

The outcome of uploading a descriptor to the HSDirs from a particular time period.

Enums

PublishStatus 🔒

Whether the reactor should initiate an upload.

UploadError

An error that occurs while trying to upload a descriptor.

Constants

MAX_CONCURRENT_UPLOADS 🔒

The maximum number of concurrent upload tasks per time period.

OVERALL_UPLOAD_TIMEOUT 🔒

The maximum time allowed for uploading a descriptor to a single HSDir, across all attempts.

UPLOAD_RATE_LIM_THRESHOLD 🔒

The upload rate-limiting threshold.

Traits

Mockable 🔒

Mockable state for the descriptor publisher reactor.

MockableClientCirc 🔒

Mockable client circuit

Functions

maybe_expand_path 🔒

Try to expand a path, logging a warning on failure.

read_blind_id_keypair 🔒

Try to read the blinded identity key for a given TimePeriod.

upload_result_state 🔒

Determine the State of the publisher based on the upload results from the current time_periods.

watch_dirs 🔒

Add the specified directories to the watcher.

Type Aliases

UploadResult 🔒

The outcome of uploading a descriptor.