summaryrefslogtreecommitdiff
path: root/crates/arti-client/src/lib.rs
Commit message (Collapse)AuthorAgeFilesLines
* enable doc_auto_cfg feature on every crate when documenting for docs.rstrinity-1686a2022-08-241-0/+1
|
* Document more explicitly what "voiding a semver warranty" entailsNick Mathewson2022-08-111-1/+5
| | | | Closes #522.
* Run maint/add_warning crates/*/src/{lib,main}.rsIan Jackson2022-06-231-0/+3
| | | | Update all lint blocks
* Merge branch 'main' into 'accel-features'Nick Mathewson2022-06-161-2/+5
|\ | | | | | | # Conflicts: # crates/arti-client/Cargo.toml
| * Remove "rustls" from "full", for license reasons.Nick Mathewson2022-06-151-2/+5
| | | | | | | | | | | | | | | | | | Rustls uses ring, which uses code from BoringSSL, which derived from OpenSSL before OpenSSL changed their license. So ring is currently under 3BSD/SSLEay licenses, which aren't GPL-compatible, which may be a problem for some people. See #493.
* | Add "accel-*" features to arti-client and arti.Nick Mathewson2022-06-131-0/+9
|/ | | | | | | | | | These need to be optional: they improve performance by shifting to asm implementations, which may not be everybody's idea of good practice. These are not 'pure' features, since they select one implementation but disable another. Therefore they don't go in `full`. Closes #441.
* Document "full", "experimental" in toplevel crate documentation.Nick Mathewson2022-06-131-41/+65
| | | | | Also, unify the features documentation format for those two crates, and document previously undocumented features there.
* lints: Add let_unit_value allow to all cratesIan Jackson2022-05-311-0/+1
| | | | | From running add_warning, with manual picking of the right hunks/lines.
* lints: Add lint block delimiters to every crateIan Jackson2022-05-311-0/+2
| | | | | | This was the result of: maint/add_warning crates/*/src/{lib,main}.rs and then manually curating the results.
* Implement a periodic task scheduler, and a basic dormant modeeta2022-03-231-1/+1
| | | | | | | | | | | This is a revised version of !397; it implements a scheduling system for periodic tasks that can be externally controlled, and then uses the external control aspect to implement a basic dormant mode (#90). More technically, the scheduling system consists of a `Stream` that periodic tasks are expected to embed in a `while` loop or similar, a way for tasks themselves to choose how long to wait until the stream next yields a result, and a handle to control this outside of the task.
* replace IsolationMap with new Isolation traittrinity-1686a2022-03-161-0/+1
|
* Merge branch 'dir-provider-redux' into 'main'Ian Jackson2022-03-021-0/+3
|\ | | | | | | | | Alternative DirProvider setup See merge request tpo/core/arti!347
| * Add a builder function for replacing a DirProvider.Nick Mathewson2022-02-231-0/+3
| | | | | | | | Put it behind experimental_api.
* | Merge branch 'clippy-allow-arc-clone' into 'main'Nick Mathewson2022-03-011-1/+0
|\ \ | | | | | | | | | | | | Disable clippy::clone_on_ref_ptr See merge request tpo/core/arti!352
| * | Disable clippy::clone_on_ref_ptrIan Jackson2022-02-241-1/+0
| |/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This lint is IMO inherently ill-conceived. I have looked for the reasons why this might be thought to be a good idea and there were basically two (and they are sort of contradictory): I. "Calling ‘.clone()` on an Rc, Arc, or Weak can obscure the fact that only the pointer is being cloned, not the underlying data." This is the wording from https://rust-lang.github.io/rust-clippy/v0.0.212/#clone_on_ref_ptr It is a bit terse; we are left to infer why it is a bad idea to obscure this fact. It seems to me that if it is bad to obscure some fact, that must be because the fact is a hazard. But why would it be a hazard to not copy the underlying data ? In other languages, faliing to copy the underlying data is a serious correctness hazard. There is a whose class of bugs where things were not copied, and then mutated and/or reused in multiple places in ways that were not what the programmer intended. In my experience, this is a very common bug when writing Python and Javascript. I'm told it's common in golang too. But in Rust this bug is much much harder to write. The data inside an Arc is immutable. To have this bug you'd have use interior mutability - ie mess around with Mutex or RefCell. That provides a good barrier to these kind of accidents. II. "The reason for writing Rc::clone and Arc::clone [is] to make it clear that only the pointer is being cloned, as opposed to the underlying data. The former is always fast, while the latter can be very expensive depending on what is being cloned." This is the reasoning found here https://github.com/rust-lang/rust-clippy/issues/2048 This is saying that *not* using Arc::clone is hazardous. Specifically, that a deep clone is a performance hazard. But for this argument, the lint is precisely backwards. It's linting the "good" case and asking for it to be written in a more explicit way; while the supposedly bad case can be written conveniently. Also, many objects (in our codebase, and in all the libraries we use) that are Clone are in fact simply handles. They contain Arc(s) (or similar) and are cheap to clone. Indeed, that is the usual case. It does not make sense to distinguish in the syntax we use to clone such a handle, whether the handle is a transparent Arc, or an opaque struct containing one or more other handles. Forcing Arc::clone to be written as such makes for code churn when a type is changed from Arc<Something> to Something: Clone, or vice versa.
* | Merge branch '010_docs'Nick Mathewson2022-03-011-5/+12
|\ \
| * | Update our stability warning on arti-client.Nick Mathewson2022-02-281-5/+12
| | |
* | | Merge branch 'main'Ian Jackson2022-03-011-2/+6
|\| | | | | | | | | | | | | | | | | | | | Fixed conflict in crates/arti-client/src/lib.rs as per tree from https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/364/#note_2782166 ie 13e55b8d7c22c26e55ba75823409b477f1bce66b
| * | Split "static" into sqlite and native-tls features.Nick Mathewson2022-02-251-4/+19
| | | | | | | | | | | | | | | | | | | | | Otherwise, it's impossible to get a static sqlite linkage without also getting native-tls, even if you wanted rustls. Closes #302.
* | | arti-client: use PreferredRuntime by default, doc cleanupseta2022-02-281-59/+75
|/ / | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This makes using the `PreferredRuntime` the first-class option inside `arti-client`, freeing users who don't want to think about runtimes from having to do so. `TorClient::create_unbootstrapped` and `builder` now automatically use this runtime, leaving only `builder_custom` for users who wish to manually specify a runtime. This lets us clean up the docs a lot: mentions of using custom runtimes are now relegated to nearer the end of the crate-level documentation, and we mostly just link to `tor_rtcompat`'s docs to explain more there. Instead, we take some more time to explain how you use the builder API to create clients synchronously. Other doc cleanups included getting rid of the explanation of `TorAddr` in the main crate-level doc; this is already well-documented elsewhere, and is something users should discover organically later. fixes arti#326
* / arti-client: Unlock the state manager on failure to bootstrapeta2022-02-241-0/+1
|/ | | | | | | | | | | | `StateMgr` got a new `unlock()` method that does what it says on the tin. We now call it from `bootstrap()` using the new `util::StateMgrUnlockGuard`, which works in a manner similar to the `BoolResetter` from `tor_dirmgr`. (A decent small little task in future might be to unify these types in some sort of general arti utility crate?) closes arti#335
* Make a TorClientBuilder API.Nick Mathewson2022-02-181-0/+2
| | | | | | | | This is a defensive API choice to protect against the possibility that we'll want to add a bunch of other non-config options in the future. Closes #350
* arti-client: add ability to automatically bootstrapeta2022-02-161-1/+1
| | | | | | | | | | | | | The new `BootstrapBehavior` enum controls whether an unbootstrapped `TorClient` will bootstrap itself automatically (`Ondemand`) when an attempt is made to use it, or whether the user must perform bootstrapping themselves (`Manual`). The `lazy-init` example shows how you could write a simple `get_tor_client()` function that used a global `OnceCell` to share a Tor client across an entire application with this API. closes arti#278
* Change deny(clippy::all) to warn(clippy::all).Nick Mathewson2022-02-141-1/+1
| | | | Closes #338.
* Rename bootstrap_existing to bootstrap.Nick Mathewson2022-02-111-2/+2
| | | | (Looks like this one got missed.)
* Allow creating unbootstrapped `TorClient`s (and `DirMgr`s)eta2022-02-111-1/+1
| | | | | | | | | | | | | | | This commit changes how the `TorClient` type works, enabling it to be constructed synchronously without initiating the bootstrapping process. Daemon tasks are still started on construction (although some of them won't do anything if the client isn't bootstrapped). The old bootstrap() methods are now reimplemented in terms of the new create_unbootstrapped() and bootstrap_existing() methods. This required refactoring how the `DirMgr` works to enable the same sort of thing there. closes #293
* ErrorDetail Simplify visibility macros a bit.Nick Mathewson2022-02-081-7/+0
| | | | | | | | Instead of declaring a macro that takes vis as an argument, we now conditionally declare a macro that applies an appropriate visibility. There's a long comment explaining the rationale here, along with a couple of other solutions that don't work.
* Rename TorResult to Result.Nick Mathewson2022-02-081-3/+3
| | | | | | | This is closer to common usage. (Not that we all agree with common usage, but it's closer to what people expect.)
* arti_client: Rename Error to ErrorDetail.Nick Mathewson2022-02-081-4/+1
| | | | | | | This is closer to what we described in Errors.md. Also, remove the (sometimes private) Result alias: it was only used in one or two places, and never exposed in public.
* Docs and clarification for a bunch of Error stuffNick Mathewson2022-02-041-60/+75
|
* Make the Error detail type non-exported from arti-clientNick Mathewson2022-02-041-4/+2
| | | | | | | | | | | At least by default, we should have Error be private, and not expose it as part of our APIs. To keep functionality in `arti`, I had to add an `ExitTimeout` error kind. For interface consistency, I also re-exported ErrorKind and HasError from `arti_client`.
* errors: Introduce error_detail featureIan Jackson2022-02-041-1/+17
| | | | | Right now we must always expose the `Error` type since we haven't converted everything.
* errors: Refer to err::Error in some bits of arti_clientIan Jackson2022-02-041-3/+1
| | | | We are going to make the top-level Error type conditionally hidden.
* errors: Introduce TorErrorIan Jackson2022-02-041-2/+4
| | | | Still much to do here.
* Fix documentation references for tor-rtcompat refactoring.Nick Mathewson2022-01-261-5/+7
|
* Make current/create functions into runtime member functions.Nick Mathewson2022-01-261-1/+1
| | | | | This should help avoid some amount of temptation towards API proliferation.
* StreamPrefs: rename from ConnectPrefsIan Jackson2022-01-211-2/+2
| | | | | | | | | | | | | The docs even say this is about stream. As @nickm writes in https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/252#note_2771289 we generally call end-to-end connections that are tunneled over Tor "Streams" to distinguish them from everything else in the Tor protocols that could possibly be called a "Connection". That seems to apply here too.
* Implement the basics of a bootstrap-status API.Nick Mathewson2022-01-131-0/+1
| | | | | | | | | | | | The purpose of a this API is to tell the user how far along Arti is in getting bootstrapped, and if it's stuck, what it's stuck on. This API doesn't yet expose any useful information: by the time it's observable to a client, it's always "100% bootstrapped." But I'm putting it in a MR now so that we can review the basic idea, and to avoid conflicts with later work on tickets like #293 and #278. This is part of #96.
* Improve the layout of crate exports; add runtime convenience functionseta2022-01-111-1/+1
| | | | | | | | | | | | | | | | | | | | This commit addresses multiple problems highlighted by arti#182: - `arti-client` had some types in its public API that weren't accessible without importing another crate (`CfgPath`, `DataReader`, `DataWriter`). This has been fixed. - In addition, the doc comments for `DataReader` and `DataWriter` were cleaned up to be of better quality, now that they're public. - It was impossible to use `arti-client` without also importing `tor-rtcompat`. This is now fixed by the addition of two convenience methods: `TorClient::bootstrap_with_tokio` and `TorClient::bootstrap_with_async_std`. - Potentially controversially: `tor-rtcompat` now returns *concrete* types from methods like `current_runtime`, instead of `impl Runtime`. - This was needed in order to actually be able to name the `TorClient` type that results from using these methods. - This does mean we lose API flexibility, but on balance I think this is a good thing, because the API we *do* have is actually usable...
* Make the arti_client::Result type public.Nick Mathewson2022-01-101-2/+2
| | | | Closes #280.
* Use *_with_prefs() for Option<ConnectPrefs> callers in TorClient::connectNeel Chauhan2022-01-081-1/+1
|
* extend lints to include 'clippy::all'Daniel Eades2021-12-281-0/+1
|
* Change sane_defaults() and with_directories()Nick Mathewson2021-11-291-1/+1
| | | | | | | | The sane_defaults() call is now the same as you get from a default builder: by convention, we just call that method Default::default(). The with_directories() constructor makes more sense as a constructor for the TorClientConfigBuilder than for TorClientConfig.
* add semicolons if nothing returnedDaniel Eades2021-11-251-0/+1
|
* More typo fixes that I forgot to save :(Nick Mathewson2021-11-241-2/+2
|
* Improve docs of more (potentially re-exported) arti-client typeseta2021-10-291-12/+0
| | | | | | | | | | | | | | | | | | | | | Most of the structs in `arti-client` have example code now, to give a clearer idea of how they're used. Annoyingly, a lot of the types exposed in `arti-client` are actually re-exports, which makes documentation a bit harder: example code that references other parts of `arti-client` can't actually be run as a doctest, since the crate it's in is a dependency of `arti-client`. We might be able to fix this in future by doing the documentation in `arti-client` itself, but rustdoc seems to have some weird behaviours there that need to be investigated first (for example, it seems to merge the re-export and original documentation, and also put the re-export documentation on the `impl` block for some reason). For now, though, this commit just writes the docs from the point of view of an `arti-client` consumer, removing notes specific to the crate in which they're defined. It's not ideal, but at least the end user experience is decent.
* arti-client example: Try to make the comments a little more clear.Nick Mathewson2021-10-281-6/+10
| | | | | I'm not 100% sure this is better, but it might help the user understand how Arti works a bit better.
* Improve top-level arti-client documentation, add example codeeta2021-10-281-15/+99
| | | | | | | | | | | | | | | | | | | | | This overhauls the top-level `arti-client` documentation significantly: - the "Using arti-client" section walks the user through all of the necessary steps to initiate a Torified TCP connection, and then provides a code example - this example is also available as `examples/readme.rs`; it's not run as a doctest, since it involves connecting to Tor - a "More advanced usage" subheading provides information about stream isolation (and can potentially be used for other interesting features once we get them). - a new "Multiple runtime support" section was added to explain the purpose and usage of the `tor-rtcompat` crate - the section on design and privacy considerations was removed; this is probably okay to keep in a README, but users of the crate aren't going to be interested in this (at least I don't think) (also, the doc comment for `arti_client::Error` was fixed to make actual sense)
* Update our disclaimers and limitations sections.Nick Mathewson2021-10-271-16/+7
|
* s/arti-arti-client/arti-client/ and regenerate readme filesNick Mathewson2021-10-251-1/+1
|
generated by cgit v1.2.3 (git 2.46.0) at 2026-08-27 09:15:10 +0000