Merge pull request #618 from appwrite/feat-os-flutter

Update Flutter SDK to add offline support

Author: lohanidamodar

CONTRIBUTING.md

@@ -115,7 +115,7 @@ sdk-generator/blob/master/example.php:
 Run the following command (make sure you have an updated docker version on your machine):
 
 ```bash
-docker run --rm -v $(pwd):/app -w /app php:7.4-cli php example.php
+docker run --rm -v $(pwd):/app -w /app php:8.1-cli php example.php
 ```
 
 >Note: You can just add the new language next to the other languages in the `example.php` file. You don't need to rewrite the file completely.
@@ -252,7 +252,7 @@ Also in `.travis.yml` add new env `SDK=[Language]` so that travis will run a tes
 
 Finally, you can run tests using:
 ```sh
-docker run --rm -v $(pwd):$(pwd):rw -w $(pwd) -v /var/run/docker.sock:/var/run/docker.sock  php:7.4-cli-alpine sh -c "apk add docker-cli && vendor/bin/phpunit"
+docker run --rm -v $(pwd):$(pwd):rw -w $(pwd) -v /var/run/docker.sock:/var/run/docker.sock  php:8.1-cli-alpine sh -c "apk add docker-cli && vendor/bin/phpunit"
 ```
 
 ## SDK Generator Interface

src/SDK/Language/Flutter.php

@@ -205,6 +205,16 @@ public function getFiles(): array
                 'destination'   => '/lib/src/interceptor.dart',
                 'template'      => 'flutter/lib/src/interceptor.dart.twig',
             ],
+            [
+                'scope'         => 'default',
+                'destination'   => '/lib/src/offline_db.dart',
+                'template'      => 'flutter/lib/src/offline_db.dart.twig',
+            ],
+            [
+                'scope'         => 'default',
+                'destination'   => '/lib/src/client_offline_mixin.dart',
+                'template'      => 'flutter/lib/src/client_offline_mixin.dart.twig',
+            ],
             [
                 'scope'         => 'default',
                 'destination'   => '/lib/{{ language.params.packageName }}.dart',

src/Spec/Swagger2.php

@@ -184,6 +184,11 @@ public function getMethods($service)
                             'query' => [],
                             'body' => [],
                         ],
+                        'offline' => [
+                            'model' => $method['x-appwrite']['offline-model'] ?? '',
+                            'key' => $method['x-appwrite']['offline-key'] ?? '',
+                            'response-key' => $method['x-appwrite']['offline-response-key'] ?? '$id',
+                        ],
                         'emptyResponse' => $emptyResponse,
                         'responseModel' => $responseModel,
                     ];

templates/dart/lib/id.dart.twig

@@ -1,13 +1,40 @@
 part of {{ language.params.packageName }};
 
 class ID {
-    ID._();
-    
-    static String unique() {
-        return 'unique()';
-    }
+  ID._();
+
+  // Generate a unique ID based on timestamp
+  // Recreated from https://www.php.net/manual/en/function.uniqid.php
+  static String _uniqid() {
+    final now = DateTime.now();
+    final secondsSinceEpoch = (now.millisecondsSinceEpoch / 1000).floor();
+    final msecs = now.microsecondsSinceEpoch - secondsSinceEpoch * 1000000;
+    return secondsSinceEpoch.toRadixString(16) +
+        msecs.toRadixString(16).padLeft(5, '0');
+  }
+
+  // Generate a unique ID with padding to have a longer ID
+  // Recreated from https://github.com/utopia-php/database/blob/main/src/Database/ID.php#L13
+  static String _unique({int padding = 7}) {
+    String id = _uniqid();
+
+    if (padding > 0) {
+      StringBuffer sb = StringBuffer();
+      for (var i = 0; i < padding; i++) {
+        sb.write(Random().nextInt(16).toRadixString(16));
+      }
 
-    static String custom(String id) {
-        return id;
+      id += sb.toString();
     }
-}
+
+    return id;
+  }
+
+  static String unique() {
+    return _unique();
+  }
+
+  static String custom(String id) {
+    return id;
+  }
+}

templates/dart/lib/package.dart.twig

@@ -1,6 +1,7 @@
 library {{ language.params.packageName }};
 
 import 'dart:async';
+import 'dart:math';
 import 'dart:typed_data';
 
 import 'src/enums.dart';

templates/flutter/base/requests/api.twig

@@ -8,6 +8,20 @@
             {{~ utils.map_headers(method.headers) }}
         };
 
