No More Collab. Fixes #449

* Fully removes real-time collaboration * URL scheme rewrite
2023-07-06 16:47:50 +02:00
parent 021bf7e9a4
commit fb75ea1a65
45 changed files with 380 additions and 1356 deletions
@@ -0,0 +1,12 @@
+The server API is relatively small. The client primarily communicates with the server for file “CRUD” (Create, Read, Update, Delete) style operations.
+
+Here’s an attempt to document this API:
+
+* `GET /index.json` (when sent with an `Accept: application/json` request header): will return a full listing of all files in your space including meta data like when the file was last modified, as well as permissions. This is primarily for sync purposes with the client. A request sent without the mentioned `Accept` header will redirect to `/` (to better support authentication layers like [Authelia](https://www.authelia.com/)).
+* `GET /*.*`: _Reads_ and returns the content of the file at the given path. This means that if you `GET /index.md` you will receive the content of your `index` page. The `GET` response will have a few additional SB-specific headers:
+  * `X-Last-Modified` as a UNIX timestamp in ms (as coming from `Data.now()`)
+  * `X-Permission`: either `rw` or `ro` which will change whether the editor opens in read-only or regular mode.
+* `PUT /*.*`: The same as `GET` except that it takes the body of the request and _writes_ it a file.
+* `DELETE /*.*`: Again the same, except this will _delete_ the given file.
+* `GET /.client/*`: Retrieve files implementing the client
+* `GET /*` and `GET /`: Anything else (any path without a file extension) will serve the SilverBullet UI HTML.
@@ -3,6 +3,12 @@ release.

 ---

+## Next
+* **Removal of all real-time collaboration features**: this was causing too many edge cases, and complicated the code too much. To simplify the product as well as the code, we completely removed all real-time collaboration features for now. We may introduce this at some point in the future when the demand and focus is there.
+* **Change of APIs**: This is mostly internal, but will likely have effects on the first load after the upgrade: you may see errors or a message around “the path has changed”, or your page may not properly load. Don’t freak out, just reload once or twice and all should resync and be fine. There’s a beginning of documenting the server [[API]] now.
+
+---
+
 ## 0.3.4

 * **Breaking change (for some templates):** Template in various places allowed you to use `{{variables}}` and various handlebars functions. There also used to be a magic `{{page}}` variable that you could use in various places, but not everywhere. This has now been unified. And the magical `{{page}}` now has been replaced with the global `@page` which does not just expose the page’s name, but any page meta data. More information here: [[🔌 Core/Templates@vars]]. You will now get completion for built-in handlebars helpers after typing `{{`.
@@ -18,8 +24,7 @@ release.

 ## 0.3.2

-* **Real-time collaboration support** between clients: Open the same page in multiple windows (browser tabs, mobile devices) and within a few seconds you should get kicked into real-time collaboration mode, showing other participants cursors, selections and edits in real time (Google doc style). This only works when a connection with the server can be established.
-  * This **breaks** existing [[🔌 Collab]] links, since we switched real-time collaboration libraries. We’re still looking at the best way to keep supporting this feature.
+* REMOVED:  **Real-time collaboration support** between clients: Open the same page in multiple windows (browser tabs, mobile devices) and within a few seconds you should get kicked into real-time collaboration mode, showing other participants cursors, selections and edits in real time (Google doc style). This only works when a connection with the server can be established.
 * [[Authentication|Multi-user authentication]]: you can now allow multiple user accounts authenticate, which makes the real-time collaboration support actually useful. This feature is still experimental and will likely evolve over time.
 * Added `spaceIgnore` setting to not sync specific folders or file patterns to the client, see [[SETTINGS]] for documentation
 * Much improved image loading behavior on page (previously scroll bars would jump up and down like a mad person)
@@ -209,7 +214,7 @@ Besides these architectural changes, a few other breaking changes were made to s
 * New `Plugs: Add` command to quickly add a new plug (will create a `PLUGS` page if you don't have one yet).
 * **Paste without formatting**: holding `Shift` while pasting will disable "rich text paste."
 * **New core plug:** [[🔌 Share]] for sharing your pages with the outside work (such as collab, see below).
-* **New plug:** [[🔌 Collab]] for real-time collaboration on your pages.
+* **New plug:** 🔌 Collab for real-time collaboration on your pages.

 ---

@@ -15,7 +15,6 @@ Now that we got that out of the way, let’s have a look at some of SilverBullet
  * Run commands via their keyboard shortcuts, or the **command palette** (triggered with `Cmd-/` or `Ctrl-/` on Linux and Windows).
  * Use [[🔌 Core/Slash Commands|slash commands]] to perform common text editing operations.
 * Provides a platform for [end-user programming](https://www.inkandswitch.com/end-user-programming/) through its support for annotating pages with [[Frontmatter]] and [[🔌 Directive|directives]] (such as [[🔌 Directive/Query|#query]]), making parts of pages _dynamic_.
-* Experimental [[🔌 Collab|real-time collaboration support]].
 * Robust extension mechanism using [[🔌 Plugs]].
 * **Self-hosted**: you own your data. All content is stored as plain files in a folder on disk. Back up, sync, edit, publish, script with any additional tools you like.
 * SilverBullet is [open source, MIT licensed](https://github.com/silverbulletmd/silverbullet) software.
@@ -1,14 +1,7 @@
-/.fs/_plug/*
-  X-Last-Modified: 12345
-  X-Permission: ro
-  access-control-allow-headers: *
-  access-control-allow-methods: GET,POST,PUT,DELETE,OPTIONS
-  access-control-allow-origin: *
-  access-control-expose-headers: *
-/.fs/*
+/*
  X-Last-Modified: 12345
  X-Permission: rw
  access-control-allow-headers: *
-  access-control-allow-methods: GET,POST,PUT,DELETE,OPTIONS
+  access-control-allow-methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
  access-control-allow-origin: *
  access-control-expose-headers: *
@@ -1,5 +1,3 @@
-/.fs   /index.json 200
-/.fs/* /_fs/:splat 200!
-/.fs/* /empty.md   200
+# /.fs     /index.json 200
 /.client/* /_client/:splat 200!
-/*    /_client/index.html 200
+/*         /_client/index.html 200
@@ -1,41 +0,0 @@
---
-type: plug
-repo: https://github.com/silverbulletmd/silverbullet
-share-support: true
---
-
-The Collab plug implements real-time “Google Doc” style collaboration with other SilverBullet users using the [Hocuspocus](https://hocuspocus.dev/) library. It supports:
-
-* Real-time editing
-* Showing other participant’s cursors and selections
-
-The philosophy behind this plug is that by default your data is private and not shared with others. However, there are cases where you would like to collaborate on individual pages. 
-
-Some example use cases:
-
-* Sharing a meeting agenda or meeting notes
-* Writing or editing an article with others
-
-The collab plug allows you to share individual pages. All collaborators will keep their own local copy on disk (which they can back up, and you probably should), but the “source of truth” moves to a central collaboration server. There is one deployed at `wss://collab.silverbullet.md`, but you can also run your own, see [[@deploy|the instructions below]]. The collab plugin leverages SB’s [[🔌 Share]] infrastructure.
-
-To use it:
-
-1. Open a page you would like to collaborate on
-2. Run the {[Share: Collab]} command and select the collab server to use (an open one runs at `wss://collab.silverbullet.md`)
-3. Copy & paste the `collab:...` URI that is injected into the `$share` [[Frontmatter]] and send to a collaborator **or** if your collaborator is not (yet) a SilverBullet user, you can use the silverbullet.md website (which is an SB instance) directly via the `https://silverbullet.md/collab:...` URL scheme.
-4. If your collaborator is an SB user, have them use the {[Share: Join Collab]} command, or directly open the `collab:...` URI as a page in SilverBullet (both do the same).
-5. If the collaborator wants to keep a persistent copy of the page collaborated page, they can simply _rename_ the page to something not prefixed with `collab:`. Everything will keep working for as long as the `collab:` will appear in the `$share` attribute of [[Frontmatter]]
-
-## How it works
-The Collab plug uses Hocuspocus for real-time collaboration via a WebSocket. A random ID is assigned to every shared page, and a copy of this page (as well as its history) will be stored on the collaboration server. Therefore, be cautious about what you share, especially when using a public collab server like `collab.silverbullet.md`. For “production use” we recommend deploying your own collab server.
-
-## Deploying your own collab server
-$deploy
-
-Collaboration uses the excellent Hocuspocus library. You can easily deploy your own collaboration server as follows (requires node.js and npm):
-
-```shell
-npx @hocuspocus/cli@2.0.6 --sqlite documents.db --port 1337
-```
-
-This will run the hocuspocus server on port 1337, and store page data persistently in a SQLite database `documents.db`. You can connect to this server via `ws://ip:1337`. To use SSL, put a TLS terminator in front of it, in which case you can use `wss://` instead.