ci: verify mobile backward compatibility

Co-authored-by: shenlong-tanwen <139912620+shalong-tanwen@users.noreply.github.com>

.github/FUNDING.yml

@@ -1 +0,0 @@
-custom: ['https://buy.immich.app', 'https://immich.store']

.github/workflows/check-openapi.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     paths:
       - 'open-api/**'
+      - 'mobile/lib/utils/openapi_patching.dart'
       - '.github/workflows/check-openapi.yml'
 
 concurrency:
@@ -29,3 +30,35 @@ jobs:
           base: https://raw.githubusercontent.com/${{ github.repository }}/main/open-api/immich-openapi-specs.json
           revision: open-api/immich-openapi-specs.json
           fail-on: ERR
+
+  check-mobile-patches:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Mise
+        uses: immich-app/devtools/actions/use-mise@7b8610a904d57da241e4ddba17fa62b62b15aed4 # use-mise-action-v2.0.2
+        with:
+          github_token: ${{ github.token }}
+
+      - name: Get packages
+        working-directory: ./mobile
+        run: flutter pub get
+
+      - name: Fetch base spec from main
+        run: |
+          curl -fsSL \
+            "https://raw.githubusercontent.com/${{ github.repository }}/main/open-api/immich-openapi-specs.json" \
+            -o /tmp/base-spec.json
+
+      - name: Check newly-required fields have a backward-compat patch
+        working-directory: ./mobile
+        env:
+          OPENAPI_BASE_SPEC: /tmp/base-spec.json
+          OPENAPI_REVISION_SPEC: ../open-api/immich-openapi-specs.json
+        run: flutter test test/openapi_patches_coverage.dart

CODE_OF_CONDUCT.md

