browser env limit

docs/browser_env.md

@@ -0,0 +1,12 @@
+# Limitations From The Browser Environment
+
+Obsidian desktop is developed by using [Electron](https://www.electronjs.org/). And Obsidian mobile is developed by using [Capacitor](https://capacitorjs.com/)
+
+Technically, the plugin (or any plugin?) runs in the js environment provided by Obsidian. And to support the mobile Obsidian, the plugin is limited to be developed for the browser environment, instead of the Node.js environment.
+
+Then some limitations are applied:
+
+1. [The CORS policy.](./browser_env_cors.md)
+2. [No Node.js environment.](./browser_env_no_nodejs.md)
+3. If the cloud service uses OAuth flow, it needs to support PKCE. More details are [here](./browser_env_oauth2_pkce.md).
+4. [No background running after Obsidian is closes.](./browser_env_no_background_after_closing.md)

docs/browser_env_cors.md

@@ -0,0 +1,21 @@
+# Limitations From The Browser Environment: CORS Issue
+
+The plugin is developed for the browser environment. The "fake" browser behind the scenes also follows CORS policy.
+
+[MDN has a doc about CORS.](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+
+To solve the issue, we have some options:
+
+1. The server side needs to return the header `Access-Control-Allow-Origin` allowing the origins `app://obsidian.md` and `capacitor://localhost` and `http://localhost`. Sometimes in the future, the header `Access-Control-Expose-Headers` with some values being set might be also needed.
+
+   [Here is an example configuration for Amazon S3.](./s3_cors_configure.md)
+
+   However, some cloud services do not allow configuring or exposing these headers. (Notably most public WebDAV services.)
+
+   It's of course possible if the users build the services by themselves.
+
+2. Obsidian implements and exposes a new api helping developers to bypass the CORS policy.
+
+   Currently (as of Feb 2022), an api `request()` indeed exists, but it only deals with text-like data, and does not support binary data or response headers reading yet.
+
+   Because this plugin allows uploading and downloading binary data, so a more feature-rich api is needed.

docs/browser_env_no_background_after_closing.md

@@ -0,0 +1,3 @@
+# Limitations From The Browser Environment: No Background Running After Obsidian Is Closed
+
+The plugin treats Obsidian as a special browser, and is in fact some js codes. So if Obsidian is closed, then the browser environment stops, then the plugin will be stopped.

docs/browser_env_no_nodejs.md

@@ -0,0 +1,9 @@
+# Limitations From The Browser Environment: No Node.js
+
+To support the mobile Obsidian, the plugin is limited to be developed for the browser environment, instead of the Node.js environment.
+
+Many js libraries are designed to work in both the browser and the Node.js environments. But some are not, because the browser doesn't provide the corresponding abilities.
+
+For example, there is a popular npm package [`ssh2-sftp-client`](https://www.npmjs.com/package/ssh2-sftp-client) for SFTP. But it relies on the modules (e.g. `http`) from Node.js which cannot be "translated" to the browser environment. So it's impossible to make this plugin support SFTP. The same status applies to FTP / FTPS.
+
+Likewise, [MEGA](https://mega.nz/) provides a SDK, but the SDK is [for C++ only](https://mega.nz/doc), so it's also impossible to make this plugin support MEGA.

docs/browser_env_oauth2_pkce.md

@@ -0,0 +1,7 @@
+# Limitations From The Browser Environment: OAuth2 PKCE
+
+If the cloud service uses OAuth flow, it needs to support PKCE, because the plugin is released to the public, and no real secrets can be statically kept in the client.
+
+Luckily, Dropbox and OneDrive supports PKCE, making it possible for this plugin to connect to them easily.
+
+Dropbox has an excellent [article](https://dropbox.tech/developers/pkce--what-and-why-) explaining what is and how to use PKCE.