cordova-app-loader - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

bower.json

 {
   "name": "cordova-app-loadaer",
   "main": "www/lib/CordovaAppLoader.js",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "homepage": "https://github.com/markmarijnissen/cordova-file-cache",
@@ -6,0 +6,0 @@ "authors": [

index.js

@@ -35,2 +35,3 @@ var CordovaFileCache = require('cordova-file-cache');
   this._updateReady = false;
+  this._checkTimeout = options.checkTimeout || 10000;
 }
@@ -91,2 +92,3 @@
       pegasus(self.newManifestUrl).then(checkManifest,reject);
+      setTimeout(function(){reject(new Error('timeout'));},self._checkTimeout);
     }
@@ -93,0 +95,0 @@ });

package.json

 {
   "name": "cordova-app-loader",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cordova App Loader - remote update your cordova app",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -5,7 +5,14 @@ cordova-app-loader
 
-1. Write a `manifest.json` to describe which files your app uses.
-2. Build and deploy your Cordova App.
-3. Update your app. Upload the new `manifest.json` together with the files to a server.
-4. `CordovaAppLoader` will check this `manifest.json`, download new files, and relaunch!
+1. Write a **manifest.json** to describe files of your app.
+2. Use the **manifest.json** to **bootstrap** your app.
+3. Build and deploy your app.
 
+A little later...
+
+1. Upload an update to your server (manifest.json + files)
+2. Use `CordovaAppLoader` to 
+   1. Check the new manifest
+   2. Download files
+   3. Update your app!
+
 Based on [cordova-promise-fs](https://github.com/markmarijnissen/cordova-promise-fs) and [cordova-file-cache](https://github.com/markmarijnissen/cordova-file-cache).
@@ -17,5 +24,5 @@
 
-Download and include [CordovaPromiseFS.js](https://raw.githubusercontent.com/markmarijnissen/cordova-promise-fs/master/dist/CordovaPromiseFS.js) and [CordovaAppLoader.js](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/lib/CordovaAppLoader.js)
+Download and include [CordovaPromiseFS.js](https://raw.githubusercontent.com/markmarijnissen/cordova-promise-fs/master/dist/CordovaPromiseFS.js), [CordovaAppLoader.js](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/lib/CordovaAppLoader.js) and [bootstrap.js](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/bootstrap.js).
 
-With `npm` or `bower`:
+With npm or bower:
 
@@ -41,2 +48,4 @@ ```bash
 
+Or run on your own computer:
+
 ```bash
@@ -51,3 +60,3 @@ git clone [e-mail]:markmarijnissen/cordova-app-loader.git
 
-**Note:** Want to run your own server? Modify `serverRoot` in `www/test/test.js`!
+**Note:** Want to run your own server? Modify `serverRoot` in `www/app.js`!
 
@@ -58,11 +67,13 @@ ## Usage
 
-1. Write `manifest.json` to describe your app files
-2. Add `bootstrap.js` script to your `index.html` to dynamically load JS and CSS.
+1. Write a manifest.json
+2. Add bootstrap.js script to your index.html
 3. Instantiate a `CordovaAppLoader`
-4. Check for updates: Download a new `manifest.json`
-5. Download (only files that have changed!)
-6. Apply update: Store the new manifest and reload page to bootstrap the updated app!
+4. Check for updates
+5. Download new files
+6. Apply update
 
-### Step 1: Write a `manifest.json`
+### Step 1: Write a manifest.json
 
+Describe which files to download and which files to load during bootstrap.
+
 ```javascript
@@ -116,13 +127,12 @@ {
 ```bash
-bin/update-manifest www www/manifest.json
+node bin/update-manifest www www/manifest.json
+node bin/update-manifest [root-directory] [manifest.json]
 ```
 
-It will update file versions (by hashing the content, so only changed files will update).
+It will update the version of only changed files (with a hash of the content).
 
-* `www` is the root directory for the files
-* `www/manifest.json` is the manifest to be updated.
+### Step 2: Add [bootstrap.js](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/bootstrap.js) to your [index.html](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/index.html)
 
+Retrieves manifest.json and dynamically inserts JS/CSS to the current page.
 
-### Step 2: Add [bootstrap.js](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/bootstrap.js) to your [index.html](https://raw.githubusercontent.com/markmarijnissen/cordova-app-loader/master/www/index.html)
-
 ```html
@@ -132,12 +142,9 @@ <script type="text/javascript" timeout="5000" manifest="manifest.json" src="bootstrap.js"></script>
 
-* On the first run, the bootstrap script retrieves `manifest.json` and starts loading JS/CSS in `manifest.load`.
-* The `manifest.json` is stored in localStorage for the second run.
-* If after `timeout` milliseconds `window.BOOTSTRAP_OK` is **not** true, the (corrupt?) manifest in localStorage is destroyed, and the page will reload.
+On the second run, the manifest.json is retrieved from localStorage.
 
-Make sure you set `window.BOOTSTRAP_OK = true` when your app has succesfully loaded!
+If after `timeout` milliseconds `window.BOOTSTRAP_OK` is **not** true, the (corrupt?) manifest in localStorage is destroyed, and the page will reload. So make sure you set `window.BOOTSTRAP_OK = true` when your app has succesfully loaded!
 
-**Tips:**
+**Tip:**
 
-* Bundle a `manifest.json` with your app. This way, your app will also launch when not connected to the internet.
-* When your app is updated, it will write a new `manifest.json` to localStorage. If this update is corrupt, it can safely revert to the bundled `manifest.json`
+Bundle a manifest.json with your app. This way, your app will also launch when not connected to the internet. When your app is updated, it will write a new manifest.json to localStorage. If this update is corrupt, it can safely revert to the bundled manifest.json
 
@@ -152,4 +159,5 @@ ### Step 3: Intialize CordovaAppLoader
   localRoot: 'app',
-  mode: 'mirror',
+  mode: 'mirror',   // use same directories and filenames as in manifest (instead of using a hash)
   cacheBuster: true // make sure we're not downloading cached files.
+  checkTimeout: 10000 // timeout for the "check" function - when you loose internet connection
 });
@@ -162,3 +170,3 @@ ```
 // download manifest from: serverRoot+'manifest.json'
-loader.check().then( ... )  
+loader.check().then(function(updateAvailable) { ... })  
 
@@ -172,3 +180,3 @@ // download from custom url
 
-**Note:** Check returns `true` or `false` when a new version is available. **Only file versions are compared ** - if you change other data (like `manifest.load`) then `manifest.check()` will return `false`!
+**Implementation Note:** Only file versions are compared! If you, for example, update `manifest.load` then the promise will return `false`!
 
@@ -178,11 +186,11 @@ ### Step 5: Download update
 ```javascript
-loader.download(onprogress).then(function(manifest){ ... },function(failedDownloadUrlArray){ ... });
+loader.download(onprogress)
+   .then(function(manifest){ ... },function(failedDownloadUrlArray){ ... });
 ```
 
-**Note:** When downloading, invalid files are deleted first. This invalidates the current manifest. Therefore, the current manifest is removed from localStorage! The app is reverted to "factory settings" (the `manifest.json` that comes bundled with the app).
+**Note:** When downloading, invalid files are deleted first. This invalidates the current manifest. Therefore, the current manifest is removed from localStorage. The app is reverted to "factory settings" (the manifest.json that comes bundled with the app).
 
 ### Step 6: Apply update (reload page to bootstrap new files)
 
-When download is a success, the new manifest can be written to localStorage. 
-When the page is reloaded, it will load the app update.
+This writes the new manifest to localStorage and reloads the page to bootstrap the updated app.
 
@@ -197,9 +205,81 @@ ```javascript
 
-**Note:** CordovaAppLoader changes the `manifest.root` to point to the file cache - otherwise the bootstrap script can't find the downloaded files!
+**Implementation Note:** CordovaAppLoader changes the `manifest.root` to point to your file cache - otherwise the bootstrap script can't find the downloaded files!
 
+## Design Decisions
+
+I want CordovaAppLoader to be fast, responsive, reliable and safe. In order to do this, I've made the following decisions:
+
+### Loading JS/CSS dynamically using bootstrap.js
+
+First, I wanted to download 'index.html' to storage, then redirect the app to this new index.html.
+
+This has a few problems:
+
+* `cordova.js` and plugin javascript cannot be found. 
+* It is hard to include `cordova.js` in the manifest because it is platform specific.
+* It is hard to find all plugin javascript - it is buried in Cordova internals. 
+* Reloading a page costs more time, CPU and memory because cordova plugins are reset.
+
+Dynamically inserting CSS and JS allows you for almost the same freedom in updates, without all these problems.
+
+### Fast, reliable and performant downloads:
+
+* To save bandwidth and time, only files that have changed are downloaded.
+* CordovaPromiseFS limits concurrency (3) to avoid trashing your app.
+* CordovaFileCache will retry the download up to 3 times - each with an increasing timeout.
+* When executing `loader.download()` for the second time, old downloads are aborted.
+* "onprogress" event is called explicitly on every download. 
+
+### Responsive app: Avoid never-resolving promises
+
+`check` and `download` return a promise. These promises should always resolve - i.e. don't wait forever for a "deviceready" or for a "manifest.json" AJAX call to return.
+
+I am assuming the following promises resolve or reject sometime:
+
+* requestFileSystem
+* CordovaPromiseFS methods:
+    * fs.deviceready (Rejected after timeout of 5 seconds).
+    * fs.file() (Relies on `fs.root.getFile`)
+    * fs.dir() (Relies on `fs.root.getDirectory`)
+    * fs.ensure() (Recursively relies on `getDirectory`)
+    * fs.list() (Relies on fs.dir() and `dirReader.readEntries`)
+    * fs.remove() (Relies on `fileEntry.remove`)
+    * fs.download() (Implemented as a concurrency-limited queue, in which failed downloads can re-add themselves to the queue before rejecting the promise, this promise ultimately relies on Cordova's `filetransfer.download()` to resolve the promise)
+
+* XHR-request to fetch manifest.json (Rejected after timeout)
+
+As you see, most methods rely on the succes/error callbacks of native/Cordova methods.
+
+Only for `deviceready` and the XHR-request I've added timeouts to ensure a timely response.
+
+### Offline - when you loose connection.
+
+When using `check`: The XHR will timeout.
+
+When using `download`: I am assuming Cordova will invoke the error callback. The download has a few retry-attempts. If the connetion isn't restored before the last retry-attemt, the download will fail.
+
+### Crashes
+
+The only critical moment is during a download. Old files are removed while new files aren't fully downloaded yet. This makes the current manifest point to missing or corrupt files. Therefore, before downloading, the current manifest is destroyed. 
+
+If the app crashes during a download, it will restart using the original manifest.
+
+### Bugs in the update
+
+* When `BOOTSTRAP_OK` is not set to `true` after a timeout, the app will destroy the current manifest and revert back to the original manifest.
+
+### More to be considered?
+
+Let me know if you find bugs. Report an issue!
+
+
 ## Changelog
 
+### 0.5.0 (15/11/2014)
+
+* Reject XHR-request when checking.
+
 ### 0.4.0 (13/11/2014)
 
-* Changed `manifest.json` format.
+* Changed manifest.json format.
 
@@ -206,0 +286,0 @@ ### 0.3.0 (13/11/2014)

www/broken-url/manifest.json

@@ -16,7 +16,7 @@ {
     "CordovaPromiseFS": {
-      "version": "635bd29385fe6664b1cf86dc16fb3d801aa9461a",
+      "version": "58f3b1d28ea7dda0c1c336360b26f92e3f24731e",
       "filename": "lib/CordovaPromiseFS.js"
     },
     "CordovaAppLoader": {
-      "version": "76f1eecd3887e69d7b08c60be4f14f90069ca8b8",
+      "version": "d6a10cd44da1ac10216593b735d9fe9f8acc22b6",
       "filename": "lib/CordovaAppLoader.js"
@@ -29,3 +29,3 @@ },
     "app": {
-      "version": "8c99369a825644e68e21433d78ed8b396351cc7d",
+      "version": "812c8c5632e276d6456dca04d624200fd1acb6c7",
       "filename": "app.js"
@@ -46,3 +46,3 @@ },
   ],
-  "version": "231d0a27056ae367ba7aa0e2272f115c48e4eeed"
+  "version": "1c0ed311c287e8de55b9f45c1fa0474dae2622c9"
 }

www/lib/CordovaAppLoader.js

@@ -82,2 +82,3 @@ var CordovaAppLoader =
 	  this._updateReady = false;
+	  this._checkTimeout = options.checkTimeout || 10000;
 	}
@@ -138,2 +139,3 @@
 	      pegasus(self.newManifestUrl).then(checkManifest,reject);
+	      setTimeout(function(){reject(new Error('timeout'));},self._checkTimeout);
 	    }