-        final res = await client.call(HttpMethod.{{ method.method | caseLower }}, path: path, params: params, headers: headers);
+        final cacheModel = '{{method['offline']['model']}}'{% if method['offline']['model'] is not empty %}{% for parameter in method.parameters.path %}.replaceAll('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | caseCamel | overrideIdentifier }}){% endfor %}{% endif %};
+        final cacheKey = {% if method['offline']['key'] starts with '{' and method['offline']['key'] ends with '}' %}{{method['offline']['key'] | replace({'{': '', '}': ''}) | overrideIdentifier }}{% else %}'{{method['offline']['key']}}'{% endif %};
+        final cacheResponseIdKey = '{{method['offline']['response-key'] | escapeDollarSign}}';
+        final cacheResponseContainerKey = '{% for property in spec.definitions[method.responseModel].properties %}{% if property.sub_schema and property.type == 'array' %}{{property.name}}{% endif %}{% endfor %}';
+
+        final res = await client.call(
+            HttpMethod.{{ method.method | caseLower }},
+            path: path,
+            params: params,
+            headers: headers,
+            cacheModel: cacheModel,
+            cacheKey: cacheKey,
+            cacheResponseIdKey: cacheResponseIdKey,
+            cacheResponseContainerKey: cacheResponseContainerKey,
+        );
 
         return {% if method.responseModel and method.responseModel != 'any' %}models.{{method.responseModel | caseUcfirst | overrideIdentifier}}.fromMap(res.data){% else %} res.data{% endif %};

templates/flutter/example/pubspec.yaml.twig

@@ -1,3 +1,3 @@
 name: {{ language.params.packageName }}_example
 environment:
-  sdk: '>=2.17.0 <3.0.0'
+  sdk: ">=2.17.0 <3.0.0"

templates/flutter/lib/package.dart.twig

@@ -1,26 +1,27 @@
 library {{ language.params.packageName }};
 
 import 'dart:async';
+import 'dart:math';
 import 'dart:typed_data';
 import 'src/enums.dart';
 import 'src/service.dart';
 import 'src/input_file.dart';
 import 'models.dart' as models;
 import 'src/upload_progress.dart';
 
-export 'src/response.dart';
 export 'src/client.dart';
 export 'src/exception.dart';
+export 'src/input_file.dart';
 export 'src/realtime.dart';
-export 'src/upload_progress.dart';
-export 'src/realtime_subscription.dart';
 export 'src/realtime_message.dart';
-export 'src/input_file.dart';
+export 'src/realtime_subscription.dart';
+export 'src/response.dart';
+export 'src/upload_progress.dart';
 
-part 'query.dart';
+part 'id.dart';
 part 'permission.dart';
+part 'query.dart';
 part 'role.dart';
-part 'id.dart';
 {% for service in spec.services %}
 part 'services/{{service.name | caseDash}}.dart';
 {% endfor %}

templates/flutter/lib/src/client.dart.twig

@@ -1,22 +1,23 @@
-import 'enums.dart';
 import 'client_stub.dart'
     if (dart.library.html) 'client_browser.dart'
     if (dart.library.io) 'client_io.dart';
+import 'enums.dart';
 import 'response.dart';
 import 'upload_progress.dart';
 
 abstract class Client {
-  static const int CHUNK_SIZE = 5*1024*1024;
+  static const int CHUNK_SIZE = 5 * 1024 * 1024;
   late Map<String, String> config;
   late String _endPoint;
   late String? _endPointRealtime;
 
   String get endPoint => _endPoint;
   String? get endPointRealtime => _endPointRealtime;
 
-  factory Client(
-          {String endPoint = '{{ spec.endpoint }}',
-          bool selfSigned = false}) =>
+  factory Client({
+    String endPoint = '{{ spec.endpoint }}',
+    bool selfSigned = false,
+  }) =>
       createClient(endPoint: endPoint, selfSigned: selfSigned);
 
   Future webAuth(Uri url, {String? callbackUrlScheme});
@@ -38,17 +39,34 @@ abstract class Client {
 
 {% for header in spec.global.headers %}
 {% if header.description %}
-    /// {{header.description}}
+  /// {{header.description}}
 {% endif %}
   Client set{{header.key | caseUcfirst}}(value);
 {% endfor %}
 
   Client addHeader(String key, String value);
 
-  Future<Response> call(HttpMethod method, {
+  Future<Response> call(
+    HttpMethod method, {
     String path = '',
     Map<String, String> headers = const {},
     Map<String, dynamic> params = const {},
     ResponseType? responseType,
+    String cacheModel = '',
+    String cacheKey = '',
+    String cacheResponseIdKey = '',
+    String cacheResponseContainerKey = '',
+    Map<String, Object?>? previous,
+  });
+
+  Future<Client> setOfflinePersistency({
+    bool status = true,
+    void Function(Object)? onWriteQueueError,
   });
+
+  bool getOfflinePersistency();
+
+  Client setOfflineCacheSize(int kbytes);
+
+  int getOfflineCacheSize();
 }

templates/flutter/lib/src/client_base.dart.twig

@@ -1,16 +1,16 @@
-import 'response.dart';
 import 'client.dart';
 import 'enums.dart';
+import 'response.dart';
 
-abstract class ClientBase implements Client {  
+abstract class ClientBase implements Client {
 {% for header in spec.global.headers %}
 {% if header.description %}
-    /// {{header.description}}
+  /// {{header.description}}
 {% endif %}
   @override
   ClientBase set{{header.key | caseUcfirst}}(value);
-{% endfor %}
 
+{% endfor %}
   @override
   ClientBase setSelfSigned({bool status = true});
 
@@ -30,5 +30,25 @@ abstract class ClientBase implements Client {
     Map<String, String> headers = const {},
     Map<String, dynamic> params = const {},
     ResponseType? responseType,
+    String cacheModel = '',
+    String cacheKey = '',
+    String cacheResponseIdKey = '',
+    String cacheResponseContainerKey = '',
+    Map<String, Object?>? previous,
+  });
+
+  @override
+  Future<ClientBase> setOfflinePersistency({
+    bool status = true,
+    void Function(Object)? onWriteQueueError,
   });
+
+  @override
+  bool getOfflinePersistency();
+
+  @override
+  ClientBase setOfflineCacheSize(int kbytes);
+
+  @override
+  int getOfflineCacheSize();
 }