@@ -1,134 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation
-in our community a harassment-free experience for everyone, regardless
-of age, body size, visible or invisible disability, ethnicity, sex
-characteristics, gender identity and expression, level of experience,
-education, socio-economic status, nationality, personal appearance,
-race, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open,
-welcoming, diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for
-our community include:
-
-- Demonstrating empathy and kindness toward other people
-- Being respectful of differing opinions, viewpoints, and experiences
-- Giving and gracefully accepting constructive feedback
-- Accepting responsibility and apologizing to those affected by our
-  mistakes, and learning from the experience
-- Focusing on what is best not just for us as individuals, but for the
-  overall community
-
-Examples of unacceptable behavior include:
-
-- The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-- Trolling, insulting or derogatory comments, and personal or
-  political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-- Other conduct which could reasonably be considered inappropriate in
-  a professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our
-standards of acceptable behavior and will take appropriate and fair
-corrective action in response to any behavior that they deem
-inappropriate, threatening, offensive, or harmful.
-
-Community leaders have the right and responsibility to remove, edit,
-or reject comments, commits, code, wiki edits, issues, and other
-contributions that are not aligned to this Code of Conduct, and will
-communicate reasons for moderation decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also
-applies when an individual is officially representing the community in
-public spaces. Examples of representing our community include using an
-official e-mail address, posting via an official social media account,
-or acting as an appointed representative at an online or offline
-event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior
-may be reported to the community leaders responsible for enforcement
-at our Discord channel. All complaints
-will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and
-security of the reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in
-determining the consequences for any action they deem in violation of
-this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior
-deemed unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders,
-providing clarity around the nature of the violation and an
-explanation of why the behavior was inappropriate. A public apology
-may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series
-of actions.
-
-**Consequence**: A warning with consequences for continued
-behavior. No interaction with the people involved, including
-unsolicited interaction with those enforcing the Code of Conduct, for
-a specified period of time. This includes avoiding interactions in
-community spaces as well as external channels like social
-media. Violating these terms may lead to a temporary or permanent ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards,
-including sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or
-public communication with the community for a specified period of
-time. No public or private interaction with the people involved,
-including unsolicited interaction with those enforcing the Code of
-Conduct, is allowed during this period. Violating these terms may lead
-to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of
-community standards, including sustained inappropriate behavior,
-harassment of an individual, or aggression toward or disparagement of
-classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction
-within the community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor
-Covenant][homepage], version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-Community Impact Guidelines were inspired by [Mozilla's code of
-conduct enforcement ladder](https://github.com/mozilla/diversity).
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the
-FAQ at https://www.contributor-covenant.org/faq. Translations are
-available at https://www.contributor-covenant.org/translations.

SECURITY.md

@@ -1,5 +0,0 @@
-# Security Policy
-
-## Reporting a Vulnerability
-
-Please report security issues to `security@immich.app`

mobile/lib/utils/openapi_patching.dart

@@ -1,67 +1,58 @@
+import 'package:flutter/foundation.dart';
 import 'package:openapi/api.dart';
 
-dynamic upgradeDto(dynamic value, String targetType) {
-  switch (targetType) {
-    case 'UserPreferencesResponseDto':
-      if (value is Map) {
-        addDefault(value, 'download.includeEmbeddedVideos', false);
-        addDefault(value, 'folders', FoldersResponse(enabled: false, sidebarWeb: false).toJson());
-        addDefault(value, 'memories', MemoriesResponse(enabled: true, duration: 5).toJson());
-        addDefault(value, 'ratings', RatingsResponse(enabled: false).toJson());
-        addDefault(value, 'people', PeopleResponse(enabled: true, sidebarWeb: false).toJson());
-        addDefault(value, 'tags', TagsResponse(enabled: false, sidebarWeb: false).toJson());
-        addDefault(value, 'sharedLinks', SharedLinksResponse(enabled: true, sidebarWeb: false).toJson());
-        addDefault(value, 'cast', CastResponse(gCastEnabled: false).toJson());
-        addDefault(value, 'albums', {'defaultAssetOrder': 'desc'});
-      }
-      break;
-    case 'ServerConfigDto':
-      if (value is Map) {
-        addDefault(value, 'mapLightStyleUrl', 'https://tiles.immich.cloud/v1/style/light.json');
-        addDefault(value, 'mapDarkStyleUrl', 'https://tiles.immich.cloud/v1/style/dark.json');
-      }
-    case 'UserResponseDto':
-      if (value is Map) {
-        addDefault(value, 'profileChangedAt', DateTime.now().toIso8601String());
-      }
-      break;
-    case 'AssetResponseDto':
-      if (value is Map) {
-        addDefault(value, 'visibility', 'timeline');
-        addDefault(value, 'createdAt', DateTime.now().toIso8601String());
-        addDefault(value, 'isEdited', false);
-      }
-      break;
-    case 'UserAdminResponseDto':
-      if (value is Map) {
-        addDefault(value, 'profileChangedAt', DateTime.now().toIso8601String());
-      }
-      break;
-    case 'LoginResponseDto':
-      if (value is Map) {
-        addDefault(value, 'isOnboarded', false);
-      }
-      break;
-    case 'SyncUserV1':
-      if (value is Map) {
-        addDefault(value, 'profileChangedAt', DateTime.now().toIso8601String());
-        addDefault(value, 'hasProfileImage', false);
-      }
-    case 'SyncAssetV1':
-      if (value is Map) {
-        addDefault(value, 'isEdited', false);
-      }
-    case 'ServerFeaturesDto':
-      if (value is Map) {
-        addDefault(value, 'ocr', false);
-      }
-      break;
-    case 'MemoriesResponse':
-      if (value is Map) {
-        addDefault(value, 'duration', 5);
-      }
-      break;
+abstract interface class _Dynamic {
+  Object? resolve();
+}
+
+class _CurrentTimestamp implements _Dynamic {
+  const _CurrentTimestamp();
+
+  @override
+  Object? resolve() => DateTime.now().toIso8601String();
+}
+
+const _now = _CurrentTimestamp();
+
+@visibleForTesting
+final Map<String, Map<String, Object?>> openApiPatches = {
+  'UserPreferencesResponseDto': {
+    'download.includeEmbeddedVideos': false,
+    'folders': FoldersResponse(enabled: false, sidebarWeb: false).toJson(),
+    'memories': MemoriesResponse(enabled: true, duration: 5).toJson(),
+    'ratings': RatingsResponse(enabled: false).toJson(),
+    'people': PeopleResponse(enabled: true, sidebarWeb: false).toJson(),
+    'tags': TagsResponse(enabled: false, sidebarWeb: false).toJson(),
+    'sharedLinks': SharedLinksResponse(enabled: true, sidebarWeb: false).toJson(),
+    'cast': CastResponse(gCastEnabled: false).toJson(),
+    'albums': {'defaultAssetOrder': 'desc'},
+  },
+  'ServerConfigDto': {
+    'mapLightStyleUrl': 'https://tiles.immich.cloud/v1/style/light.json',
+    'mapDarkStyleUrl': 'https://tiles.immich.cloud/v1/style/dark.json',
+    'minFaces': 3,
+  },
+  'UserResponseDto': {'profileChangedAt': _now},
+  'AssetResponseDto': {'visibility': 'timeline', 'createdAt': _now, 'isEdited': false},
+  'UserAdminResponseDto': {'profileChangedAt': _now},
+  'LoginResponseDto': {'isOnboarded': false},
+  'SyncUserV1': {'profileChangedAt': _now, 'hasProfileImage': false},
+  'SyncAssetV1': {'isEdited': false},
+  'ServerFeaturesDto': {'ocr': false, 'realtimeTranscoding': false},
+  'MemoriesResponse': {'duration': 5},
+};
+
+void upgradeDto(dynamic value, String targetType) {
+  if (value is! Map) {
+    return;
   }
+  final fields = openApiPatches[targetType];
+  if (fields == null) {
+    return;
+  }
+  fields.forEach((key, defaultValue) {
+    addDefault(value, key, defaultValue is _Dynamic ? defaultValue.resolve() : defaultValue);
+  });
 }
 
 addDefault(dynamic value, String keys, dynamic defaultValue) {

mobile/test/openapi_patches_coverage.dart

@@ -0,0 +1,104 @@
+// Intentionally NOT named `*_test.dart`: that suffix makes `flutter test`
+// auto-discover it, which would run it on every mobile PR. This check is only
+// relevant when the OpenAPI spec changes, so the `Check OpenAPI` workflow runs
+// it by explicit path with the spec locations in the environment.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:immich_mobile/utils/openapi_patching.dart';
+
+void main() {
+  test('every newly-required response field has a backward-compat patch', () {
+    final basePath = Platform.environment['OPENAPI_BASE_SPEC'];
+    final revisionPath = Platform.environment['OPENAPI_REVISION_SPEC'];
+    if (basePath == null || revisionPath == null) {
+      markTestSkipped('set OPENAPI_BASE_SPEC and OPENAPI_REVISION_SPEC to run');
+      return;
+    }
+
+    final baseRequired = _requiredBySchema(_loadSpec(basePath));
+    final revisionSpec = _loadSpec(revisionPath);
+    final revisionRequired = _requiredBySchema(revisionSpec);
+    final deserialized = _deserializedSchemas(revisionSpec);
+    final patched = openApiPatches.map((type, fields) => MapEntry(type, fields.keys.toSet()));
+
+    final missing = <String>[];
+    for (final entry in revisionRequired.entries) {
+      if (!deserialized.contains(entry.key)) {
+        continue;
+      }
+      final have = patched[entry.key] ?? const <String>{};
+      final newlyRequired = entry.value.difference(baseRequired[entry.key] ?? const <String>{});
+      for (final field in newlyRequired) {
+        if (!have.contains(field)) {
+          missing.add('${entry.key}.$field');
+        }
+      }
+    }
+    missing.sort();
+
+    expect(
+      missing,
+      isEmpty,
+      reason:
+          'These newly-required fields will be omitted by older servers and trip the generated '
+          'null-assertion.\nAdd a default to openApiPatches in lib/utils/openapi_patching.dart: $missing',
+    );
+  });
+}
+
+Map<String, dynamic> _loadSpec(String path) => jsonDecode(File(path).readAsStringSync()) as Map<String, dynamic>;
+
+Map<String, dynamic> _schemas(Map<String, dynamic> spec) =>
+    ((spec['components'] as Map?)?['schemas'] as Map?)?.cast<String, dynamic>() ?? const {};
+
+Map<String, Set<String>> _requiredBySchema(Map<String, dynamic> spec) {
+  final result = <String, Set<String>>{};
+  _schemas(spec).forEach((name, schema) {
+    final required = (schema as Map)['required'] as List? ?? const [];
+    result[name] = required.cast<String>().toSet();
+  });
+  return result;
+}
+
+Iterable<String> _refsIn(Object? node) sync* {
+  if (node is Map) {
+    if (node[r'$ref'] case final String ref) {
+      yield ref.split('/').last;
+    }
+    for (final value in node.values) {
+      yield* _refsIn(value);
+    }
+  } else if (node is List) {
+    for (final value in node) {
+      yield* _refsIn(value);
+    }
+  }
+}
+
+Set<String> _deserializedSchemas(Map<String, dynamic> spec) {
+  final schemas = _schemas(spec);
+  final reachable = <String>{};
+
+  final queue = <String>[];
+  for (final path in (spec['paths'] as Map?)?.values ?? const []) {
+    if (path is! Map) {
+      continue;
+    }
+    for (final operation in path.values) {
+      if (operation is Map) {
+        queue.addAll(_refsIn(operation['responses']));
+      }
+    }
+  }
+  while (queue.isNotEmpty) {
+    final name = queue.removeLast();
+    if (!schemas.containsKey(name) || !reachable.add(name)) {
+      continue;
+    }
+    queue.addAll(_refsIn(schemas[name]));
+  }
+  return reachable;
+}