fix: update Web Worker example

billiegoose · billiegoose · commit 32b64ca6d7c1 · 2020-02-14T22:51:34.000-05:00
diff --git a/README.md b/README.md
@@ -37,7 +37,6 @@ The following environments are tested in CI and will continue to be supported un
 TODO:
 - [ ] I should probably normalize on timestamps and get rid of the `date` options.
 - [ ] I should probably remove `username`, `password`, `token`, and `oauth2format` and make everyone use `onAuth` callback for that.
-- [ ] Update the WebWorker Guide.
 - [ ] Update the Useful Snippets.
 
 ### Big changes
diff --git a/docs/guide-webworker.md b/docs/guide-webworker.md
@@ -1,12 +1,14 @@
 ---
 id: webworker
-title: WebWorker Guide
-sidebar_label: WebWorker Guide
+title: WebWorker Example
+sidebar_label: WebWorker Example
 ---
 
 While `isomorphic-git` tries not to block the main thread, it still does on occasion.
 This can cause your webapp to stutter or even freeze up briefly!
 To achieve buttery smooth performance, you'll eventually want to move all your `isomorphic-git` usage off of the main thread.
+Actually, you should move all your logic that's not directly responsible for updating the DOM off the main thread.
+That's still a real challenge in 2020, but more and more libraries are appearing to help solve this.
 
 ## Introduction
 
@@ -18,95 +20,19 @@ Technically, this is done using the [structured clone](https://developer.mozilla
 What kinds of Objects can be sent using `postMessage`? Functions cannot. Therefore objects with methods cannot.
 JSON objects can. `Date` objects and `RegExp` objects can. Also `Uint8Array` objects and `Map` objects and `Set` objects.
 So basically the types of objects you can send to a worker are a superset of JSON but a subset of full JavaScript objects.
-For convenience, throughout the rest of this document I will refer to objects that can be serialized via the structured clone algorithm as "cloneable" objects.
 
-Because of foresight and planning, most `isomorphic-git` functions are:
-
-1. async
-2. have a single, cloneable object as their argument.
-
-The plugins (excepting `fs` plugin) also follow this pattern.
-This greatly simplifies the job of mapping `isomorphic-git` calls to a remote procedure call (RPC) API using `postMessage`.
-If you already have a WebWorker in your project and a prefered way to communicating with it, then mapping `isomorphic-git` calls is easy.
-
-If you don't already have a prefered WebWorker RPC solution, then the easiest way is to use the [MagicPortal](https://www.npmjs.com/package/magic-portal) which was designed specifically for `isomorphic-git` so it's a perfect match!
-The examples below will use MagicPortal.
-
-## Implementation
-
-In the main thread, we acquire a proxy isomorphic-git we can use.
-
-```js
-// main.js
-;(async () => {
-  let worker = new Worker("./worker.js")
-
-  const portal = new MagicPortal(worker)
-  // Acquire it from the worker
-  const git = await portal.get('git')
-})();
-```
-
-In the worker, we expose `isomorphic-git` to the main thread.
-
-```js
-// worker.js
-importScripts([
-  "https://isomorphic-git.org/js/browserfs.js",
-  "https://unpkg.com/isomorphic-git",
-  "https://unpkg.com/magic-portal",
-])
-
-BrowserFS.configure({ fs: 'IndexedDB', options: {} }, function (err) {
-  if (err) return console.log(err)
-
-  // Initialize isomorphic-git
-  const fs = BrowserFS.BFSRequire('fs')
-  git.plugins.set('fs', fs)
-
-  // Expose it to the main thread
-  const portal = new MagicPortal(self);
-  portal.set('git', git)
-})
-```
-
-## Plugins
-
-All plugins have to be setup in the worker, because the plugin functions have to live in the same thread as `isomorphic-git`.
-Therefore, if your plugin needs to interact with the main thread, you have to ALSO proxy your plugin!
-
-```js
-// main.js
-const credentialManager = {
-  async fill({ url }) {
-    let username = window.prompt("Username:")
-    let password = window.prompt("Password:")
-    return { username, password }
-  },
-  async approved({ url, auth }) {
-    return
-  },
-  async rejected({ url, auth }) {
-    window.alert('Authentication rejected')
-    return
-  }
-}
-portal.set('credentialManager', credentialManager, {void: ['approved', 'rejected']})
-
-```
-
-```js
-// worker.js
-let credentialManager = await portal.get('credentialManager')
-git.plugins.set('credentialManager', credentialManager)
-```
+If you don't already have a WebWorker RPC solution, then I recommend using [MagicPortal](https://www.npmjs.com/package/magic-portal) (because I wrote it) or [Comlink](https://www.npmjs.com/package/comlink) which is a similar library.
+The example below will use MagicPortal.
 
 ## Example
 
 Here is a complete example that runs git in a WebWorker.
-The worker exposes 'git' to the main thread, and the main thread exposes the 'emitter' and 'credentialManager' plugins (which need access to the DOM) to the worker.
+The worker wraps some git functions and exposes them to the main thread, while the main thread exposes some functions to the worker for use in callbacks like `onProgress`, `onMessage`, and `onAuth`.
 
 Gist: https://gist.github.com/wmhilton/c311070034bc8d99e3e82d97636d0fd8
 
-<iframe src="https://codesandbox.io/embed/kkpx6q162o?fontsize=13&module=%2Fworker.js" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"></iframe>
-
+<iframe
+  src="https://codesandbox.io/embed/magic-portal-with-isomorphic-git-ejdoo?fontsize=14&hidenavigation=1&module=%2Fworker.js&theme=dark"
+  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+  title="isomorphic-git@1.0 in a Worker example"
+  sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"></iframe>
diff --git a/package.json b/package.json
@@ -55,6 +55,7 @@
     "dist/bundle.umd.min.js.map",
     "dist/http.cjs",
     "dist/http.js",
+    "dist/http.umd.min.js",
     "dist/index.cjs",
     "dist/index.d.ts",
     "dist/index.js",
diff --git a/rollup.config.js b/rollup.config.js
@@ -41,11 +41,24 @@ const nodeConfig = (input, output = input) => ({
   ]
 })
 
