Merge pull request #5 from getditto/initial-code

most of the initial code

.flutter-plugins

@@ -0,0 +1,8 @@
+# This is a generated file; do not edit or check into version control.
+device_info_plus=/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/
+ditto_live=/Users/cameron/.pub-cache/hosted/pub.dev/ditto_live-4.8.0-publicpreview.2/
+file_picker=/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/
+flutter_plugin_android_lifecycle=/Users/cameron/.pub-cache/hosted/pub.dev/flutter_plugin_android_lifecycle-2.0.22/
+webview_flutter=/Users/cameron/.pub-cache/hosted/pub.dev/webview_flutter-4.8.0/
+webview_flutter_android=/Users/cameron/.pub-cache/hosted/pub.dev/webview_flutter_android-3.16.8/
+webview_flutter_wkwebview=/Users/cameron/.pub-cache/hosted/pub.dev/webview_flutter_wkwebview-3.14.0/

.flutter-plugins-dependencies

@@ -0,0 +1 @@
+{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","native_build":true,"dependencies":[]},{"name":"ditto_live","path":"/Users/cameron/.pub-cache/hosted/pub.dev/ditto_live-4.8.0-publicpreview.2/","native_build":true,"dependencies":["device_info_plus"]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","native_build":true,"dependencies":[]},{"name":"webview_flutter_wkwebview","path":"/Users/cameron/.pub-cache/hosted/pub.dev/webview_flutter_wkwebview-3.14.0/","native_build":true,"dependencies":[]}],"android":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","native_build":true,"dependencies":[]},{"name":"ditto_live","path":"/Users/cameron/.pub-cache/hosted/pub.dev/ditto_live-4.8.0-publicpreview.2/","native_build":true,"dependencies":["device_info_plus"]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","native_build":true,"dependencies":["flutter_plugin_android_lifecycle"]},{"name":"flutter_plugin_android_lifecycle","path":"/Users/cameron/.pub-cache/hosted/pub.dev/flutter_plugin_android_lifecycle-2.0.22/","native_build":true,"dependencies":[]},{"name":"webview_flutter_android","path":"/Users/cameron/.pub-cache/hosted/pub.dev/webview_flutter_android-3.16.8/","native_build":true,"dependencies":[]}],"macos":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","native_build":true,"dependencies":[]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","native_build":false,"dependencies":[]}],"linux":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","native_build":false,"dependencies":[]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","native_build":false,"dependencies":[]}],"windows":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","native_build":false,"dependencies":[]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","native_build":false,"dependencies":[]}],"web":[{"name":"device_info_plus","path":"/Users/cameron/.pub-cache/hosted/pub.dev/device_info_plus-10.1.2/","dependencies":[]},{"name":"file_picker","path":"/Users/cameron/.pub-cache/hosted/pub.dev/file_picker-8.1.4/","dependencies":[]}]},"dependencyGraph":[{"name":"device_info_plus","dependencies":[]},{"name":"ditto_live","dependencies":["device_info_plus"]},{"name":"file_picker","dependencies":["flutter_plugin_android_lifecycle"]},{"name":"flutter_plugin_android_lifecycle","dependencies":[]},{"name":"webview_flutter","dependencies":["webview_flutter_android","webview_flutter_wkwebview"]},{"name":"webview_flutter_android","dependencies":[]},{"name":"webview_flutter_wkwebview","dependencies":[]}],"date_created":"2024-11-20 13:21:29.287824","version":"3.22.0"}

.gitignore

@@ -0,0 +1,29 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+build/

.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "5dcb86f68f239346676ceb1ed1ea385bd215fba1"
+  channel: "stable"
+
+project_type: package

CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+Initial release containing the `SyncStatusHelper` and `SyncStatusView` tools

README.md

@@ -1,2 +1,110 @@
-# DittoFlutterTools
+# `ditto_flutter_tools`
+
 Diagnostic and Debugging Tools for Ditto in Flutter
