braidfs 0.0.54 → 0.0.56

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
 
@@ -14,10 +51,10 @@ npm install -g braidfs
 
 ## Usage
 
-To start the braidfs server:
+To start the braidfs daemon:
 
 ```
-braidfs serve
+braidfs run
 ```
 
 To sync a URL:
@@ -37,45 +74,31 @@ To unsync a URL:
 braidfs unsync <url>
 ```
 
-## Accessing the Server
-
-The braidfs server runs on `http://localhost:10000` by default and provides the following endpoints:
-
-- `/<url>`: Synchronizes the specified URL: creates a local file, and provides a Braid-HTTP interface
-- `/.braidfs/config`: Displays the current configuration
-- `/.braidfs/errors`: Shows the error log
-
-Accessing a URL through the proxy (e.g., `http://localhost:10000/https://example.com/file.txt`) will automatically add it to the set of synced URLs, similar to using `braidfs sync <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:
 
-- `port`: The port number for the proxy server (default: 10000)
-- `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
 {
-  "port": 10000,
   "sync": {
     "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,14 +23,25 @@ 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 = {
-        port: 10000,
         sync: {},
-        domains: { 'example.com': { auth_headers: { Cookie: "secret_pass" } } },
+        cookies: { 'example.com': 'secret_pass' },
+        port: 45678,
         scan_interval_ms: 1000 * 20,
     }
     require('fs').mkdirSync(braidfs_config_dir, { recursive: true })
@@ -43,10 +54,10 @@ require('fs').mkdirSync(temp_folder, { recursive: true })
 
 // process command line args
 let to_run_in_background = process.platform === 'darwin' ? `
-To run server in background:
-    launchctl submit -l org.braid.braidfs -- braidfs serve` : ''
+To run daemon in background:
+    launchctl submit -l org.braid.braidfs -- braidfs run` : ''
 let argv = process.argv.slice(2)
-if (argv.length === 1 && argv[0] === 'serve') {
+if (argv.length === 1 && argv[0].match(/^(run|serve)$/)) {
     return main()
 } else if (argv.length && argv.length % 2 == 0 && argv.every((x, i) => i % 2 != 0 || x.match(/^(sync|unsync)$/))) {
     let operations = []
@@ -71,13 +82,13 @@ if (argv.length === 1 && argv[0] === 'serve') {
         }).then(() => console.log(`${operation}ed: ${url}`))
     )).then(() => console.log('All operations completed successfully.'))
         .catch(() => {
-            return console.log(`The braidfs server does not appear to be running.
+            return console.log(`The braidfs daemon does not appear to be running.
 You can run it with:
-    braidfs serve${to_run_in_background}`)
+    braidfs run${to_run_in_background}`)
         })
 } else {
     return console.log(`Usage:
-    braidfs serve
+    braidfs run
     braidfs sync <URL>
     braidfs unsync <URL>${to_run_in_background}`)
 }
@@ -106,7 +117,7 @@ async function main() {
 
         braid_text.serve(req, res, { key: normalize_url(url) })
     }).listen(config.port, () => {
-        console.log(`server started on port ${config.port}`)
+        console.log(`daemon started on port ${config.port}`)
         if (!config.allow_remote_access) console.log('!! only accessible from localhost !!')
 
         proxy_url('.braidfs/config').then(() => {
@@ -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))
@@ -159,7 +170,7 @@ async function main() {
         watch_files()
         setTimeout(scan_files, 1200)
     }).on('error', e => {
-        if (e.code === 'EADDRINUSE') return console.log(`server already running on port ${config.port}`)
+        if (e.code === 'EADDRINUSE') return console.log(`port ${config.port} is in use`)
         throw e
     })
 }
@@ -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,
@@ -542,7 +553,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 +605,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.54",
+  "version": "0.0.56",
   "description": "braid technology synchronizing files and webpages",
   "author": "Braid Working Group",
   "repository": "braid-org/braidfs",