braidfs 0.0.55 → 0.0.57

package/README.md

@@ -1,8 +1,45 @@
-# braidfs
+# BraidFS: Braid your Filesystem with the Web
 
-Sync Braid URLs as files on disk.
+Provides interoperability between **web pages** via http and your **OS filesystem**.
+  - Using collaborative CRDTs and the Braid extensions for HTTP.
 
-Like Dropbox (file sync), plus Google Docs (collaborative editing), all over HTTP.
+The `braidfs` daemon performs bi-directional synchronization between remote Braid-HTTP resources and your local filesystem.
+
+### Web resources map onto your filesystem
+
+It creates a `~/http` folder in your home directory to synchronize webpages with:
+
+```
+~/http/
+  ├── example.com/
+  │   ├── document.html
+  │   ├── notes.md
+  │   └── assets/
+  │       └── style.css
+  └── braid.org/
+      └── meeting-53
+```
+
+
+https://github.com/user-attachments/assets/4fb36208-e0bd-471b-b47b-bbeee20e4f3f
+
+
+
+### Two-way sync edits between files and web
+
+As long as `braidfs` is running, it will keep the file and web resources in
+sync!
+
+ - Edit to the file → web resource
+ - Edit to the web resource → file
+
+Each edit to the file is diffed and sent as a CRDT patch, so you can edit
+files offline, and even collaboratively edit them, with one caveat:
+
+#### Caveat
+
+For the period of time that you have edited the file in your editor but not
+saved it, external edits cannot be integrated.
 
 ## Installation
 
@@ -39,13 +76,13 @@ braidfs unsync <url>
 
 ## Configuration
 
-braidfs looks for a configuration file at `~/http/.braidfs/config`. You can set the following options:
+braidfs looks for a configuration file at `~/http/.braidfs/config`, or creates it if it doesn't exist. You can set the following options:
 
-- `sync`: An object where the keys are URLs to sync, and the values are simply "true"
-- `domains`: An object for setting domain-specific configurations, including authentication headers
+- `sync`: An object where the keys are URLs to sync, and the values are simply `true`
+- `cookies`: An object for setting domain-specific cookies for authentication
 - `port`: The port number for the internal daemon (default: 45678)
 
-Example `config.json`:
+Example `config`:
 
 ```json
 {
@@ -53,19 +90,15 @@ Example `config.json`:
     "https://example.com/document1.txt": true,
     "https://example.com/document2.txt": true
   },
-  "domains": {
-    "example.com": {
-      "auth_headers": {
-        "Cookie": "secret_pass"
-      }
-    }
+  "cookies": {
+    "example.com": "secret_pass"
   },
   "port": 45678
 }
 ```
 
-The `domains` configuration allows you to set authentication headers for specific domains. In the example above, any requests to `example.com` will include the specified `Cookie` header.
+The `cookies` configuration allows you to set authentication cookies for specific domains. In the example above, any requests to `example.com` will include the specified cookie value.
 
 ## Security
 
-braidfs is designed to run locally and only accepts connections from localhost (127.0.0.1 or ::1) for security reasons. The `domains` configuration enables secure communication with servers that require authentication by allowing you to set domain-specific headers.
+braidfs is designed to run locally and only accepts connections from localhost (127.0.0.1 or ::1) for security reasons. The `cookies` configuration enables secure communication with servers that require authentication by allowing you to set domain-specific cookie values.

package/index.js