@@ -140,0 +142,0 @@ });

www/manifest.json

@@ -16,7 +16,7 @@ {
     "CordovaPromiseFS": {
-      "version": "635bd29385fe6664b1cf86dc16fb3d801aa9461a",
+      "version": "58f3b1d28ea7dda0c1c336360b26f92e3f24731e",
       "filename": "lib/CordovaPromiseFS.js"
     },
     "CordovaAppLoader": {
-      "version": "76f1eecd3887e69d7b08c60be4f14f90069ca8b8",
+      "version": "d6a10cd44da1ac10216593b735d9fe9f8acc22b6",
       "filename": "lib/CordovaAppLoader.js"
@@ -29,3 +29,3 @@ },
     "app": {
-      "version": "8c99369a825644e68e21433d78ed8b396351cc7d",
+      "version": "812c8c5632e276d6456dca04d624200fd1acb6c7",
       "filename": "app.js"
@@ -47,3 +47,3 @@ },
   ],
-  "version": "d4a957c194b7ecedb47c8422ea2703d2dfff2183"
+  "version": "3feefac61c0663c01c020a34be57fdbc0e9f88bf"
 }

www/slow-download/manifest.json

@@ -16,7 +16,7 @@ {
     "CordovaPromiseFS": {
-      "version": "635bd29385fe6664b1cf86dc16fb3d801aa9461a",
+      "version": "58f3b1d28ea7dda0c1c336360b26f92e3f24731e",
       "filename": "lib/CordovaPromiseFS.js"
     },
     "CordovaAppLoader": {
-      "version": "76f1eecd3887e69d7b08c60be4f14f90069ca8b8",
+      "version": "d6a10cd44da1ac10216593b735d9fe9f8acc22b6",
       "filename": "lib/CordovaAppLoader.js"
@@ -29,3 +29,3 @@ },
     "app": {
-      "version": "8c99369a825644e68e21433d78ed8b396351cc7d",
+      "version": "812c8c5632e276d6456dca04d624200fd1acb6c7",
       "filename": "app.js"
@@ -56,3 +56,3 @@ },
   ],