+// Browser environments that still don't support `import` (Workers and ServiceWorkers)
+const umdConfig = (input, name) => ({
+  input: `src/${input}`,
+  output: [
+    {
+      format: 'umd',
+      name,
+      file: `dist/${path.basename(input, '.js')}.umd.min.js`
+    }
+  ]
+})
+
 export default [
   moduleConfig('index.js'),
   nodeConfig('api/_index.js', 'index.js'),
   moduleConfig('internal-apis.js'),
   nodeConfig('internal-apis.js'),
   nodeConfig('builtin-node/http.js'),
-  moduleConfig('builtin-browser/http.js')
+  moduleConfig('builtin-browser/http.js'),
+  umdConfig('builtin-browser/http.js', 'GitHttp')
 ]
diff --git a/src/api/clone.js b/src/api/clone.js
@@ -14,6 +14,9 @@ import { join } from '../utils/join.js'
  * @param {HttpClient} args.http - an HTTP client
  * @param {ProgressCallback} [args.onProgress] - optional progress event callback
  * @param {MessageCallback} [args.onMessage] - optional message event callback
+ * @param {AuthCallback} [args.onAuth] - optional auth fill callback
+ * @param {AuthSuccessCallback} [args.onAuthSuccess] - optional auth approved callback
+ * @param {AuthFailureCallback} [args.onAuthFailure] - optional auth rejected callback
  * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [required] The [git directory](dir-vs-gitdir.md) path
  * @param {string} args.url - The URL of the remote repository