+
+## `SyncStatusHelper` and `SyncStatusView`
+
+These tools are intended to provide insights into the status of your subscriptions.
+`SyncStatusHelper` provides programmatic access to the collected data, and `SyncStatusView` provides a pre-made UI that can be embedded in an app for real-time debugging.
+
+To use it, pass in your `Ditto` instance, as well as a list of subscriptions you wish to monitor:
+```dart
+final syncStatusHelper = SyncStatusHelper(
+  ditto: ditto,
+  subscriptions: [
+    mySubscription1,
+    mySubscription2,
+  ],
+);
+```
+Alternatively, if you want to use all the subscriptions that are currently active, use the `fromCurrentSubscriptions` constructor:
+```dart
+final syncStatusHelper = SyncStatusHelper.fromCurrentSubscriptions(
+  ditto: ditto,
+);
+```
+Note that this will only monitor the subscriptions that are currently active. If you register a new subscription to the underlying `Ditto` instance, the `SyncStatusHelper` will not update.
+
+### Querying the data
+
+The helper provides an `overallStatus` getter, which provides a high-level overview of all subscriptions. This returns a `SyncStatus`:
+ - if your device is not connected to any other peers, `overallStatus` will be `disconnected`
+ - if your device is connected to at least one peer, and none of the subscriptions have been updated recently, `overallStatus` will be `connectedIdle`
+ - if your device is connected to at least one peer, and at least one of the subscriptions has been updated recently, `overallStatus` will be `connectedSyncing`
+
+You can configure the maximum time that can have passed for an update to be considered "recent" by providing the optional `idleTimeoutInterval` parameter (defaults to one second).
+
+You can also inspect individual subscriptions:
+```dart
+final helper = SyncStatusHelper(/* ... */);
+final subscription = helper.subscriptions[0];
+
+// the `SyncStatus` for a particular subscription
+print(helper.statusFor(subscription));
+
+// a `DateTime?`, null if this subscription has never been updated
+print(helper.lastUpdatedAt(subscription))
+```
+
+You can also see details about the connectivity of the device.
+A device is considered "connected" if and only if it is connected to at least one other peer.
+
+```dart
+final helper = SyncStatusHelper(/* ... */);
+
+// Is the device currently connected
+print(helper.isConnected);
+
+// A `DateTime?` representing the most recent time this device was connected
+// Will be `null` if this device has never been connected
+print(helper.lastConnectedAt);
+
+// `DateTime?`s representing the last time the connectivity status changed
+print(helper.becameConnectedAt);
+print(helper.becameDisconnectedAt);
+```
+
+For example, if a device had become connected to another device five minutes ago, and the connection had been uninterrupted for the entire duration:
+ - `lastConnectedAt` would be very close to `DateTime.now()` (though not exactly due to slight delay in reporting connectivity changes)
+ - `becameConnectedAt` would be five minutes ago
+ - `becameDisconnectedAt` would be `null`
+
+If, on the other hand, the device lost connectivity for one minute during that five minute period, you might see something like:
+ - `lastConnectedAt` would be very close to `DateTime.now()` (though not exactly due to slight delay in reporting connectivity changes)
+ - `becameConnectedAt` would be two minutes ago
+ - `becameDisconnectedAt` would be three minutes ago
+
+
+### Interpreting the data
+
+#### No historical tracking
+
+`SyncStatusHelper` only tracks data from the point at which it was created, and cannot provide data about any point in time before its creation.
+
+So for example, if your device was connected five minutes ago, then lost connectivity one minute ago, then you created a `SyncStatusHelper`, it would report that this device had never been connected.
+
+#### Peer-to-peer specific interpretations
+
+The sync state means:
+ - `disconnected` - you are not connected to other peers
+ - `connectedIdle` - you are connected to at least one peer and have not received recent updates
+ - `connectedSyncing` - you are connected to at least one peer and have received at least one recent update
+
+When connected to a big peer, being in a `connectedIdle` state can be interpreted as meaning "I am up to date with what the big peer has".
+However, if connected via peer-to-peer connection to another small peer, that interpretation isn't always correct.
+
+For example:
+ - you could be connected to another peer, but you are islanded from the rest of the mesh
+ - the peer you are connected to could have a different set of sync subscriptions, and so would have incomplete data
+
+#### Freshness
+
+You may also want to consider the "freshness" of data when you are disconnected.
+For example, consider the following scenarios:
+ - your device is `disconnected`, your subscription was last updated five days ago, and `lastConnectedAt` is five days ago
+ - your device is `disconnected`, your subscription was last updated five days ago, and `lastConnectedAt` is 1 minute ago
+
+In the second scenario, you can be quite confident that your data is still the most up-to-date version; it's quite unlikely that you have had no updates in the last five days, but in the one minute you've been offline, there's new data. Compare that with the first scenario, in which the last update was exactly when you lost connectivity.
+
+That said, the aim of this tool is to provide heuristics that you can combine with an understanding of your data model to get an accurate picture of the state of your device.
+If you have specific knowledge about your data model or update frequency, you can use that knowledge to get a clearer view of the data you have locally.

