Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 59 insertions, 0 deletions

diff --git a/third_party/rust/viaduct/README.md b/third_party/rust/viaduct/README.md
new file mode 100644
index 0000000000..fd6adf5171
--- /dev/null
+++ b/third_party/rust/viaduct/README.md
@@ -0,0 +1,59 @@
+# Viaduct
+
+Viaduct is our HTTP request library, which can make requests either via a
+rust-based (reqwest) networking stack (used on iOS and for local desktop use,
+for tests and the like), or using a stack that calls a function passed into it
+over the FFI (on android).
+
+For usage info, you can run `cargo +nightly doc -p viaduct` (the `+nightly` is
+optional, however some intra-doc links require it), it has several examples.
+
+## Android/FFI Backend overview
+
+On Android, the backend works as follows:
+
+1. During megazord initialization, we are passed a `Lazy<Client>` (`Client` comes
+   from the [concept-fetch](https://github.com/mozilla-mobile/android-components/tree/master/components/concept/fetch)
+   android component, and `Lazy` is from the Kotlin stdlib).
+
+    - It also sets a flag that indicates that even if the FFI backend never gets
+      fully initialized (e.g. with a callback), we should error rather than use
+      the reqwest backend (which should not be compiled in, however we've had
+      trouble ensuring this in the past, although at this point we have checks
+      in CI to ensure it is not present).
+
+2. At this point, a JNA `Callback` instance is created and passed into Rust.
+    - This serves to proxy the request made by Rust to the `Client`.
+    - The `Callback` instance is never allowed to be GCed.
+    - To Rust, it's just a `extern "C"` function pointer that get's stored in an
+      atomic variable and never can be unset.
+
+3. When Rust makes a request:
+    1. We serialize the request info into a protobuf record
+    2. This record is passed into the function pointer we should have by this
+       point (erroring if it has not been set yet).
+    3. The callback (on the Java side now) deserializes the protobuf record,
+       converts it to a concept-fetch Request instance, and passes it to the
+       client.
+    4. The response (or error) is then converted into a protobuf record. The
+       java code then asks Rust for a buffer big enough to hold the serialized
+       response (or error).
+    5. The response is written to the buffer, and returned to Rust.
+    6. Rust then decodes the protobuf, and converts it to a
+      `viaduct::Response` object that it returns to the caller.
+
+Some notes:
+
+- This "request flow" is entirely synchronous, simplifying the implementation
+  considerably.
+
+- Cookies are explicitely not supported at the moment, adding them would
+  require a separate security review.
+
+- Generally, this is the way the FFI backend is expected to work on any
+  platform, but for concreteness (and because it's the only one currently using
+  the FFI backend), we explained it for Android.
+
+- Most of the code in `viaduct` is defining a ergonomic HTTP facade, and is
+  unrelated to this (or to the reqwest backend). This code is more or less
+  entirely (in the Kotlin layer and) in `src/backend/ffi.rs`.