api: Embed platform and app info in user-agent

Generate the user-agent using `deviceInfo` and `packageInfo` from
ZulipBinding, and since it now depends on them, move the function
to the ZulipBinding class — making it explicit to the caller that
it depends on ZulipBinding being initialised.

In addition to that, support fetching macOS, Windows and Linux
device information, so that user-agents for them can be generated.

Fixes: #467

Author: rajveermalviya

lib/api/core.dart

@@ -4,6 +4,7 @@ import 'dart:io';
 import 'package:http/http.dart' as http;
 
 import '../log.dart';
+import '../model/binding.dart';
 import '../model/localizations.dart';
 import 'exception.dart';
 
@@ -88,7 +89,7 @@ class ApiConnection {
     assert(debugLog("${request.method} ${request.url}"));
 
     addAuth(request);
-    request.headers.addAll(userAgentHeader());
+    request.headers.addAll(ZulipBinding.instance.userAgentHeader());
     if (overrideUserAgent != null) {
       request.headers['User-Agent'] = overrideUserAgent;
     }
@@ -213,13 +214,6 @@ Map<String, String> authHeader({required String email, required String apiKey})
   };
 }
 
-Map<String, String> userAgentHeader() {
-  return {
-    // TODO(#467) include platform, platform version, and app version
-    'User-Agent': 'ZulipFlutter',
-  };
-}
-
 Map<String, String>? encodeParameters(Map<String, dynamic>? params) {
   return params?.map((k, v) =>
     MapEntry(k, v is RawParameter ? v.value : jsonEncode(v)));

lib/model/binding.dart

@@ -131,6 +131,12 @@ abstract class ZulipBinding {
 
   /// Wraps the [AndroidNotificationHostApi] constructor.
   AndroidNotificationHostApi get androidNotificationHost;
+
+  /// Generates a user agent header for HTTP requests.
+  ///
+  /// Uses [deviceInfo] to get operating system information
+  /// and [packageInfo] to get application version information.
+  Map<String, String> userAgentHeader();
 }
 
 /// Like [device_info_plus.BaseDeviceInfo], but without things we don't use.
@@ -140,13 +146,23 @@ abstract class BaseDeviceInfo {
 
 /// Like [device_info_plus.AndroidDeviceInfo], but without things we don't use.
 class AndroidDeviceInfo extends BaseDeviceInfo {
+  /// The user-visible version string.
+  ///
+  /// E.g., "1.0" or "3.4b5" or "bananas". This field is an opaque string.
+  /// Do not assume that its value has any particular structure or that
+  /// values of RELEASE from different releases can be somehow ordered.
+  final String release;
+
   /// The Android SDK version.
   ///
   /// Possible values are defined in:
   ///   https://developer.android.com/reference/android/os/Build.VERSION_CODES.html
   final int sdkInt;
 
-  AndroidDeviceInfo({required this.sdkInt});
+  AndroidDeviceInfo({
+    required this.release,
+    required this.sdkInt,
+  });
 }
 
 /// Like [device_info_plus.IosDeviceInfo], but without things we don't use.
@@ -159,6 +175,59 @@ class IosDeviceInfo extends BaseDeviceInfo {
   IosDeviceInfo({required this.systemVersion});
 }
 
+/// Like [device_info_plus.MacOsDeviceInfo], but without things we don't use.
+class MacOsDeviceInfo extends BaseDeviceInfo {
+  /// The major release number, such as 10 in version 10.9.3.
+  final int majorVersion;
+
+  /// The minor release number, such as 9 in version 10.9.3.
+  final int minorVersion;
+
+  /// The update release number, such as 3 in version 10.9.3.
+  final int patchVersion;
+
+  MacOsDeviceInfo({
+    required this.majorVersion,
+    required this.minorVersion,
+    required this.patchVersion,
+  });
+}
+
+/// Like [device_info_plus.WindowsDeviceInfo], currently only used to
+/// determine if we're on Windows.
+class WindowsDeviceInfo implements BaseDeviceInfo {}
+
+/// Like [device_info_plus.LinuxDeviceInfo], but without things we don't use.
+///
+/// See:
+///   https://www.freedesktop.org/software/systemd/man/os-release.html
+class LinuxDeviceInfo implements BaseDeviceInfo {
+  /// A string identifying the operating system, without a version component,
+  /// and suitable for presentation to the user.
+  ///
+  /// Examples: 'Fedora', 'Debian GNU/Linux'.
+  ///
+  /// If not set, defaults to 'Linux'.
+  final String name;
+
+  /// A lower-case string identifying the operating system version, excluding
+  /// any OS name information or release code name, and suitable for processing
+  /// by scripts or usage in generated filenames.
+  ///
+  /// The version is mostly numeric, and contains no spaces or other characters
+  /// outside of 0–9, a–z, '.', '_' and '-'.
+  ///
+  /// Examples: '17', '11.04'.
+  ///
+  /// This field is optional and may be null on some systems.
+  final String? versionId;
+
+  LinuxDeviceInfo({
+    required this.name,
+    required this.versionId,
+  });
+}
+
 /// Like [package_info_plus.PackageInfo], but without things we don't use.
 class PackageInfo {
   final String version;
@@ -191,6 +260,9 @@ class LiveZulipBinding extends ZulipBinding {
     return ZulipBinding.instance as LiveZulipBinding;
   }
 
+  // Stored user agent header, since it remains constant.
+  Map<String, String>? _userAgentHeader;
+
   @override
   BaseDeviceInfo get deviceInfo => _deviceInfo!;
   BaseDeviceInfo? _deviceInfo;
@@ -202,9 +274,16 @@ class LiveZulipBinding extends ZulipBinding {
   Future<void> _prefetchDeviceInfo() async {
     final info = await device_info_plus.DeviceInfoPlugin().deviceInfo;
     _deviceInfo = switch (info) {
-      device_info_plus.AndroidDeviceInfo(:var version)   => AndroidDeviceInfo(sdkInt: version.sdkInt),
-      device_info_plus.IosDeviceInfo(:var systemVersion) => IosDeviceInfo(systemVersion: systemVersion),
-      _                                                  => throw UnimplementedError(),
+      device_info_plus.AndroidDeviceInfo() => AndroidDeviceInfo(release: info.version.release,
+                                                                sdkInt: info.version.sdkInt),
+      device_info_plus.IosDeviceInfo()     => IosDeviceInfo(systemVersion: info.systemVersion),
+      device_info_plus.MacOsDeviceInfo()   => MacOsDeviceInfo(majorVersion: info.majorVersion,
+                                                              minorVersion: info.minorVersion,
+                                                              patchVersion: info.patchVersion),
+      device_info_plus.WindowsDeviceInfo() => WindowsDeviceInfo(),
+      device_info_plus.LinuxDeviceInfo()   => LinuxDeviceInfo(name: info.name,
+                                                              versionId: info.versionId),
+      _                                    => throw UnimplementedError(),
     };
   }
 
@@ -268,4 +347,39 @@ class LiveZulipBinding extends ZulipBinding {
 
   @override
   AndroidNotificationHostApi get androidNotificationHost => AndroidNotificationHostApi();
+
+  @override
+  Map<String, String> userAgentHeader() {
+    return _userAgentHeader ??= buildUserAgentHeader(deviceInfo, packageInfo);
+  }
+}
+
+@visibleForTesting
+Map<String, String> buildUserAgentHeader(BaseDeviceInfo deviceInfo, PackageInfo packageInfo) {
+  final osInfo = switch (deviceInfo) {
+    AndroidDeviceInfo(
+      :var release)       => 'Android $release', // "Android 14"
+    IosDeviceInfo(
+      :var systemVersion) => 'iOS $systemVersion', // "iOS 17.4"
+    MacOsDeviceInfo(
+      :var majorVersion,
+      :var minorVersion,
+      :var patchVersion)  => 'macOS $majorVersion.$minorVersion.$patchVersion', // "macOS 14.5.0"
+    WindowsDeviceInfo()   => 'Windows', // "Windows"
+    LinuxDeviceInfo(
+      :var name,
+      :var versionId)     => 'Linux; $name${versionId != null ? ' $versionId' : ''}', // "Linux; Fedora Linux 40" or "Linux; Fedora Linux"
+    _                     => throw UnimplementedError(),
+  };
+  final PackageInfo(:version, :buildNumber) = packageInfo;
+
+  // Possible examples:
+  //  'ZulipFlutter/0.0.15+15 (Android 14)'
+  //  'ZulipFlutter/0.0.15+15 (iOS 17.4)'
+  //  'ZulipFlutter/0.0.15+15 (macOS 14.5.0)'
+  //  'ZulipFlutter/0.0.15+15 (Windows)'
+  //  'ZulipFlutter/0.0.15+15 (Linux; Fedora Linux 40)'
+  return {
+    'User-Agent': 'ZulipFlutter/$version+$buildNumber ($osInfo)',
+  };
 }

lib/widgets/content.dart

@@ -1235,7 +1235,7 @@ class RealmContentNetworkImage extends StatelessWidget {
         if (src.origin == account.realmUrl.origin) ...authHeader(
           email: account.email, apiKey: account.apiKey,
         ),
-        ...userAgentHeader(),
+        ...ZulipBinding.instance.userAgentHeader(),
       },
       cacheWidth: cacheWidth,
       cacheHeight: cacheHeight,

lib/widgets/lightbox.dart

@@ -7,6 +7,7 @@ import 'package:video_player/video_player.dart';
 import '../api/core.dart';
 import '../api/model/model.dart';
 import '../log.dart';
+import '../model/binding.dart';
 import 'content.dart';
 import 'dialog.dart';
 import 'page.dart';
@@ -389,7 +390,7 @@ class _VideoLightboxPageState extends State<VideoLightboxPage> with PerAccountSt
         email: store.account.email,
         apiKey: store.account.apiKey,
       ),
-      ...userAgentHeader()
+      ...ZulipBinding.instance.userAgentHeader(),
     });
     _controller!.addListener(_handleVideoControllerUpdate);
 

test/api/core_test.dart

@@ -6,14 +6,19 @@ import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/core.dart';
 import 'package:zulip/api/exception.dart';
+import 'package:zulip/model/binding.dart';
 import 'package:zulip/model/localizations.dart';
 
+import '../model/binding.dart';
 import '../stdlib_checks.dart';
 import 'exception_checks.dart';
 import 'fake_api.dart';
 import '../example_data.dart' as eg;
 
 void main() {
+  TestZulipBinding.ensureInitialized();
+  tearDown(testBinding.reset);
+
   test('ApiConnection.get', () async {
     Future<void> checkRequest(Map<String, dynamic>? params, String expectedRelativeUrl) {
       return FakeApiConnection.with_(account: eg.selfAccount, (connection) async {
@@ -24,7 +29,7 @@ void main() {
           ..url.asString.equals('${eg.realmUrl.origin}$expectedRelativeUrl')
           ..headers.deepEquals({
             ...authHeader(email: eg.selfAccount.email, apiKey: eg.selfAccount.apiKey),
-            ...userAgentHeader(),
+            ...testBinding.userAgentHeader(),
           })
           ..body.equals('');
       });
@@ -55,7 +60,7 @@ void main() {
           ..url.asString.equals('${eg.realmUrl.origin}/api/v1/example/route')
           ..headers.deepEquals({
             ...authHeader(email: eg.selfAccount.email, apiKey: eg.selfAccount.apiKey),
-            ...userAgentHeader(),
+            ...testBinding.userAgentHeader(),
             if (expectContentType)
               'content-type': 'application/x-www-form-urlencoded; charset=utf-8',
           })
@@ -88,7 +93,7 @@ void main() {
           ..url.asString.equals('${eg.realmUrl.origin}/api/v1/example/route')
           ..headers.deepEquals({
             ...authHeader(email: eg.selfAccount.email, apiKey: eg.selfAccount.apiKey),
-            ...userAgentHeader(),
+            ...testBinding.userAgentHeader(),
           })
           ..fields.deepEquals({})
           ..files.single.which((it) => it
@@ -121,7 +126,7 @@ void main() {
           ..url.asString.equals('${eg.realmUrl.origin}/api/v1/example/route')
           ..headers.deepEquals({
             ...authHeader(email: eg.selfAccount.email, apiKey: eg.selfAccount.apiKey),
-            ...userAgentHeader(),
+            ...testBinding.userAgentHeader(),
             if (expectContentType)
               'content-type': 'application/x-www-form-urlencoded; charset=utf-8',
           })
@@ -308,6 +313,39 @@ void main() {
       check(st.toString()).contains("distinctivelyNamedFromJson");
     }
   });
+
+  group('ApiConnection user-agent', () {
+    Future<void> checkUserAgent(String expectedUserAgent) async {
+      return FakeApiConnection.with_(account: eg.selfAccount, (connection) async {
+        connection.prepare(json: {});
+        await connection.get(kExampleRouteName, (json) => json, 'example/route', null);
+        check(connection.lastRequest!).isA<http.Request>()
+          .headers.deepEquals({
+            ...authHeader(email: eg.selfAccount.email, apiKey: eg.selfAccount.apiKey),
+            ...{'User-Agent': expectedUserAgent},
+          });
+      });
+    }
+
+    final packageInfo = PackageInfo(version: '0.0.1', buildNumber: '1');
+
+    final testCases = [
+      ('ZulipFlutter/0.0.1+1 (Android 14)',             AndroidDeviceInfo(release: '14', sdkInt: 34),                        packageInfo),
+      ('ZulipFlutter/0.0.1+1 (iOS 17.4)',               IosDeviceInfo(systemVersion: '17.4'),                                packageInfo),
+      ('ZulipFlutter/0.0.1+1 (macOS 14.5.0)',           MacOsDeviceInfo(majorVersion: 14, minorVersion: 5, patchVersion: 0), packageInfo),
+      ('ZulipFlutter/0.0.1+1 (Windows)',                WindowsDeviceInfo(),                                                 packageInfo),
+      ('ZulipFlutter/0.0.1+1 (Linux; Fedora Linux 40)', LinuxDeviceInfo(name: 'Fedora Linux', versionId: '40'),              packageInfo),
+      ('ZulipFlutter/0.0.1+1 (Linux; Fedora Linux)',    LinuxDeviceInfo(name: 'Fedora Linux', versionId: null),              packageInfo),
+    ];
+
+    for (final (userAgent, deviceInfo, pacakgeInfo) in testCases) {
+      test('matches $userAgent', () async {
+        testBinding.deviceInfoResult = deviceInfo;
+        testBinding.packageInfoResult = pacakgeInfo;
+        await checkUserAgent(userAgent);
+      });
+    }
+  });
 }
 
 class DistinctiveError extends Error {

test/api/fake_api_test.dart

@@ -2,10 +2,14 @@ import 'package:checks/checks.dart';
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/exception.dart';
 
+import '../model/binding.dart';
 import 'exception_checks.dart';
 import 'fake_api.dart';
 
 void main() {
+  TestZulipBinding.ensureInitialized();
+  tearDown(testBinding.reset);
+
   test('baseline happy case', () async {
     final connection = FakeApiConnection();
     connection.prepare(json: {'a': 3});

test/api/route/messages_test.dart

@@ -3,18 +3,21 @@ import 'dart:convert';
 import 'package:checks/checks.dart';
 import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
-import 'package:zulip/api/core.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/model/narrow.dart';
 import 'package:zulip/api/route/messages.dart';
 import 'package:zulip/model/narrow.dart';
 
 import '../../example_data.dart' as eg;
+import '../../model/binding.dart';
 import '../../stdlib_checks.dart';
 import '../fake_api.dart';
 import 'route_checks.dart';
 
 void main() {
+  TestZulipBinding.ensureInitialized();
+  tearDown(testBinding.reset);
+
   group('getMessageCompat', () {
     Future<Message?> checkGetMessageCompat(FakeApiConnection connection, {
       required bool expectLegacy,
@@ -316,7 +319,7 @@ void main() {
         ..method.equals('POST')
         ..url.path.equals('/api/v1/messages')
         ..bodyFields.deepEquals(expectedBodyFields)
-        ..headers['User-Agent'].equals(expectedUserAgent ?? userAgentHeader()['User-Agent']!);
+        ..headers['User-Agent'].equals(expectedUserAgent ?? testBinding.userAgentHeader()['User-Agent']!);
     }
 
     test('smoke', () {

test/api/route/notifications_test.dart

@@ -3,10 +3,14 @@ import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/route/notifications.dart';
 
+import '../../model/binding.dart';
 import '../../stdlib_checks.dart';
 import '../fake_api.dart';
 
 void main() {
+  TestZulipBinding.ensureInitialized();
+  tearDown(testBinding.reset);
+
   group('registerFcmToken', () {
     Future<void> checkRegisterFcmToken(FakeApiConnection connection, {
       required String token,