tor_error/lib.rs
1#![cfg_attr(docsrs, feature(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#![allow(clippy::cognitive_complexity)] // See arti#2556
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#![warn(clippy::or_fun_call)]
28#![deny(clippy::print_stderr)]
29#![deny(clippy::print_stdout)]
30#![warn(clippy::rc_buffer)]
31#![deny(clippy::ref_option_ref)]
32#![warn(clippy::semicolon_if_nothing_returned)]
33#![warn(clippy::trait_duplication_in_bounds)]
34#![deny(clippy::unchecked_time_subtraction)]
35#![deny(clippy::unnecessary_wraps)]
36#![warn(clippy::unseparated_literal_suffix)]
37#![deny(clippy::unwrap_used)]
38#![deny(clippy::mod_module_files)]
39#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
40#![allow(clippy::uninlined_format_args)]
41#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
42#![allow(clippy::result_large_err)] // temporary workaround for arti#587
43#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
44#![allow(clippy::needless_lifetimes)] // See arti#1765
45#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060
46#![allow(clippy::collapsible_if)] // See arti#2342
47#![deny(clippy::unused_async)]
48#![deny(clippy::string_slice)] // See arti#2571
49#![allow(recursion_depth_exceeding_limit)] // arti#2715, rust/issues/159228
50//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
51
52use derive_more::Display;
53
54mod internal;
55pub use internal::*;
56
57mod report;
58pub use report::*;
59
60mod retriable;
61pub use retriable::*;
62
63mod misc;
64pub use misc::*;
65
66#[cfg(feature = "tracing")]
67pub mod tracing;
68
69#[cfg(feature = "http")]
70mod http;
71
72pub use void;
73
74/// Classification of an error arising from Arti's Tor operations
75///
76/// This `ErrorKind` should suffice for programmatic handling by most applications embedding Arti:
77/// get the kind via [`HasKind::kind`] and compare it to the expected value(s) with equality
78/// or by matching.
79///
80/// When forwarding or reporting errors, use the whole error (e.g., `TorError`), not just the kind:
81/// the error itself will contain more detail and context which is useful to humans.
82//
83// Splitting vs lumping guidelines:
84//
85// # Split on the place which caused the error
86//
87// Every ErrorKind should generally have an associated "location" in
88// which it occurred. If a problem can happen in two different
89// "locations", it should have two different ErrorKinds. (This goal
90// may be frustrated sometimes by difficulty in determining where exactly
91// a given error occurred.)
92//
93// The location of an ErrorKind should always be clear from its name. If is not
94// clear, add a location-related word to the name of the ErrorKind.
95//
96// For the purposes of this discussion, the following locations exist:
97// - Process: Our code, or the application code using it. These errors don't
98// usually need a special prefix.
99// - Host: A problem with our local computing environment. These errors
100// usually reflect trying to run under impossible circumstances (no file
101// system, no permissions, etc).
102// - Local: Another process on the same machine, or on the network between us
103// and the Tor network. Errors in this location often indicate an outage,
104// misconfiguration, or a censorship event.
105// - Tor: Anywhere within the Tor network, or connections between Tor relays.
106// The words "Exit" and "Relay" also indicate this location.
107// - Remote: Anywhere _beyond_ the Tor exit. Can be a problem in the Tor
108// exit's connection to the real internet, or with the remote host that the
109// exit is talking to. (This kind of error can also indicate that the exit
110// is lying.)
111//
112// ## Lump any locations more fine-grained than that.
113//
114// We do not split locations more finely unless there's a good reason to do so.
115// For example, we don't typically split errors within the "Tor" location based
116// on whether they happened at a guard, a directory, or an exit. (Errors with
117// "Exit" or "Guard" in their names are okay, so long as that kind of error can
118// _only_ occur at an Exit or Guard.)
119//
120// # Split based on reasonable response and semantics
121//
122// We also should split ErrorKinds based on what it's reasonable for the
123// receiver to do with them. Users may find more applications for our errors
124// than we do, so we shouldn't assume that we can predict every reasonable use
125// in advance.
126//
127// ErrorKinds should be more specific than just the locations in which they
128// happen: for example, there shouldn't be a `TorNetworkError` or
129// a `RemoteFailure`.
130//
131// # Avoid exposing implementation details
132//
133// ErrorKinds should not relate to particular code paths in the Arti codebase.
134
135#[derive(Debug, Clone, Copy, PartialEq, Eq, Display, Hash)]
136#[non_exhaustive]
137pub enum ErrorKind {
138 /// Error connecting to the Tor network
139 ///
140 /// Perhaps the local network is not working,
141 /// or perhaps the chosen relay or bridge is not working properly.
142 /// Not used for errors that occur within the Tor network, or accessing the public
143 /// internet on the far side of Tor.
144 #[display("error connecting to Tor")]
145 TorAccessFailed,
146
147 /// An attempt was made to use a Tor client for something without bootstrapping it first.
148 #[display("attempted to use unbootstrapped client")]
149 BootstrapRequired,
150
151 /// Our network directory has expired before we were able to replace it.
152 ///
153 /// This kind of error can indicate one of several possible problems:
154 /// * It can occur if the client used to be on the network, but has been
155 /// unable to make directory connections for a while.
156 /// * It can occur if the client has been suspended or sleeping for a long
157 /// time, and has suddenly woken up without having a chance to replace its
158 /// network directory.
159 /// * It can happen if the client has a sudden clock jump.
160 ///
161 /// Often, retrying after a minute or so will resolve this issue.
162 ///
163 // TODO this is pretty shonky. "try again after a minute or so", seriously?
164 //
165 /// Future versions of Arti may resolve this situation automatically without caller
166 /// intervention, possibly depending on preferences and API usage, in which case this kind of
167 /// error will never occur.
168 //
169 // TODO: We should distinguish among the actual issues here, and report a
170 // real bootstrapping problem when it exists.
171 #[display("network directory is expired.")]
172 DirectoryExpired,
173
174 /// IO error accessing local persistent state
175 ///
176 /// For example, the disk might be full, or there may be a permissions problem.
177 /// Usually the source will be [`std::io::Error`].
178 ///
179 /// Note that this kind of error only applies to problems in your `state_dir`:
180 /// problems with your cache are another kind.
181 #[display("could not read/write persistent state")]
182 PersistentStateAccessFailed,
183
184 /// We could not start up because a local resource is already being used by someone else
185 ///
186 /// Local resources include things like listening ports and state lockfiles.
187 /// (We don't use this error for "out of disk space" and the like.)
188 ///
189 /// This can occur when another process
190 /// (or another caller of Arti APIs)
191 /// is already running a facility that overlaps with the one being requested.
192 ///
193 /// For example,
194 /// running multiple processes each containing instances of the same hidden service,
195 /// using the same state directories etc., is not supported.
196 ///
197 /// Another example:
198 /// if Arti is configured to listen on a particular port,
199 /// but another process on the system is already listening there,
200 /// the resulting error has kind `LocalResourceAlreadyInUse`.
201 // Actually, we only currently listen on ports in `arti` so we don't return
202 // any Rust errors for this situation at all, at the time of writing.
203 #[display("local resource (port, lockfile, etc.) already in use")]
204 LocalResourceAlreadyInUse,
205
206 /// We encountered a problem with filesystem permissions.
207 ///
208 /// This is likeliest to be caused by permissions on a file or directory
209 /// being too permissive; the next likeliest cause is that we were unable to
210 /// check the permissions on the file or directory, or on one of its
211 /// ancestors.
212 #[display("problem with filesystem permissions")]
213 FsPermissions,
214
215 /// Tor client's persistent state has been corrupted
216 ///
217 /// This could be because of a bug in the Tor code, or because something
218 /// else has been messing with the data.
219 ///
220 /// This might also occur if the Tor code was upgraded and the new Tor is
221 /// not compatible.
222 ///
223 /// Note that this kind of error only applies to problems in your
224 /// `state_dir`: problems with your cache are another kind.
225 #[display("corrupted data in persistent state")]
226 PersistentStateCorrupted,
227
228 /// Tor client's cache has been corrupted.
229 ///
230 /// This could be because of a bug in the Tor code, or because something else has been messing
231 /// with the data.
232 ///
233 /// This might also occur if the Tor code was upgraded and the new Tor is not compatible.
234 ///
235 /// Note that this kind of error only applies to problems in your `cache_dir`:
236 /// problems with your persistent state are another kind.
237 #[display("corrupted data in cache")]
238 CacheCorrupted,
239
240 /// We had a problem reading or writing to our data cache.
241 ///
242 /// This may be a disk error, a file permission error, or similar.
243 ///
244 /// Note that this kind of error only applies to problems in your `cache_dir`:
245 /// problems with your persistent state are another kind.
246 #[display("cache access problem")]
247 CacheAccessFailed,
248
249 /// The keystore has been corrupted
250 ///
251 /// This could be because of a bug in the Tor code, or because something else has been messing
252 /// with the data.
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("corrupted data in keystore")]
257 KeystoreCorrupted,
258
259 /// IO error accessing keystore
260 ///
261 /// For example, the disk might be full, or there may be a permissions problem.
262 /// The source is typically an [`std::io::Error`].
263 ///
264 /// Note that this kind of error only applies to problems in your `keystore_dir`:
265 /// problems with your cache or persistent state are another kind.
266 #[display("could not access keystore")]
267 KeystoreAccessFailed,
268
269 /// Tor client's Rust async reactor is shutting down.
270 ///
271 /// This likely indicates that the reactor has encountered a fatal error, or
272 /// has been told to do a clean shutdown, and it isn't possible to spawn new
273 /// tasks.
274 #[display("reactor is shutting down")]
275 ReactorShuttingDown,
276
277 /// Tor client is shutting down.
278 ///
279 /// This likely indicates that the last handle to the `TorClient` has been
280 /// dropped, and is preventing other operations from completing.
281 #[display("Tor client is shutting down.")]
282 ArtiShuttingDown,
283
284 /// This Tor client software is missing some feature that is recommended
285 /// (or required) for operation on the network.
286 ///
287 /// This occurs when the directory authorities tell us that we ought to have
288 /// a particular protocol feature that we do not support.
289 /// The correct solution is likely to upgrade to a more recent version of Arti.
290 #[display("Software version is deprecated")]
291 SoftwareDeprecated,
292
293 /// An operation failed because we waited too long for an exit to do
294 /// something.
295 ///
296 /// This error can happen if the host you're trying to connect to isn't
297 /// responding to traffic.
298 /// It can also happen if an exit, or hidden service, is overloaded, and
299 /// unable to answer your replies in a timely manner.
300 ///
301 /// And it might simply mean that the Tor network itself
302 /// (including possibly relays, or hidden service introduction or rendezvous points)
303 /// is not working properly
304 ///
305 /// In either case, trying later, or on a different circuit, might help.
306 //
307 // TODO: Say that this is distinct from the case where the exit _tells you_
308 // that there is a timeout.
309 #[display("operation timed out at exit")]
310 RemoteNetworkTimeout,
311
312 /// One or more configuration values were invalid or incompatible.
313 ///
314 /// This kind of error can happen if the user provides an invalid or badly
315 /// formatted configuration file, if some of the options in that file are
316 /// out of their ranges or unparsable, or if the options are not all
317 /// compatible with one another. It can also happen if configuration options
318 /// provided via APIs are out of range.
319 ///
320 /// If this occurs because of user configuration, it's probably best to tell
321 /// the user about the error. If it occurs because of API usage, it's
322 /// probably best to fix the code that causes the error.
323 #[display("invalid configuration")]
324 InvalidConfig,
325
326 /// Tried to change the configuration of a running Arti service in a way
327 /// that isn't supported.
328 ///
329 /// This kind of error can happen when you call a `reconfigure()` method on
330 /// a service (or part of a service) and the new configuration is not
331 /// compatible with the previous configuration.
332 ///
333 /// The only available remedy is to tear down the service and make a fresh
334 /// one (for example, by making a new `TorClient`).
335 #[display("invalid configuration transition")]
336 InvalidConfigTransition,
337
338 /// Tried to look up a directory depending on the user's home directory, but
339 /// the user's home directory isn't set or can't be found.
340 ///
341 /// This kind of error can also occur if we're running in an environment
342 /// where users don't have home directories.
343 ///
344 /// To resolve this kind of error, either move to an OS with home
345 /// directories, or make sure that all paths in the configuration are set
346 /// explicitly, and do not depend on any path variables.
347 #[display("could not find a home directory")]
348 NoHomeDirectory,
349
350 /// A requested operation was not implemented by Arti.
351 ///
352 /// This kind of error can happen when requesting a piece of protocol
353 /// functionality that has not (yet) been implemented in the Arti project.
354 ///
355 /// If it happens as a result of a user activity, it's fine to ignore, log,
356 /// or report the error. If it happens as a result of direct API usage, it
357 /// may indicate that you're using something that isn't implemented yet.
358 ///
359 /// This kind can relate both to operations which we plan to implement, and
360 /// to operations which we do not. It does not relate to facilities which
361 /// are disabled (e.g. at build time) or harmful.
362 ///
363 /// It can refer to facilities which were once implemented in Tor or Arti
364 /// but for which support has been removed.
365 #[display("operation not implemented")]
366 NotImplemented,
367
368 /// A feature was requested which has been disabled in this build of Arti.
369 ///
370 /// This kind of error happens when the running Arti was built without the
371 /// appropriate feature (usually, cargo feature) enabled.
372 ///
373 /// This might indicate that the overall running system has been
374 /// mis-configured at build-time. Alternatively, it can occur if the
375 /// running system is deliberately stripped down, in which case it might be
376 /// reasonable to simply report this error to a user.
377 #[display("operation not supported because Arti feature disabled")]
378 FeatureDisabled,
379
380 /// Someone or something local violated a network protocol.
381 ///
382 /// This kind of error can happen when a local program accessing us over some
383 /// other protocol violates the protocol's requirements.
384 ///
385 /// This usually indicates a programming error: either in that program's
386 /// implementation of the protocol, or in ours. In any case, the problem
387 /// is with software on the local system (or otherwise sharing a Tor client).
388 ///
389 /// It might also occur if the local system has an incompatible combination
390 /// of tools that we can't talk with.
391 ///
392 /// This error kind does *not* include situations that are better explained
393 /// by a local program simply crashing or terminating unexpectedly.
394 #[display("local protocol violation (local bug or incompatibility)")]
395 LocalProtocolViolation,
396
397 /// Someone or something on the Tor network violated the Tor protocols.
398 ///
399 /// This kind of error can happen when a remote Tor instance behaves in a
400 /// way we don't expect.
401 ///
402 /// It usually indicates a programming error: either in their implementation
403 /// of the protocol, or in ours. It can also indicate an attempted attack,
404 /// though that can be hard to diagnose.
405 #[display("Tor network protocol violation (bug, incompatibility, or attack)")]
406 TorProtocolViolation,
407
408 /// Something went wrong with a network connection or the local network.
409 ///
410 /// This kind of error is usually safe to retry, and shouldn't typically be
411 /// seen. By the time it reaches the caller, a more specific error type
412 /// should typically be available.
413 #[display("problem with network or connection")]
414 LocalNetworkError,
415
416 /// More of a local resource was needed, than is available (or than we are allowed)
417 ///
418 /// For example, we tried to use more memory than permitted by our memory quota.
419 #[display("local resource exhausted")]
420 LocalResourceExhausted,
421
422 /// A problem occurred when launching or communicating with an external
423 /// process running on this computer.
424 #[display("an externally launched plug-in tool failed")]
425 ExternalToolFailed,
426
427 /// A relay had an identity other than the one we expected.
428 ///
429 /// This could indicate a MITM attack, but more likely indicates that the
430 /// relay has changed its identity but the new identity hasn't propagated
431 /// through the directory system yet.
432 #[display("identity mismatch")]
433 RelayIdMismatch,
434
435 /// An attempt to do something remotely through the Tor network failed
436 /// because the circuit it was using shut down before the operation could
437 /// finish.
438 #[display("circuit collapsed")]
439 CircuitCollapse,
440
441 /// An operation timed out on the tor network.
442 ///
443 /// This may indicate a network problem, either with the local network
444 /// environment's ability to contact the Tor network, or with the Tor
445 /// network itself.
446 #[display("tor operation timed out")]
447 TorNetworkTimeout,
448
449 /// We tried but failed to download or upload a piece of directory information.
450 ///
451 /// This is a lower-level kind of error; in general it should be retried
452 /// before the user can see it. In the future it is likely to be split
453 /// into several other kinds.
454 // TODO ^
455 #[display("directory fetch or upload attempt failed")]
456 TorDirectoryError,
457
458 /// An operation finished because a remote stream was closed successfully.
459 ///
460 /// This can indicate that the target server closed the TCP connection,
461 /// or that the exit told us that it closed the TCP connection.
462 /// Callers should generally treat this like a closed TCP connection.
463 #[display("remote stream closed")]
464 RemoteStreamClosed,
465
466 /// An operation finished because the remote stream was closed abruptly.
467 ///
468 /// This kind of error is analogous to an ECONNRESET error; it indicates
469 /// that the exit reported that the stream was terminated without a clean
470 /// TCP shutdown.
471 ///
472 /// For most purposes, it's fine to treat this kind of error the same as
473 /// regular unexpected close.
474 #[display("remote stream reset")]
475 RemoteStreamReset,
476
477 /// An operation finished because a remote stream was closed unsuccessfully.
478 ///
479 /// This indicates that the exit reported some error message for the stream.
480 ///
481 /// We only provide this error kind when no more specific kind is available.
482 #[display("remote stream error")]
483 RemoteStreamError,
484
485 /// A stream failed, and the exit reports that the remote host refused
486 /// the connection.
487 ///
488 /// This is analogous to an ECONNREFUSED error.
489 #[display("remote host refused connection")]
490 RemoteConnectionRefused,
491
492 /// A stream was rejected by the exit relay because of that relay's exit
493 /// policy.
494 ///
495 /// (In Tor, exits have a set of policies declaring which addresses and
496 /// ports they're willing to connect to. Clients download only _summaries_
497 /// of these policies, so it's possible to be surprised by an exit's refusal
498 /// to connect somewhere.)
499 #[display("rejected by exit policy")]
500 ExitPolicyRejected,
501
502 /// An operation failed, and the exit reported that it waited too long for
503 /// the operation to finish.
504 ///
505 /// This kind of error is distinct from `RemoteNetworkTimeout`, which means
506 /// that _our own_ timeout threshold was violated.
507 #[display("timeout at exit relay")]
508 ExitTimeout,
509
510 /// An operation failed, and the exit reported a network failure of some
511 /// kind.
512 ///
513 /// This kind of error can occur for a number of reasons. If it happens
514 /// when trying to open a stream, it usually indicates a problem connecting,
515 /// such as an ENOROUTE error.
516 #[display("network failure at exit")]
517 RemoteNetworkFailed,
518
519 /// An operation finished because an exit failed to look up a hostname.
520 ///
521 /// Unfortunately, the Tor protocol does not distinguish failure of DNS
522 /// services ("we couldn't find out if this host exists and what its name is")
523 /// from confirmed denials ("this is not a hostname"). So this kind
524 /// conflates both those sorts of error.
525 ///
526 /// Trying at another exit might succeed, or the address might truly be
527 /// unresolvable.
528 #[display("remote hostname not found")]
529 RemoteHostNotFound,
530
531 /// The target hidden service (`.onion` service) was not found in the directory
532 ///
533 /// We successfully connected to at least one directory server,
534 /// but it didn't have a record of the hidden service.
535 ///
536 /// This probably means that the hidden service is not running, or does not exist.
537 /// (It might mean that the directory servers are faulty,
538 /// and that the hidden service was unable to publish its descriptor.)
539 #[display("Onion Service not found")]
540 OnionServiceNotFound,
541
542 /// The target hidden service (`.onion` service) seems to be down
543 ///
544 /// We successfully obtained a hidden service descriptor for the service,
545 /// so we know it is supposed to exist,
546 /// but we weren't able to communicate with it via any of its
547 /// introduction points.
548 ///
549 /// This probably means that the hidden service is not running.
550 /// (It might mean that the introduction point relays are faulty.)
551 #[display("Onion Service not running")]
552 OnionServiceNotRunning,
553
554 /// Protocol trouble involving the target hidden service (`.onion` service)
555 ///
556 /// Something unexpected happened when trying to connect to the selected hidden service.
557 /// It seems to have been due to the hidden service violating the Tor protocols somehow.
558 #[display("Onion Service protocol failed (apparently due to service behaviour)")]
559 OnionServiceProtocolViolation,
560
561 /// The target hidden service (`.onion` service) is running but we couldn't connect to it,
562 /// and we aren't sure whose fault that is
563 ///
564 /// This might be due to malfunction on the part of the service,
565 /// or a relay being used as an introduction point or relay,
566 /// or failure of the underlying Tor network.
567 #[display("Onion Service not reachable (due to service, or Tor network, behaviour)")]
568 OnionServiceConnectionFailed,
569
570 /// We tried to connect to an onion service without authentication,
571 /// but it apparently requires authentication.
572 #[display("Onion service required authentication, but none was provided.")]
573 OnionServiceMissingClientAuth,
574
575 /// We tried to connect to an onion service that requires authentication, and
576 /// ours is wrong.
577 ///
578 /// This likely means that we need to use a different key for talking to
579 /// this onion service, or that it has revoked our permissions to reach it.
580 #[display("Onion service required authentication, but provided authentication was incorrect.")]
581 OnionServiceWrongClientAuth,
582
583 /// We tried to parse a `.onion` address, and found that it was not valid.
584 ///
585 /// This likely means that it was corrupted somewhere along its way from its
586 /// origin to our API surface. It may be the wrong length, have invalid
587 /// characters, have an invalid version number, or have an invalid checksum.
588 #[display(".onion address was invalid.")]
589 OnionServiceAddressInvalid,
590
591 /// An resolve operation finished with an error.
592 ///
593 /// Contrary to [`RemoteHostNotFound`](ErrorKind::RemoteHostNotFound),
594 /// this can't mean "this is not a hostname".
595 /// This error should be retried.
596 #[display("remote hostname lookup failure")]
597 RemoteHostResolutionFailed,
598
599 /// Trouble involving a protocol we're using with a peer on the far side of the Tor network
600 ///
601 /// We were using a higher-layer protocol over a Tor connection,
602 /// and something went wrong.
603 /// This might be an error reported by the remote host within that higher protocol,
604 /// or a problem detected locally but relating to that higher protocol.
605 ///
606 /// The nature of the problem can vary:
607 /// examples could include:
608 /// failure to agree suitable parameters (incompatibility);
609 /// authentication problems (eg, TLS certificate trouble);
610 /// protocol violation by the peer;
611 /// peer refusing to provide service;
612 /// etc.
613 #[display("remote protocol violation")]
614 RemoteProtocolViolation,
615
616 /// An operation failed, and the relay in question reported that it's too
617 /// busy to answer our request.
618 #[display("relay too busy")]
619 RelayTooBusy,
620
621 /// We were asked to make an anonymous connection to a malformed address.
622 ///
623 /// This is probably because of a bad input from a user.
624 #[display("target address was invalid")]
625 InvalidStreamTarget,
626
627 /// We were asked to make an anonymous connection to a _locally_ disabled
628 /// address.
629 ///
630 /// For example, this kind of error can happen when try to connect to (e.g.)
631 /// `127.0.0.1` using a client that isn't configured with allow_local_addrs.
632 ///
633 /// Usually this means that you intended to reject the request as
634 /// nonsensical; but if you didn't, it probably means you should change your
635 /// configuration to allow what you want.
636 #[display("target address disabled locally")]
637 ForbiddenStreamTarget,
638
639 /// An operation failed in a transient way.
640 ///
641 /// This kind of error indicates that some kind of operation failed in a way
642 /// where retrying it again could likely have made it work.
643 ///
644 /// You should not generally see this kind of error returned directly to you
645 /// for high-level functions. It should only be returned from lower-level
646 /// crates that do not automatically retry these failures.
647 // Errors with this kind should generally not return a `HasRetryTime::retry_time()` of `Never`.
648 #[display("un-retried transient failure")]
649 TransientFailure,
650
651 /// Bug, for example calling a function with an invalid argument.
652 ///
653 /// This kind of error is usually a programming mistake on the caller's part.
654 /// This is usually a bug in code calling Arti, but it might be a bug in Arti itself.
655 //
656 // Usually, use `bad_api_usage!` and `into_bad_api_usage!` and thereby `InternalError`,
657 // rather than inventing a new type with this kind.
658 //
659 // Errors with this kind should generally include a stack trace. They are
660 // very like InternalError, in that they represent a bug in the program.
661 // The difference is that an InternalError, with kind `Internal`, represents
662 // a bug in arti, whereas errors with kind BadArgument represent bugs which
663 // could be (often, are likely to be) outside arti.
664 #[display("bad API usage (bug)")]
665 BadApiUsage,
666
667 /// We asked a relay to create or extend a circuit, and it declined.
668 ///
669 /// Either it gave an error message indicating that it refused to perform
670 /// the request, or the protocol gives it no room to explain what happened.
671 ///
672 /// This error is returned by higher-level functions only if it is the most informative
673 /// error after appropriate retries etc.
674 #[display("remote host refused our request")]
675 CircuitRefused,
676
677 /// We were unable to construct a path through the Tor network.
678 ///
679 /// Usually this indicates that there are too many user-supplied
680 /// restrictions for us to comply with.
681 ///
682 /// On test networks, it likely indicates that there aren't enough relays,
683 /// or that there aren't enough relays in distinct families.
684 //
685 // TODO: in the future, errors of this type should distinguish between
686 // cases where this happens because of a user restriction and cases where it
687 // happens because of a severely broken directory.
688 //
689 // The latter should be classified as TorDirectoryBroken.
690 #[display("could not construct a path")]
691 NoPath,
692
693 /// We were unable to find an exit relay with a certain set of desired
694 /// properties.
695 ///
696 /// Usually this indicates that there were too many user-supplied
697 /// restrictions on the exit for us to comply with, or that there was no
698 /// exit on the network supporting all of the ports that the user asked for.
699 //
700 // TODO: same as for NoPath.
701 #[display("no exit available for path")]
702 NoExit,
703
704 /// The Tor consensus directory is broken or unsuitable
705 ///
706 /// This could occur when running very old software
707 /// against the current Tor network,
708 /// so that the newer network is incompatible.
709 ///
710 /// It might also mean a catastrophic failure of the Tor network,
711 /// or that a deficient test network is in use.
712 ///
713 /// Currently some instances of this kind of problem
714 /// are reported as `NoPath` or `NoExit`.
715 #[display("Tor network consensus directory is not usable")]
716 TorDirectoryUnusable,
717
718 /// An operation failed because of _possible_ clock skew.
719 ///
720 /// The broken clock may be ours, or it may belong to another party on the
721 /// network. It's also possible that somebody else is lying about the time,
722 /// caching documents for far too long, or something like that.
723 #[display("possible clock skew detected")]
724 ClockSkew,
725
726 /// A directory told us that some document we were trying to upload
727 /// is not acceptable.
728 ///
729 /// This could be our fault (if we have a bug, if we're misconfigured,
730 /// if we are running very old software, etc),
731 /// or it could be the fault of the remote host
732 /// (if it is running very old software).
733 ///
734 /// In the case of an upload over unencrypted HTTP, this error
735 /// could also be the result of a MITM attacker impersonating the directory.
736 TorDocumentRejected,
737
738 /// Internal error (bug) in Arti.
739 ///
740 /// A supposedly impossible problem has arisen. This indicates a bug in
741 /// Arti; if the Arti version is relatively recent, please report the bug on
742 /// our [bug tracker](https://gitlab.torproject.org/tpo/core/arti/-/issues).
743 #[display("internal error (bug)")]
744 Internal,
745
746 /// Unclassified error
747 ///
748 /// Some other error occurred, which does not fit into any of the other kinds.
749 ///
750 /// This kind is provided for use by external code
751 /// hooking into or replacing parts of Arti.
752 /// It is never returned by the code in Arti (`arti-*` and `tor-*` crates).
753 #[display("unclassified error")]
754 Other,
755}
756
757/// Errors that can be categorized as belonging to an [`ErrorKind`]
758///
759/// The most important implementation of this trait is
760/// `arti_client::TorError`; however, other internal errors throughout Arti
761/// also implement it.
762pub trait HasKind {
763 /// Return the kind of this error.
764 fn kind(&self) -> ErrorKind;
765}
766
767#[cfg(feature = "futures")]
768impl HasKind for futures::task::SpawnError {
769 fn kind(&self) -> ErrorKind {
770 use ErrorKind as EK;
771 if self.is_shutdown() {
772 EK::ReactorShuttingDown
773 } else {
774 EK::Internal
775 }
776 }
777}
778
779impl HasKind for void::Void {
780 fn kind(&self) -> ErrorKind {
781 void::unreachable(*self)
782 }
783}
784
785impl HasKind for std::convert::Infallible {
786 fn kind(&self) -> ErrorKind {
787 unreachable!()
788 }
789}
790
791/// Sealed
792mod sealed {
793 /// Sealed
794 pub trait Sealed {}
795}