1
#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
2
#![doc = include_str!("../README.md")]
3
// @@ begin lint list maintained by maint/add_warning @@
4
#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)
5
#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)
6
#![warn(missing_docs)]
7
#![warn(noop_method_call)]
8
#![warn(unreachable_pub)]
9
#![warn(clippy::all)]
10
#![deny(clippy::await_holding_lock)]
11
#![deny(clippy::cargo_common_metadata)]
12
#![deny(clippy::cast_lossless)]
13
#![deny(clippy::checked_conversions)]
14
#![warn(clippy::cognitive_complexity)]
15
#![deny(clippy::debug_assert_with_mut_call)]
16
#![deny(clippy::exhaustive_enums)]
17
#![deny(clippy::exhaustive_structs)]
18
#![deny(clippy::expl_impl_clone_on_copy)]
19
#![deny(clippy::fallible_impl_from)]
20
#![deny(clippy::implicit_clone)]
21
#![deny(clippy::large_stack_arrays)]
22
#![warn(clippy::manual_ok_or)]
23
#![deny(clippy::missing_docs_in_private_items)]
24
#![warn(clippy::needless_borrow)]
25
#![warn(clippy::needless_pass_by_value)]
26
#![warn(clippy::option_option)]
27
#![deny(clippy::print_stderr)]
28
#![deny(clippy::print_stdout)]
29
#![warn(clippy::rc_buffer)]
30
#![deny(clippy::ref_option_ref)]
31
#![warn(clippy::semicolon_if_nothing_returned)]
32
#![warn(clippy::trait_duplication_in_bounds)]
33
#![deny(clippy::unchecked_duration_subtraction)]
34
#![deny(clippy::unnecessary_wraps)]
35
#![warn(clippy::unseparated_literal_suffix)]
36
#![deny(clippy::unwrap_used)]
37
#![deny(clippy::mod_module_files)]
38
#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
39
#![allow(clippy::uninlined_format_args)]
40
#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
41
#![allow(clippy::result_large_err)] // temporary workaround for arti#587
42
#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
43
#![allow(clippy::needless_lifetimes)] // See arti#1765
44
#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060
45
//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
46

            
47
use derive_more::Display;
48

            
49
mod internal;
50
pub use internal::*;
51

            
52
mod report;
53
pub use report::*;
54

            
55
mod retriable;
56
pub use retriable::*;
57

            
58
mod misc;
59
pub use misc::*;
60

            
61
#[cfg(feature = "tracing")]
62
pub mod tracing;
63

            
64
/// Classification of an error arising from Arti's Tor operations
65
///
66
/// This `ErrorKind` should suffice for programmatic handling by most applications embedding Arti:
67
/// get the kind via [`HasKind::kind`] and compare it to the expected value(s) with equality
68
/// or by matching.
69
///
70
/// When forwarding or reporting errors, use the whole error (e.g., `TorError`), not just the kind:
71
/// the error itself will contain more detail and context which is useful to humans.
72
//
73
// Splitting vs lumping guidelines:
74
//
75
// # Split on the place which caused the error
76
//
77
// Every ErrorKind should generally have an associated "location" in
78
// which it occurred.  If a problem can happen in two different
79
// "locations", it should have two different ErrorKinds.  (This goal
80
// may be frustrated sometimes by difficulty in determining where exactly
81
// a given error occurred.)
82
//
83
// The location of an ErrorKind should always be clear from its name.  If is not
84
// clear, add a location-related word to the name of the ErrorKind.
85
//
86
// For the purposes of this discussion, the following locations exist:
87
//   - Process:  Our code, or the application code using it.  These errors don't
88
//     usually need a special prefix.
89
//   - Host: A problem with our local computing  environment.  These errors
90
//     usually reflect trying to run under impossible circumstances (no file
91
//     system, no permissions, etc).
92
//   - Local: Another process on the same machine, or on the network between us
93
//     and the Tor network.  Errors in this location often indicate an outage,
94
//     misconfiguration, or a censorship event.
95
//   - Tor: Anywhere within the Tor network, or connections between Tor relays.
96
//     The words "Exit" and "Relay" also indicate this location.
97
//   - Remote: Anywhere _beyond_ the Tor exit. Can be a problem in the Tor
98
//     exit's connection to the real internet,  or with the remote host that the
99
//     exit is talking to.  (This kind of error can also indicate that the exit
100
//     is lying.)
101
//
102
// ## Lump any locations more fine-grained than that.
103
//
104
// We do not split locations more finely unless there's a good reason to do so.
105
// For example, we don't typically split errors within the "Tor" location based
106
// on whether they happened at a guard, a directory, or an exit.  (Errors with
107
// "Exit" or "Guard" in their names are okay, so long as that kind of error can
108
// _only_ occur at an Exit or Guard.)
109
//
110
// # Split based on reasonable response and semantics
111
//
112
// We also should split ErrorKinds based on what it's reasonable for the
113
// receiver to do with them.  Users may find more applications for our errors
114
// than we do, so we shouldn't assume that we can predict every reasonable use
115
// in advance.
116
//
117
// ErrorKinds should be more specific than just the locations in which they
118
// happen: for example, there shouldn't be a `TorNetworkError` or
119
// a `RemoteFailure`.
120
//
121
// # Avoid exposing implementation details
122
//
123
// ErrorKinds should not relate to particular code paths in the Arti codebase.
124

            
125
#[derive(Debug, Clone, Copy, PartialEq, Eq, Display)]
126
#[non_exhaustive]
127
pub enum ErrorKind {
128
    /// Error connecting to the Tor network
129
    ///
130
    /// Perhaps the local network is not working,
131
    /// or perhaps the chosen relay or bridge is not working properly.
132
    /// Not used for errors that occur within the Tor network, or accessing the public
133
    /// internet on the far side of Tor.
134
    #[display("error connecting to Tor")]
135
    TorAccessFailed,
136

            
137
    /// An attempt was made to use a Tor client for something without bootstrapping it first.
138
    #[display("attempted to use unbootstrapped client")]
139
    BootstrapRequired,
140

            
141
    /// Our network directory has expired before we were able to replace it.
142
    ///
143
    /// This kind of error can indicate one of several possible problems:
144
    /// * It can occur if the client used to be on the network, but has been
145
    ///   unable to make directory connections for a while.
146
    /// * It can occur if the client has been suspended or sleeping for a long
147
    ///   time, and has suddenly woken up without having a chance to replace its
148
    ///   network directory.
149
    /// * It can happen if the client has a sudden clock jump.
150
    ///
151
    /// Often, retrying after a minute or so will resolve this issue.
152
    ///
153
    // TODO this is pretty shonky.  "try again after a minute or so", seriously?
154
    //
155
    /// Future versions of Arti may resolve this situation automatically without caller
156
    /// intervention, possibly depending on preferences and API usage, in which case this kind of
157
    /// error will never occur.
158
    //
159
    // TODO: We should distinguish among the actual issues here, and report a
160
    // real bootstrapping problem when it exists.
161
    #[display("network directory is expired.")]
162
    DirectoryExpired,
163

            
164
    /// IO error accessing local persistent state
165
    ///
166
    /// For example, the disk might be full, or there may be a permissions problem.
167
    /// Usually the source will be [`std::io::Error`].
168
    ///
169
    /// Note that this kind of error only applies to problems in your `state_dir`:
170
    /// problems with your cache are another kind.
171
    #[display("could not read/write persistent state")]
172
    PersistentStateAccessFailed,
173

            
174
    /// We could not start up because a local resource is already being used by someone else
175
    ///
176
    /// Local resources include things like listening ports and state lockfiles.
177
    /// (We don't use this error for "out of disk space" and the like.)
178
    ///
179
    /// This can occur when another process
180
    /// (or another caller of Arti APIs)
181
    /// is already running a facility that overlaps with the one being requested.
182
    ///
183
    /// For example,
184
    /// running multiple processes each containing instances of the same hidden service,
185
    /// using the same state directories etc., is not supported.
186
    ///
187
    /// Another example:
188
    /// if Arti is configured to listen on a particular port,
189
    /// but another process on the system is already listening there,
190
    /// the resulting error has kind `LocalResourceAlreadyInUse`.
191
    // Actually, we only currently listen on ports in `arti` so we don't return
192
    // any Rust errors for this situation at all, at the time of writing.
193
    #[display("local resource (port, lockfile, etc.) already in use")]
194
    LocalResourceAlreadyInUse,
195

            
196
    /// We encountered a problem with filesystem permissions.
197
    ///
198
    /// This is likeliest to be caused by permissions on a file or directory
199
    /// being too permissive; the next likeliest cause is that we were unable to
200
    /// check the permissions on the file or directory, or on one of its
201
    /// ancestors.
202
    #[display("problem with filesystem permissions")]
203
    FsPermissions,
204

            
205
    /// Tor client's persistent state has been corrupted
206
    ///
207
    /// This could be because of a bug in the Tor code, or because something
208
    /// else has been messing with the data.
209
    ///
210
    /// This might also occur if the Tor code was upgraded and the new Tor is
211
    /// not compatible.
212
    ///
213
    /// Note that this kind of error only applies to problems in your
214
    /// `state_dir`: problems with your cache are another kind.
215
    #[display("corrupted data in persistent state")]
216
    PersistentStateCorrupted,
217

            
218
    /// Tor client's cache has been corrupted.
219
    ///
220
    /// This could be because of a bug in the Tor code, or because something else has been messing
221
    /// with the data.
222
    ///
223
    /// This might also occur if the Tor code was upgraded and the new Tor is not compatible.
224
    ///
225
    /// Note that this kind of error only applies to problems in your `cache_dir`:
226
    /// problems with your persistent state are another kind.
227
    #[display("corrupted data in cache")]
228
    CacheCorrupted,
229

            
230
    /// We had a problem reading or writing to our data cache.
231
    ///
232
    /// This may be a disk error, a file permission error, or similar.
233
    ///
234
    /// Note that this kind of error only applies to problems in your `cache_dir`:
235
    /// problems with your persistent state are another kind.
236
    #[display("cache access problem")]
237
    CacheAccessFailed,
238

            
239
    /// The keystore has been corrupted
240
    ///
241
    /// This could be because of a bug in the Tor code, or because something else has been messing
242
    /// with the data.
243
    ///
244
    /// Note that this kind of error only applies to problems in your `keystore_dir`:
245
    /// problems with your cache or persistent state are another kind.
246
    #[display("corrupted data in keystore")]
247
    KeystoreCorrupted,
248

            
249
    /// IO error accessing keystore
250
    ///
251
    /// For example, the disk might be full, or there may be a permissions problem.
252
    /// The source is typically an [`std::io::Error`].
253
    ///
254
    /// Note that this kind of error only applies to problems in your `keystore_dir`:
255
    /// problems with your cache or persistent state are another kind.
256
    #[display("could not access keystore")]
257
    KeystoreAccessFailed,
258

            
259
    /// Tor client's Rust async reactor is shutting down.
260
    ///
261
    /// This likely indicates that the reactor has encountered a fatal error, or
262
    /// has been told to do a clean shutdown, and it isn't possible to spawn new
263
    /// tasks.
264
    #[display("reactor is shutting down")]
265
    ReactorShuttingDown,
266

            
267
    /// Tor client is shutting down.
268
    ///
269
    /// This likely indicates that the last handle to the `TorClient` has been
270
    /// dropped, and is preventing other operations from completing.
271
    #[display("Tor client is shutting down.")]
272
    ArtiShuttingDown,
273

            
274
    /// This Tor client software is missing some feature that is recommended
275
    /// (or required) for operation on the network.
276
    ///
277
    /// This occurs when the directory authorities tell us that we ought to have
278
    /// a particular protocol feature that we do not support.
279
    /// The correct solution is likely to upgrade to a more recent version of Arti.
280
    #[display("Software version is deprecated")]
281
    SoftwareDeprecated,
282

            
283
    /// An operation failed because we waited too long for an exit to do
284
    /// something.
285
    ///
286
    /// This error can happen if the host you're trying to connect to isn't
287
    /// responding to traffic.
288
    /// It can also happen if an exit, or hidden service, is overloaded, and
289
    /// unable to answer your replies in a timely manner.
290
    ///
291
    /// And it might simply mean that the Tor network itself
292
    /// (including possibly relays, or hidden service introduction or rendezvous points)
293
    /// is not working properly
294
    ///
295
    /// In either case, trying later, or on a different circuit, might help.
296
    //
297
    // TODO: Say that this is distinct from the case where the exit _tells you_
298
    // that there is a timeout.
299
    #[display("operation timed out at exit")]
300
    RemoteNetworkTimeout,
301

            
302
    /// One or more configuration values were invalid or incompatible.
303
    ///
304
    /// This kind of error can happen if the user provides an invalid or badly
305
    /// formatted configuration file, if some of the options in that file are
306
    /// out of their ranges or unparsable, or if the options are not all
307
    /// compatible with one another. It can also happen if configuration options
308
    /// provided via APIs are out of range.
309
    ///
310
    /// If this occurs because of user configuration, it's probably best to tell
311
    /// the user about the error. If it occurs because of API usage, it's
312
    /// probably best to fix the code that causes the error.
313
    #[display("invalid configuration")]
314
    InvalidConfig,
315

            
316
    /// Tried to change the configuration of a running Arti service in a way
317
    /// that isn't supported.
318
    ///
319
    /// This kind of error can happen when you call a `reconfigure()` method on
320
    /// a service (or part of a service) and the new configuration is not
321
    /// compatible with the previous configuration.
322
    ///
323
    /// The only available remedy is to tear down the service and make a fresh
324
    /// one (for example, by making a new `TorClient`).
325
    #[display("invalid configuration transition")]
326
    InvalidConfigTransition,
327

            
328
    /// Tried to look up a directory depending on the user's home directory, but
329
    /// the user's home directory isn't set or can't be found.
330
    ///
331
    /// This kind of error can also occur if we're running in an environment
332
    /// where users don't have home directories.
333
    ///
334
    /// To resolve this kind of error, either move to an OS with home
335
    /// directories, or make sure that all paths in the configuration are set
336
    /// explicitly, and do not depend on any path variables.
337
    #[display("could not find a home directory")]
338
    NoHomeDirectory,
339

            
340
    /// A requested operation was not implemented by Arti.
341
    ///
342
    /// This kind of error can happen when requesting a piece of protocol
343
    /// functionality that has not (yet) been implemented in the Arti project.
344
    ///
345
    /// If it happens as a result of a user activity, it's fine to ignore, log,
346
    /// or report the error. If it happens as a result of direct API usage, it
347
    /// may indicate that you're using something that isn't implemented yet.
348
    ///
349
    /// This kind can relate both to operations which we plan to implement, and
350
    /// to operations which we do not.  It does not relate to facilities which
351
    /// are disabled (e.g. at build time) or harmful.
352
    ///
353
    /// It can refer to facilities which were once implemented in Tor or Arti
354
    /// but for which support has been removed.
355
    #[display("operation not implemented")]
356
    NotImplemented,
357

            
358
    /// A feature was requested which has been disabled in this build of Arti.
359
    ///
360
    /// This kind of error happens when the running Arti was built without the
361
    /// appropriate feature (usually, cargo feature) enabled.
362
    ///
363
    /// This might indicate that the overall running system has been
364
    /// mis-configured at build-time.  Alternatively, it can occur if the
365
    /// running system is deliberately stripped down, in which case it might be
366
    /// reasonable to simply report this error to a user.
367
    #[display("operation not supported because Arti feature disabled")]
368
    FeatureDisabled,
369

            
370
    /// Someone or something local violated a network protocol.
371
    ///
372
    /// This kind of error can happen when a local program accessing us over some
373
    /// other protocol violates the protocol's requirements.
374
    ///
375
    /// This usually indicates a programming error: either in that program's
376
    /// implementation of the protocol, or in ours.  In any case, the problem
377
    /// is with software on the local system (or otherwise sharing a Tor client).
378
    ///
379
    /// It might also occur if the local system has an incompatible combination
380
    /// of tools that we can't talk with.
381
    ///
382
    /// This error kind does *not* include situations that are better explained
383
    /// by a local program simply crashing or terminating unexpectedly.
384
    #[display("local protocol violation (local bug or incompatibility)")]
385
    LocalProtocolViolation,
386

            
387
    /// Someone or something on the Tor network violated the Tor protocols.
388
    ///
389
    /// This kind of error can happen when a remote Tor instance behaves in a
390
    /// way we don't expect.
391
    ///
392
    /// It usually indicates a programming error: either in their implementation
393
    /// of the protocol, or in ours.  It can also indicate an attempted attack,
394
    /// though that can be hard to diagnose.
395
    #[display("Tor network protocol violation (bug, incompatibility, or attack)")]
396
    TorProtocolViolation,
397

            
398
    /// Something went wrong with a network connection or the local network.
399
    ///
400
    /// This kind of error is usually safe to retry, and shouldn't typically be
401
    /// seen.  By the time it reaches the caller, a more specific error type
402
    /// should typically be available.
403
    #[display("problem with network or connection")]
404
    LocalNetworkError,
405

            
406
    /// More of a local resource was needed, than is available (or than we are allowed)
407
    ///
408
    /// For example, we tried to use more memory than permitted by our memory quota.
409
    #[display("local resource exhausted")]
410
    LocalResourceExhausted,
411

            
412
    /// A problem occurred when launching or communicating with an external
413
    /// process running on this computer.
414
    #[display("an externally launched plug-in tool failed")]
415
    ExternalToolFailed,
416

            
417
    /// A relay had an identity other than the one we expected.
418
    ///
419
    /// This could indicate a MITM attack, but more likely indicates that the
420
    /// relay has changed its identity but the new identity hasn't propagated
421
    /// through the directory system yet.
422
    #[display("identity mismatch")]
423
    RelayIdMismatch,
424

            
425
    /// An attempt to do something remotely through the Tor network failed
426
    /// because the circuit it was using shut down before the operation could
427
    /// finish.
428
    #[display("circuit collapsed")]
429
    CircuitCollapse,
430

            
431
    /// An operation timed out on the tor network.
432
    ///
433
    /// This may indicate a network problem, either with the local network
434
    /// environment's ability to contact the Tor network, or with the Tor
435
    /// network itself.
436
    #[display("tor operation timed out")]
437
    TorNetworkTimeout,
438

            
439
    /// We tried but failed to download a piece of directory information.
440
    ///
441
    /// This is a lower-level kind of error; in general it should be retried
442
    /// before the user can see it.   In the future it is likely to be split
443
    /// into several other kinds.
444
    // TODO ^
445
    #[display("directory fetch attempt failed")]
446
    TorDirectoryError,
447

            
448
    /// An operation finished because a remote stream was closed successfully.
449
    ///
450
    /// This can indicate that the target server closed the TCP connection,
451
    /// or that the exit told us that it closed the TCP connection.
452
    /// Callers should generally treat this like a closed TCP connection.
453
    #[display("remote stream closed")]
454
    RemoteStreamClosed,
455

            
456
    /// An operation finished because the remote stream was closed abruptly.
457
    ///
458
    /// This kind of error is analogous to an ECONNRESET error; it indicates
459
    /// that the exit reported that the stream was terminated without a clean
460
    /// TCP shutdown.
461
    ///
462
    /// For most purposes, it's fine to treat this kind of error the same as
463
    /// regular unexpected close.
464
    #[display("remote stream reset")]
465
    RemoteStreamReset,
466

            
467
    /// An operation finished because a remote stream was closed unsuccessfully.
468
    ///
469
    /// This indicates that the exit reported some error message for the stream.
470
    ///
471
    /// We only provide this error kind when no more specific kind is available.
472
    #[display("remote stream error")]
473
    RemoteStreamError,
474

            
475
    /// A stream failed, and the exit reports that the remote host refused
476
    /// the connection.
477
    ///
478
    /// This is analogous to an ECONNREFUSED error.
479
    #[display("remote host refused connection")]
480
    RemoteConnectionRefused,
481

            
482
    /// A stream was rejected by the exit relay because of that relay's exit
483
    /// policy.
484
    ///
485
    /// (In Tor, exits have a set of policies declaring which addresses and
486
    /// ports they're willing to connect to.  Clients download only _summaries_
487
    /// of these policies, so it's possible to be surprised by an exit's refusal
488
    /// to connect somewhere.)
489
    #[display("rejected by exit policy")]
490
    ExitPolicyRejected,
491

            
492
    /// An operation failed, and the exit reported that it waited too long for
493
    /// the operation to finish.
494
    ///
495
    /// This kind of error is distinct from `RemoteNetworkTimeout`, which means
496
    /// that _our own_ timeout threshold was violated.
497
    #[display("timeout at exit relay")]
498
    ExitTimeout,
499

            
500
    /// An operation failed, and the exit reported a network failure of some
501
    /// kind.
502
    ///
503
    /// This kind of error can occur for a number of reasons.  If it happens
504
    /// when trying to open a stream, it usually indicates a problem connecting,
505
    /// such as an ENOROUTE error.
506
    #[display("network failure at exit")]
507
    RemoteNetworkFailed,
508

            
509
    /// An operation finished because an exit failed to look up a hostname.
510
    ///
511
    /// Unfortunately, the Tor protocol does not distinguish failure of DNS
512
    /// services ("we couldn't find out if this host exists and what its name is")
513
    /// from confirmed denials ("this is not a hostname").  So this kind
514
    /// conflates both those sorts of error.
515
    ///
516
    /// Trying at another exit might succeed, or the address might truly be
517
    /// unresolvable.
518
    #[display("remote hostname not found")]
519
    RemoteHostNotFound,
520

            
521
    /// The target hidden service (`.onion` service) was not found in the directory
522
    ///
523
    /// We successfully connected to at least one directory server,
524
    /// but it didn't have a record of the hidden service.
525
    ///
526
    /// This probably means that the hidden service is not running, or does not exist.
527
    /// (It might mean that the directory servers are faulty,
528
    /// and that the hidden service was unable to publish its descriptor.)
529
    #[display("Onion Service not found")]
530
    OnionServiceNotFound,
531

            
532
    /// The target hidden service (`.onion` service) seems to be down
533
    ///
534
    /// We successfully obtained a hidden service descriptor for the service,
535
    /// so we know it is supposed to exist,
536
    /// but we weren't able to communicate with it via any of its
537
    /// introduction points.
538
    ///
539
    /// This probably means that the hidden service is not running.
540
    /// (It might mean that the introduction point relays are faulty.)
541
    #[display("Onion Service not running")]
542
    OnionServiceNotRunning,
543

            
544
    /// Protocol trouble involving the target hidden service (`.onion` service)
545
    ///
546
    /// Something unexpected happened when trying to connect to the selected hidden service.
547
    /// It seems to have been due to the hidden service violating the Tor protocols somehow.
548
    #[display("Onion Service protocol failed (apparently due to service behaviour)")]
549
    OnionServiceProtocolViolation,
550

            
551
    /// The target hidden service (`.onion` service) is running but we couldn't connect to it,
552
    /// and we aren't sure whose fault that is
553
    ///
554
    /// This might be due to malfunction on the part of the service,
555
    /// or a relay being used as an introduction point or relay,
556
    /// or failure of the underlying Tor network.
557
    #[display("Onion Service not reachable (due to service, or Tor network, behaviour)")]
558
    OnionServiceConnectionFailed,
559

            
560
    /// We tried to connect to an onion service without authentication,
561
    /// but it apparently requires authentication.
562
    #[display("Onion service required authentication, but none was provided.")]
563
    OnionServiceMissingClientAuth,
564

            
565
    /// We tried to connect to an onion service that requires authentication, and
566
    /// ours is wrong.
567
    ///
568
    /// This likely means that we need to use a different key for talking to
569
    /// this onion service, or that it has revoked our permissions to reach it.
570
    #[display("Onion service required authentication, but provided authentication was incorrect.")]
571
    OnionServiceWrongClientAuth,
572

            
573
    /// We tried to parse a `.onion` address, and found that it was not valid.
574
    ///
575
    /// This likely means that it was corrupted somewhere along its way from its
576
    /// origin to our API surface.  It may be the wrong length, have invalid
577
    /// characters, have an invalid version number, or have an invalid checksum.
578
    #[display(".onion address was invalid.")]
579
    OnionServiceAddressInvalid,
580

            
581
    /// An resolve operation finished with an error.
582
    ///
583
    /// Contrary to [`RemoteHostNotFound`](ErrorKind::RemoteHostNotFound),
584
    /// this can't mean "this is not a hostname".
585
    /// This error should be retried.
586
    #[display("remote hostname lookup failure")]
587
    RemoteHostResolutionFailed,
588

            
589
    /// Trouble involving a protocol we're using with a peer on the far side of the Tor network
590
    ///
591
    /// We were using a higher-layer protocol over a Tor connection,
592
    /// and something went wrong.
593
    /// This might be an error reported by the remote host within that higher protocol,
594
    /// or a problem detected locally but relating to that higher protocol.
595
    ///
596
    /// The nature of the problem can vary:
597
    /// examples could include:
598
    /// failure to agree suitable parameters (incompatibility);
599
    /// authentication problems (eg, TLS certificate trouble);
600
    /// protocol violation by the peer;
601
    /// peer refusing to provide service;
602
    /// etc.
603
    #[display("remote protocol violation")]
604
    RemoteProtocolViolation,
605

            
606
    /// An operation failed, and the relay in question reported that it's too
607
    /// busy to answer our request.
608
    #[display("relay too busy")]
609
    RelayTooBusy,
610

            
611
    /// We were asked to make an anonymous connection to a malformed address.
612
    ///
613
    /// This is probably because of a bad input from a user.
614
    #[display("target address was invalid")]
615
    InvalidStreamTarget,
616

            
617
    /// We were asked to make an anonymous connection to a _locally_ disabled
618
    /// address.
619
    ///
620
    /// For example, this kind of error can happen when try to connect to (e.g.)
621
    /// `127.0.0.1` using a client that isn't configured with allow_local_addrs.
622
    ///
623
    /// Usually this means that you intended to reject the request as
624
    /// nonsensical; but if you didn't, it probably means you should change your
625
    /// configuration to allow what you want.
626
    #[display("target address disabled locally")]
627
    ForbiddenStreamTarget,
628

            
629
    /// An operation failed in a transient way.
630
    ///
631
    /// This kind of error indicates that some kind of operation failed in a way
632
    /// where retrying it again could likely have made it work.
633
    ///
634
    /// You should not generally see this kind of error returned directly to you
635
    /// for high-level functions.  It should only be returned from lower-level
636
    /// crates that do not automatically retry these failures.
637
    // Errors with this kind should generally not return a `HasRetryTime::retry_time()` of `Never`.
638
    #[display("un-retried transient failure")]
639
    TransientFailure,
640

            
641
    /// Bug, for example calling a function with an invalid argument.
642
    ///
643
    /// This kind of error is usually a programming mistake on the caller's part.
644
    /// This is usually a bug in code calling Arti, but it might be a bug in Arti itself.
645
    //
646
    // Usually, use `bad_api_usage!` and `into_bad_api_usage!` and thereby `InternalError`,
647
    // rather than inventing a new type with this kind.
648
    //
649
    // Errors with this kind should generally include a stack trace.  They are
650
    // very like InternalError, in that they represent a bug in the program.
651
    // The difference is that an InternalError, with kind `Internal`, represents
652
    // a bug in arti, whereas errors with kind BadArgument represent bugs which
653
    // could be (often, are likely to be) outside arti.
654
    #[display("bad API usage (bug)")]
655
    BadApiUsage,
656

            
657
    /// We asked a relay to create or extend a circuit, and it declined.
658
    ///
659
    /// Either it gave an error message indicating that it refused to perform
660
    /// the request, or the protocol gives it no room to explain what happened.
661
    ///
662
    /// This error is returned by higher-level functions only if it is the most informative
663
    /// error after appropriate retries etc.
664
    #[display("remote host refused our request")]
665
    CircuitRefused,
666

            
667
    /// We were unable to construct a path through the Tor network.
668
    ///
669
    /// Usually this indicates that there are too many user-supplied
670
    /// restrictions for us to comply with.
671
    ///
672
    /// On test networks, it likely indicates that there aren't enough relays,
673
    /// or that there aren't enough relays in distinct families.
674
    //
675
    // TODO: in the future, errors of this type should distinguish between
676
    // cases where this happens because of a user restriction and cases where it
677
    // happens because of a severely broken directory.
678
    //
679
    // The latter should be classified as TorDirectoryBroken.
680
    #[display("could not construct a path")]
681
    NoPath,
682

            
683
    /// We were unable to find an exit relay with a certain set of desired
684
    /// properties.
685
    ///
686
    /// Usually this indicates that there were too many user-supplied
687
    /// restrictions on the exit for us to comply with, or that there was no
688
    /// exit on the network supporting all of the ports that the user asked for.
689
    //
690
    // TODO: same as for NoPath.
691
    #[display("no exit available for path")]
692
    NoExit,
693

            
694
    /// The Tor consensus directory is broken or unsuitable
695
    ///
696
    /// This could occur when running very old software
697
    /// against the current Tor network,
698
    /// so that the newer network is incompatible.
699
    ///
700
    /// It might also mean a catastrophic failure of the Tor network,
701
    /// or that a deficient test network is in use.
702
    ///
703
    /// Currently some instances of this kind of problem
704
    /// are reported as `NoPath` or `NoExit`.
705
    #[display("Tor network consensus directory is not usable")]
706
    TorDirectoryUnusable,
707

            
708
    /// An operation failed because of _possible_ clock skew.
709
    ///
710
    /// The broken clock may be ours, or it may belong to another party on the
711
    /// network. It's also possible that somebody else is lying about the time,
712
    /// caching documents for far too long, or something like that.
713
    #[display("possible clock skew detected")]
714
    ClockSkew,
715

            
716
    /// Internal error (bug) in Arti.
717
    ///
718
    /// A supposedly impossible problem has arisen.  This indicates a bug in
719
    /// Arti; if the Arti version is relatively recent, please report the bug on
720
    /// our [bug tracker](https://gitlab.torproject.org/tpo/core/arti/-/issues).
721
    #[display("internal error (bug)")]
722
    Internal,
723

            
724
    /// Unclassified error
725
    ///
726
    /// Some other error occurred, which does not fit into any of the other kinds.
727
    ///
728
    /// This kind is provided for use by external code
729
    /// hooking into or replacing parts of Arti.
730
    /// It is never returned by the code in Arti (`arti-*` and `tor-*` crates).
731
    #[display("unclassified error")]
732
    Other,
733
}
734

            
735
/// Errors that can be categorized as belonging to an [`ErrorKind`]
736
///
737
/// The most important implementation of this trait is
738
/// `arti_client::TorError`; however, other internal errors throughout Arti
739
/// also implement it.
740
pub trait HasKind {
741
    /// Return the kind of this error.
742
    fn kind(&self) -> ErrorKind;
743
}
744

            
745
#[cfg(feature = "futures")]
746
impl HasKind for futures::task::SpawnError {
747
70
    fn kind(&self) -> ErrorKind {
748
        use ErrorKind as EK;
749
70
        if self.is_shutdown() {
750
70
            EK::ReactorShuttingDown
751
        } else {
752
            EK::Internal
753
        }
754
70
    }
755
}
756

            
757
impl HasKind for void::Void {
758
    fn kind(&self) -> ErrorKind {
759
        void::unreachable(*self)
760
    }
761
}
762

            
763
impl HasKind for std::convert::Infallible {
764
    fn kind(&self) -> ErrorKind {
765
        unreachable!()
766
    }
767
}
768

            
769
/// Sealed
770
mod sealed {
771
    /// Sealed
772
    pub trait Sealed {}
773
}