diff options
Diffstat (limited to 'third_party/rust/tabs/README.md')
| -rw-r--r-- | third_party/rust/tabs/README.md | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/third_party/rust/tabs/README.md b/third_party/rust/tabs/README.md new file mode 100644 index 0000000000..fc57a02908 --- /dev/null +++ b/third_party/rust/tabs/README.md @@ -0,0 +1,62 @@ +# Synced Tabs Component + + + +## Implementation Overview + +This crate implements an in-memory syncing engine for remote tabs. + +## Directory structure +The relevant directories are as follows: + +- `src`: The meat of the library. This contains cross-platform rust code that + implements the syncing of tabs. +- `ffi`: The Rust public FFI bindings. This is a (memory-unsafe, by necessity) + API that is exposed to Kotlin and Swift. It leverages the `ffi_support` crate + to avoid many issues and make it more safe than it otherwise would be. + It uses protocol buffers for marshalling data over the FFI. +- `android`: This contains android bindings to synced tabs, written in Kotlin. These + use JNA to call into to the code in `ffi`. +- `ios`: This contains the iOS binding to synced tabs, written in Swift. These use + Swift's native support for calling code written in C to call into the code in + `ffi`. + +## Features +- Synchronization of the local and remote session states. + +## Business Logic + +### Storage + +The storage is all done in memory for simplicity purposes. The host applications are free to persist the remote tabs list if it makes sense to them. + +### Payload format + +Every remote sync record is roughly a list of tabs with their URL history (think of the back button). There is one record for each client. + +### Association with device IDs + +Each remote tabs sync record is associated to a "client" using a `client_id` field, which is really a foreign-key to a `clients` collection record. +However, because we'd like to move away from the clients collection, which is why this crate associates these records with Firefox Accounts device ids. +Currently for platforms using the sync-manager provided in this repo, the `client_id` is really the Firefox Accounts device ID and all is well, however for older platforms it is a distinct ID, which is why we have to feed the `clients` collection to this Tabs Sync engine to associate the correct Firefox Account device id. + +## Getting started + +**Prerequisites**: Firefox account authentication is necessary to obtain the keys to decrypt synced tabs data. See the [android-components FxA Client readme](https://github.com/mozilla-mobile/android-components/blob/master/components/service/firefox-accounts/README.md) for details on how to implement on Android. For iOS, Firefox for iOS still implement the legacy oauth. + +**Platform-specific details**: +- <TODO-ST> Android +- iOS: start with the [guide to consuming rust components on iOS](https://github.com/mozilla/application-services/blob/main/docs/howtos/consuming-rust-components-on-ios.md) + +## API Documentation +- TODO + +## Testing + +<TODO-ST> + +## Telemetry +<TODO-ST> + +## Examples +<TODO-ST> |