@@ -23,13 +23,24 @@ var config = null,
 if (require('fs').existsSync(proxy_base)) {
     try {
         config = JSON.parse(require('fs').readFileSync(braidfs_config_file, 'utf8'))
+
+        // for 0.0.55 users upgrading to 0.0.56,
+        // which changes the config "domains" key to "cookies",
+        // and condenses its structure a bit
+        if (config.domains) {
+            config.cookies = Object.fromEntries(Object.entries(config.domains).map(([k, v]) => {
+                if (v.auth_headers?.Cookie) return [k, v.auth_headers.Cookie]
+            }).filter(x => x))
+            delete config.domains
+            require('fs').writeFileSync(braidfs_config_file, JSON.stringify(config, null, 4))
+        }
     } catch (e) {
         return console.log(`Cannot parse the configuration file at: ${braidfs_config_file}`)
     }
 } else {
     config = {
         sync: {},
-        domains: { 'example.com': { auth_headers: { Cookie: "secret_pass" } } },
+        cookies: { 'example.com': 'secret_pass' },
         port: 45678,
         scan_interval_ms: 1000 * 20,
     }
@@ -132,12 +143,12 @@ async function main() {
                         // have the appropriate connections reconnect
                         let changed = new Set()
                         // any old domains no longer exist?
-                        for (let domain of Object.keys(prev.domains ?? {}))
-                            if (!config.domains?.[domain]) changed.add(domain)
+                        for (let domain of Object.keys(prev.cookies ?? {}))
+                            if (!config.cookies?.[domain]) changed.add(domain)
                         // any new domains not like the old?
-                        for (let [domain, v] of Object.entries(config.domains ?? {}))
-                            if (!prev.domains?.[domain]
-                                || JSON.stringify(prev.domains[domain]) !== JSON.stringify(v))
+                        for (let [domain, v] of Object.entries(config.cookies ?? {}))
+                            if (!prev.cookies?.[domain]
+                                || JSON.stringify(prev.cookies[domain]) !== JSON.stringify(v))
                                 changed.add(domain)
                         // ok, have every domain which has changed reconnect
                         for (let [path, x] of Object.entries(proxy_url.cache))
@@ -388,7 +399,7 @@ async function proxy_url(url) {
                         headers: {
                             "Merge-Type": "dt",
                             "Content-Type": 'text/plain',
-                            ...config.domains?.[(new URL(url)).hostname]?.auth_headers,
+                            ...(x => x && {Cookie: x})(config.cookies?.[new URL(url).hostname])
                         },
                         method: "PUT",
                         retry: true,
@@ -488,11 +499,17 @@ async function proxy_url(url) {
                         file_needs_writing = false
                         let { version, body } = await braid_text.get(url, {})
                         if (!v_eq(version, file_last_version)) {
-                            console.log(`writing file ${fullpath}`)
-
-                            // make sure the file has what it had before
+                            // let's do a final check to see if anything has changed
+                            // before writing out a new version of the file
                             let text = await require('fs').promises.readFile(fullpath, { encoding: 'utf8' })
-                            if (self.file_last_text != text) crash(new Error('File changed without us noticing.'))
+                            if (self.file_last_text != text) {
+                                // if the text is different, let's read it first..
+                                file_needs_reading = true
+                                file_needs_writing = true
+                                continue
+                            }
+
+                            console.log(`writing file ${fullpath}`)
 
                             try { if (await is_read_only(fullpath)) await set_read_only(fullpath, false) } catch (e) { }
 
@@ -542,7 +559,7 @@ async function proxy_url(url) {
                 headers: {
                     "Merge-Type": "dt",
                     Accept: 'text/plain',
-                    ...config.domains?.[(new URL(url)).hostname]?.auth_headers,
+                    ...(x => x && {Cookie: x})(config.cookies?.[new URL(url).hostname]),
                 },
                 subscribe: true,
                 retry: {
@@ -594,7 +611,7 @@ async function proxy_url(url) {
                     method: "HEAD",
                     headers: {
                         Accept: 'text/plain',
-                        ...config.domains?.[(new URL(url)).hostname]?.auth_headers,
+                        ...(x => x && {Cookie: x})(config.cookies?.[new URL(url).hostname]),
                     },
                     retry: true
                 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braidfs",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "description": "braid technology synchronizing files and webpages",
   "author": "Braid Working Group",
   "repository": "braid-org/braidfs",