@@ -54,6 +57,9 @@ export async function clone ({
   http,
   onProgress,
   onMessage,
+  onAuth,
+  onAuthSuccess,
+  onAuthFailure,
   dir,
   gitdir = join(dir, '.git'),
   url,
@@ -87,6 +93,9 @@ export async function clone ({
       http,
       onProgress,
       onMessage,
+      onAuth,
+      onAuthSuccess,
+      onAuthFailure,
       dir,
       gitdir,
       url,
diff --git a/src/commands/clone.js b/src/commands/clone.js
@@ -14,6 +14,9 @@ import { addRemote } from './addRemote.js'
  * @param {HttpClient} args.http
  * @param {ProgressCallback} [args.onProgress]
  * @param {MessageCallback} [args.onMessage]
+ * @param {AuthCallback} [args.onAuth]
+ * @param {AuthSuccessCallback} [args.onAuthSuccess]
+ * @param {AuthFailureCallback} [args.onAuthFailure]
  * @param {string} [args.dir]
  * @param {string} args.gitdir
  * @param {string} args.url
@@ -42,6 +45,9 @@ export async function clone ({
   http,
   onProgress,
   onMessage,
+  onAuth,
+  onAuthSuccess,
+  onAuthFailure,
   dir,
   gitdir,
   url,
@@ -78,6 +84,9 @@ export async function clone ({
     http,
     onProgress,
     onMessage,
+    onAuth,
+    onAuthSuccess,
+    onAuthFailure,
     gitdir,
     noGitSuffix,
     ref,
diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -122,8 +122,8 @@
         "sidebar_label": "Quick Start"
       },
       "webworker": {
-        "title": "WebWorker Guide",
-        "sidebar_label": "WebWorker Guide"
+        "title": "WebWorker Example",
+        "sidebar_label": "WebWorker Example"
       },
       "hashBlob": {
         "title": "hashBlob",
@@ -197,8 +197,8 @@
         "sidebar_label": "onProgress"
       },
       "onSign": {
-        "title": "onSign & onVerify",
-        "sidebar_label": "onSign & onVerify"
+        "title": "onSign",
+        "sidebar_label": "onSign"
       },
       "packObjects": {
         "title": "packObjects",
@@ -272,10 +272,6 @@
         "title": "tag",
         "sidebar_label": "tag"
       },
-      "verify": {
-        "title": "verify",
-        "sidebar_label": "verify"
-      },
       "version": {
         "title": "version",
         "sidebar_label": "version"
diff --git a/website/siteConfig.js b/website/siteConfig.js
@@ -67,7 +67,7 @@ const siteConfig = {
     '/js/object-inspector.min.js',
     '/js/codemirrorify.js',
     { type: 'module', src: '/js/tutorial.js' },
-    '/js/try-it-out-giturl.js',
+    { type: 'module', src: '/js/try-it-out-giturl.js' },
     '//static.getclicky.com/js',
     '/js/analytics.js',
   ],
diff --git a/website/static/css/custom.css b/website/static/css/custom.css
@@ -112,6 +112,9 @@ footer img[src="/img/isomorphic-git-logo.svg"] {
 .try-it-out {
   line-height: 2em;
 }
+.try-it-out h2 {
+  margin-top: 0;
+}
 
 #giturl_branches,
 #giturl_tags {
diff --git a/website/static/js/try-it-out-giturl.js b/website/static/js/try-it-out-giturl.js
@@ -1,3 +1,5 @@
+import http from './http.js'
+
 document.addEventListener('DOMContentLoaded', function listener () {
   document.removeEventListener('DOMContentLoaded', listener)
   let $input = document.getElementById('giturl_input')
@@ -7,7 +9,9 @@ document.addEventListener('DOMContentLoaded', function listener () {
     value = value.replace(/^https?:\/\//, '')
     if (!value.endsWith('.git')) value += '.git'
     let info = await git.getRemoteInfo({
-      url: `https://cors.isomorphic-git.org/${value}`
+      http,
+      url: value,
+      corsProxy: 'https://cors.isomorphic-git.org'
     })
     const limit = 100;
     if (info.refs.tags) {

Original file line number	Diff line number	Diff line change
`@@ -112,6 +112,9 @@ footer img[src="/img/isomorphic-git-logo.svg"] {`
`112`	`112`	`.try-it-out {`
`113`	`113`	`line-height: 2em;`
`114`	`114`	`}`
	`115`	`+.try-it-out h2 {`
	`116`	`+ margin-top: 0;`
	`117`	`+}`
`115`	`118`
`116`	`119`	`#giturl_branches,`
`117`	`120`	`#giturl_tags {`