api: Embed platform and app info in user-agent

Generate the user-agent using `deviceInfo` and `packageInfo` from
ZulipBinding.

Fixes: #467

Author: rajveermalviya

lib/model/binding.dart

@@ -162,6 +162,9 @@ abstract class ZulipBinding {
   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();
 }
 
@@ -388,14 +391,40 @@ class LiveZulipBinding extends ZulipBinding {
 
   @override
   Map<String, String> userAgentHeader() {
-    return _userAgentHeader ??= buildUserAgentHeader();
+    if (maybeDeviceInfo == null || maybePackageInfo == null) {
+      assert(debugLog('userAgentHeader: Dependencies not initialized, falling back to \'ZulipFlutter\'.'));
+      return {'User-Agent': 'ZulipFlutter'}; // TODO(log)
+    }
+    return _userAgentHeader ??= buildUserAgentHeader(maybeDeviceInfo!, maybePackageInfo!);
   }
 }
 
 @visibleForTesting
-Map<String, String> buildUserAgentHeader() {
+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 {
-    // TODO(#467) include platform, platform version, and app version
-    'User-Agent': 'ZulipFlutter',
+    'User-Agent': 'ZulipFlutter/$version+$buildNumber ($osInfo)',
   };
 }

test/api/core_test.dart

@@ -6,6 +6,7 @@ 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';
@@ -320,6 +321,41 @@ void main() {
       check(st.toString()).contains("distinctivelyNamedFromJson");
     }
   });
+
+  group('ApiConnection user-agent', () {
+    Future<void> checkUserAgent(String expectedUserAgent) async {
+      return FakeApiConnection.with_(account: eg.selfAccount,
+        userAgentHeader: testBinding.userAgentHeader,
+        (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, packageInfo) in testCases) {
+      test('matches $userAgent', () async {
+        testBinding.deviceInfoResult = deviceInfo;
+        testBinding.packageInfoResult = packageInfo;
+        await checkUserAgent(userAgent);
+      });
+    }
+  });
 }
 
 class DistinctiveError extends Error {

test/model/binding.dart

@@ -294,7 +294,7 @@ class TestZulipBinding extends ZulipBinding {
 
   @override
   Map<String, String> userAgentHeader() {
-    return _userAgentHeader ??= buildUserAgentHeader();
+    return _userAgentHeader ??= buildUserAgentHeader(maybeDeviceInfo!, maybePackageInfo!);
   }
 }