analysis_options.yaml

@@ -0,0 +1,4 @@
+include: package:flutter_lints/flutter.yaml
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

example/.gitignore

@@ -0,0 +1,43 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

example/.metadata

@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "5dcb86f68f239346676ceb1ed1ea385bd215fba1"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: android
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: ios
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: linux
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: macos
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: web
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+    - platform: windows
+      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

example/README.md

@@ -0,0 +1,16 @@
+# example
+
+A new Flutter project.
+
+## Getting Started
+
+This project is a starting point for a Flutter application.
+
+A few resources to get you started if this is your first Flutter project:
+
+- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
+- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+
+For help getting started with Flutter development, view the
+[online documentation](https://docs.flutter.dev/), which offers tutorials,
+samples, guidance on mobile development, and a full API reference.

example/analysis_options.yaml

@@ -0,0 +1,28 @@
+# This file configures the analyzer, which statically analyzes Dart code to
+# check for errors, warnings, and lints.
+#
+# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
+# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
+# invoked from the command line by running `flutter analyze`.
+
+# The following line activates a set of recommended lints for Flutter apps,
+# packages, and plugins designed to encourage good coding practices.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at https://dart.dev/lints.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    avoid_print: false  # Uncomment to disable the `avoid_print` rule
+    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

example/android/.gitignore

@@ -0,0 +1,13 @@
+gradle-wrapper.jar
+/.gradle
+/captures/
+/gradlew
+/gradlew.bat
+/local.properties
+GeneratedPluginRegistrant.java
+
+# Remember to never publicly share your keystore.
+# See https://flutter.dev/docs/deployment/android#reference-the-keystore-from-the-app
+key.properties
+**/*.keystore
+**/*.jks

example/android/app/build.gradle

@@ -0,0 +1,58 @@
+plugins {
+    id "com.android.application"
+    id "kotlin-android"
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id "dev.flutter.flutter-gradle-plugin"
+}
+
+def localProperties = new Properties()
+def localPropertiesFile = rootProject.file("local.properties")
+if (localPropertiesFile.exists()) {
+    localPropertiesFile.withReader("UTF-8") { reader ->
+        localProperties.load(reader)
+    }
+}
+
+def flutterVersionCode = localProperties.getProperty("flutter.versionCode")
+if (flutterVersionCode == null) {
+    flutterVersionCode = "1"
+}
+
+def flutterVersionName = localProperties.getProperty("flutter.versionName")
+if (flutterVersionName == null) {
+    flutterVersionName = "1.0"
+}
+
+android {
+    namespace = "com.example.example"
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+
+    defaultConfig {
+        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
+        applicationId = "com.example.example"
+        // You can update the following values to match your application needs.
+        // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration.
+        minSdk = 23
+        targetSdk = flutter.targetSdkVersion
+        versionCode = flutterVersionCode.toInteger()
+        versionName = flutterVersionName
+    }
+
+    buildTypes {
+        release {
+            // TODO: Add your own signing config for the release build.
+            // Signing with the debug keys for now, so `flutter run --release` works.
+            signingConfig = signingConfigs.debug
+        }
+    }
+}
+
+flutter {
+    source = "../.."
+}

example/android/app/src/debug/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>