-  "version": "98c273529ce000f8713a04fdc5704eb0c352e02f"
+  "version": "3e3b4e3cdbd479b804df4bc8d0834ffa3bf1911a"
 }

www/update/manifest.json

@@ -16,7 +16,7 @@ {
     "CordovaPromiseFS": {
-      "version": "635bd29385fe6664b1cf86dc16fb3d801aa9461a",
+      "version": "58f3b1d28ea7dda0c1c336360b26f92e3f24731e",
       "filename": "lib/CordovaPromiseFS.js"
     },
     "CordovaAppLoader": {
-      "version": "76f1eecd3887e69d7b08c60be4f14f90069ca8b8",
+      "version": "d6a10cd44da1ac10216593b735d9fe9f8acc22b6",
       "filename": "lib/CordovaAppLoader.js"
@@ -29,3 +29,3 @@ },
     "app": {
-      "version": "8c99369a825644e68e21433d78ed8b396351cc7d",
+      "version": "812c8c5632e276d6456dca04d624200fd1acb6c7",
       "filename": "app.js"
@@ -56,3 +56,3 @@ },
   ],
-  "version": "9d25453106ad5d3e935ffcd7bc3d8b9460f85c31"
+  "version": "f688fe883d17cd9d7c8c50ebd824b67b173514a5"
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

450099

increased by0.81%

Lines of code

6772

increased by0.06%

Number of lines in readme file

303

increased by35.87%

No dependency changes