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';
 
@@ -37,11 +38,14 @@ class ApiConnection {
     String? email,
     String? apiKey,
     required http.Client client,
+    Map<String, String>? userAgentHeader,
   }) : assert((email != null) == (apiKey != null)),
        _authValue = (email != null && apiKey != null)
          ? _authHeaderValue(email: email, apiKey: apiKey)
          : null,
-       _client = client;
+       _client = client,
+       _userAgentHeader =
+         userAgentHeader ?? <String, String>{'User-Agent': 'ZulipFlutter'};
 
   /// Construct an API connection that talks to a live Zulip server over the real network.
   ApiConnection.live({
@@ -51,7 +55,8 @@ class ApiConnection {
     String? apiKey,
   }) : this(client: http.Client(),
             realmUrl: realmUrl, zulipFeatureLevel: zulipFeatureLevel,
-            email: email, apiKey: apiKey);
+            email: email, apiKey: apiKey,
+            userAgentHeader: ZulipBinding.instance.userAgentHeader());
 
   final Uri realmUrl;
 
@@ -69,6 +74,8 @@ class ApiConnection {
   ///  * API docs at <https://zulip.com/api/changelog>.
   int? zulipFeatureLevel;
 
+  final Map<String, String> _userAgentHeader;
+
   final String? _authValue;
 
   void addAuth(http.BaseRequest request) {
@@ -88,7 +95,7 @@ class ApiConnection {
     assert(debugLog("${request.method} ${request.url}"));
 
     addAuth(request);
-    request.headers.addAll(userAgentHeader());
+    request.headers.addAll(_userAgentHeader);
     if (overrideUserAgent != null) {
       request.headers['User-Agent'] = overrideUserAgent;
     }
@@ -213,13 +220,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

@@ -7,6 +7,7 @@ import 'package:package_info_plus/package_info_plus.dart' as package_info_plus;
 import 'package:url_launcher/url_launcher.dart' as url_launcher;
 
 import '../host/android_notifications.dart';
+import '../log.dart';
 import '../widgets/store.dart';
 import 'store.dart';
 
@@ -131,6 +132,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 +147,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 +176,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;
@@ -189,6 +259,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;
@@ -200,9 +273,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(),
     };
   }
 
@@ -266,4 +346,43 @@ class LiveZulipBinding extends ZulipBinding {
 
   @override
   AndroidNotificationHostApi get androidNotificationHost => AndroidNotificationHostApi();
+
+  @override
+  Map<String, String> userAgentHeader() {
+    if (deviceInfo == null || packageInfo == null) {
+      debugLog('userAgentHeader: Dependencies not initialized, falling back to \'ZulipFlutter\'.');
+      return {'User-Agent': 'ZulipFlutter'}; // TODO(log)
+    }
+    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

@@ -1308,7 +1308,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);