SDK Queuing System #1

Author: SaadArdati

example/lib/main.dart

@@ -11,7 +11,7 @@ void main() async {
     config: CodelesslyConfig(
       authToken: "cSlMIT93cj1lXkBuYk5QNmImSTUsTHw2MDQ4VkdlOCZFLHc7",
       isPreview: kDebugMode,
-      preload: false,
+      preload: true,
     ),
   );
 
@@ -34,7 +34,18 @@ class _MyAppState extends State<MyApp> {
         showPanel: true,
         wrapperBuilder: (context, child) {
           return MaterialApp(
-            home: child,
+            home: Column(
+              children: [
+                ElevatedButton.icon(
+                  onPressed: () {
+                    Codelessly.instance.reset(clearCache: true);
+                  },
+                  icon: const Icon(Icons.refresh),
+                  label: const Text('Reset'),
+                ),
+                if (child != null) child,
+              ],
+            ),
           );
         },
         stories: [
@@ -47,7 +58,8 @@ class _MyAppState extends State<MyApp> {
                     return const CupertinoActivityIndicator();
                   },
                 );
-              }),
+            },
+          ),
           Story(
               name: 'License UI',
               builder: (context) {

example/macos/Runner.xcodeproj/project.pbxproj

@@ -202,7 +202,7 @@
 			isa = PBXProject;
 			attributes = {
 				LastSwiftUpdateCheck = 0920;
-				LastUpgradeCheck = 1300;
+				LastUpgradeCheck = 1430;
 				ORGANIZATIONNAME = "";
 				TargetAttributes = {
 					33CC10EC2044A3C60003C045 = {

example/macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "1300"
+   LastUpgradeVersion = "1430"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"

lib/src/codelessly.dart

@@ -95,16 +95,16 @@ class Codelessly {
   /// when they are triggered.
   final Map<String, CodelesslyFunction> functions = {};
 
-  CodelesslyStatus _status = CodelesslyStatus.empty;
+  CStatus _status = CStatus.empty();
 
   /// Returns the current status of this SDK instance.
-  CodelesslyStatus get status => _status;
+  CStatus get status => _status;
 
-  final StreamController<CodelesslyStatus> _statusStreamController =
-      StreamController.broadcast()..add(CodelesslyStatus.empty);
+  final StreamController<CStatus> _statusStreamController =
+      StreamController.broadcast()..add(CStatus.empty());
 
   /// Returns a stream of status updates for this SDK instance.
-  Stream<CodelesslyStatus> get statusStream => _statusStreamController.stream;
+  Stream<CStatus> get statusStream => _statusStreamController.stream;
 
   LocalStorage get localStorage => dataManager.localStorage;
 
@@ -139,7 +139,7 @@ class Codelessly {
 
     // If the config is not null, update the status to configured.
     if (_config != null) {
-      _updateStatus(CodelesslyStatus.configured);
+      _updateStatus(CStatus.configured());
     }
   }
 
@@ -150,7 +150,7 @@ class Codelessly {
     if (completeDispose) {
       _statusStreamController.close();
     } else {
-      _status = CodelesslyStatus.empty;
+      _status = CStatus.empty();
       _statusStreamController.add(_status);
     }
 
@@ -178,8 +178,8 @@ class Codelessly {
     _templateDataManager?.invalidate('Template');
     _authManager?.invalidate();
 
-    _config = null;
-    _status = CodelesslyStatus.empty;
+    _status =
+        config == null ? CStatus.empty() : CStatus.configured();
     _statusStreamController.add(_status);
 
     if (clearCache) {
@@ -207,7 +207,7 @@ class Codelessly {
 
   /// Internally updates the status of this instance of the SDK and emits a
   /// status update event to the [statusStream].
-  void _updateStatus(CodelesslyStatus status) {
+  void _updateStatus(CStatus status) {
     if (_status == status) {
       return;
     }
@@ -228,7 +228,7 @@ class Codelessly {
   /// [Codelessly] SDK is the global instance rather than a local one, it will
   /// configure and initialize the SDK automatically via its widget's
   /// constructor parameters.
-  CodelesslyStatus configure({
+  CStatus configure({
     CodelesslyConfig? config,
 
     // Optional data and functions.
@@ -249,7 +249,7 @@ class Codelessly {
     );
 
     assert(
-      status == CodelesslyStatus.empty,
+      status == CStatus.empty(),
       'The SDK cannot be configured if it is not idle. '
       'Consider calling [Codelessly.dispose] before reconfiguring.',
     );
@@ -277,7 +277,7 @@ class Codelessly {
     if (functions != null) {
       this.functions.addAll(functions);
     }
-    _updateStatus(CodelesslyStatus.configured);
+    _updateStatus(CStatus.configured());
     return status;
   }
 
@@ -315,7 +315,7 @@ class Codelessly {
         if (exception.layoutID != null) {
           return;
         }
-        _updateStatus(CodelesslyStatus.error);
+        _updateStatus(CStatus.error());
       },
     );
 
@@ -332,7 +332,7 @@ class Codelessly {
   /// [Codelessly] SDK is the global instance rather than a local one, it will
   /// configure and/or initialize the SDK automatically via its widget's
   /// constructor parameters, if specified.
-  Future<CodelesslyStatus> initialize({
+  Future<CStatus> initialize({
     CodelesslyConfig? config,
 
     // Optional data and functions.
@@ -368,7 +368,7 @@ class Codelessly {
       automaticallySendCrashReports: _config!.automaticallySendCrashReports,
     );
     try {
-      _updateStatus(CodelesslyStatus.configured);
+      _updateStatus(CStatus.configured());
 
       // Clean up.
       if (cacheManager != null) _cacheManager?.dispose();
@@ -441,12 +441,14 @@ class Codelessly {
             LocalDataRepository(cacheManager: this.cacheManager),
       );
 
-      _updateStatus(CodelesslyStatus.loading);
+      _updateStatus(CStatus.loading('initialized_managers'));
 
       log('[SDK] [INIT] Initializing cache manager');
       // The cache manager initializes first to load the local cache.
       await this.cacheManager.init();
 
+      _updateStatus(CStatus.loading('initialized_cache'));
+
       // The auth manager initializes second to look up cached auth data
       // from the cache manager. If no auth data is available, it halts the
       // entire process and awaits to authenticate with the server.
@@ -461,6 +463,8 @@ class Codelessly {
         await this.authManager.init();
         _config!.publishSource =
             this.authManager.getBestPublishSource(_config!);
+
+        _updateStatus(CStatus.loading('initialized_auth'));
       } else {
         log('[SDK] [INIT] A slug was provided. Acutely skipping authentication.');
       }
@@ -497,6 +501,8 @@ class Codelessly {
             }
             break;
         }
+
+        _updateStatus(CStatus.loading('initialized_data_managers'));
       } else {
         if (!initializeDataManagers) {
           log(
@@ -523,13 +529,14 @@ class Codelessly {
             this.authManager.authData!.projectId,
           );
         });
+        _updateStatus(CStatus.loading('initialized_slug'));
       }
 
       log('[SDK] [INIT] Codelessly ${_instance == this ? 'global' : 'local'} instance initialization complete.');
 
-      _updateStatus(CodelesslyStatus.loaded);
+      _updateStatus(CStatus.loaded());
     } catch (error, stacktrace) {
-      _updateStatus(CodelesslyStatus.error);
+      _updateStatus(CStatus.error());
       CodelesslyErrorHandler.instance.captureException(
         error,
         stacktrace: stacktrace,

lib/src/codelessly_config.dart

@@ -132,3 +132,35 @@ enum CodelesslyStatus {
   /// The SDK has an error..
   error,
 }
+
+sealed class CStatus {
+  const CStatus();
+
+  factory CStatus.empty() => const CEmpty();
+  factory CStatus.configured() => const CConfigured();
+  factory CStatus.loading(String step) => CLoading(step);
+  factory CStatus.loaded() => const CLoaded();
+  factory CStatus.error() => const CError();
+}
+
+class CEmpty extends CStatus {
+  const CEmpty();
+}
+
+class CConfigured extends CStatus {
+  const CConfigured();
+}
+
+class CLoading extends CStatus {
+  final String step;
+
+  const CLoading(this.step);
+}
+
+class CLoaded extends CStatus {
+  const CLoaded();
+}
+
+class CError extends CStatus {
+  const CError();
+}

lib/src/data/data_manager.dart

@@ -17,6 +17,13 @@ class DataManager {
   /// not need to be initialized again.
   bool initialized = false;
 
+  /// This is set to true once the while loop that processes the
+  /// [_downloadQueue] finishes processing in the initialization of this
+  /// [DataManager].
+  ///
+  /// Queuing is ignored after this is set to true.
+  bool queuingDone = false;
+
   /// The passed config from the SDK.
   final CodelesslyConfig config;
 
@@ -63,6 +70,16 @@ class DataManager {
   /// The slug for the project as defined in the editor's publish settings.
   late String? slug = config.slug;
 
+  /// The download queue holds the list of layout IDs that need to be
+  /// downloaded in order. Tracking this as an external queue allows
+  /// us to interrupt and inject different layouts to prioritize when needed.
+  ///
+  /// Use Case: Config preloading is set to true, but a CodelesslyWidget got
+  /// rendered on the screen with a layoutID specified before preload could
+  /// finish its queue.
+  /// We inject the layoutID at the start of this queue to prioritize it.
+  final List<String> _downloadQueue = [];
+
   /// Creates a new instance of [DataManager] with the given [config].
   DataManager({
     required this.config,
@@ -269,34 +286,20 @@ class DataManager {
       // If a [layoutID] is not specified, then we need to download all layouts
       // in the background.
       if (config.preload) {
-        final preloadFuture = Future(() async {
-          log(
-            '[DataManager] Config preload was specified during init. Downloading ${_publishModel!.updates.layouts.length} layouts...',
-          );
-          for (final String layoutID in _publishModel!.updates.layouts.keys) {
-            log(
-              '[DataManager] \tDownloading layout [$layoutID]...',
-            );
-            await getOrFetchPopulatedLayout(layoutID: layoutID);
-            log(
-              '[DataManager] \tLayout [$layoutID] during init download complete.',
-            );
-          }
+        log('[DataManager] Config preload was specified during init, but a layoutID was not specified. Waiting for all layouts to download...');
+        log('[DataManager] Config preload was specified during init. Downloading ${_publishModel!.updates.layouts.length} layouts as a queue...');
+        _downloadQueue.addAll(_publishModel!.updates.layouts.keys);
+
+        while (_downloadQueue.isNotEmpty) {
+          final String layoutID = _downloadQueue.removeAt(0);
+          log('[DataManager] \tDownloading layout [$layoutID]...');
+          await getOrFetchPopulatedLayout(layoutID: layoutID);
+          log('[DataManager] \tLayout [$layoutID] during init download complete.');
+        }
 
-          log(
-            '[DataManager] All layouts during init download complete.',
-          );
-        });
+        queuingDone = true;
 
-        // Don't await for all the of the layouts to download if the data manager
-        // is initialized with a layoutID. The layoutID should be prioritized
-        // and downloaded first, the rest can be downloaded in the background.
-        if (layoutID == null) {
-          log(
-            '[DataManager] Config preload was specified during init, but a layoutID was not specified. Waiting for all layouts to download...',
-          );
-          await preloadFuture;
-        }
+        log('[DataManager] All layouts during init download complete.');
       }
     }
 
@@ -835,10 +838,36 @@ class DataManager {
     return conditionUpdates;
   }
 
-  /// [layoutID] is the identifier of the layout to be fetched or retrieved.
+  /// Similar to [getOrFetchPopulatedLayout], but utilizes the download queue
+  /// to respect the order of downloads.
+  Future<void> queueLayout({
+    required String layoutID,
+    bool prioritize = false,
+  }) async {
+    if (_publishModel != null && queuingDone) {
+      log('[DataManager] [queueLayout] Download queue is empty. Downloading layout [$layoutID] immediately...');
+      await getOrFetchPopulatedLayout(layoutID: layoutID);
+      log('[DataManager] [queueLayout] Layout [$layoutID] download complete.');
+    } else {
+      if (_downloadQueue.contains(layoutID)) {
+        log('[DataManager] [queueLayout] Layout [$layoutID] is already in the queue. Skipping.');
+        return;
+      }
+
+      if (prioritize) {
+        log('[DataManager] [queueLayout] Prioritizing this layout. Inserting [$layoutID] to the front of the queue.');
+        _downloadQueue.insert(0, layoutID);
+      } else {
+        log('[DataManager] [queueLayout] Adding [$layoutID] to the back of the queue.');
+        _downloadQueue.add(layoutID);
+      }
+    }
+  }
+
+  /// Downloads or looks up the requested [layoutID] along with its associated
+  /// fonts, and emits the updated [_publishModel].
   ///
-  /// Fetches or gets the requested [layoutID] along with its associated fonts,
-  /// and emits the updated [_publishModel].
+  /// [layoutID] is the identifier of the layout to be fetched or retrieved.
   ///
   /// This method first checks if the layout with the given [layoutID] is
   /// already cached.