autosync (version 0.2.0)

sync_project: Open files from a project document

Description

Given a sync server URL and a project document ID, opens a persistent connection to the server, syncs the project document over it, and exposes its file tree for opening individual files. A project is an Automerge document with a files map whose keys are file paths and whose values are text objects holding each file's own document ID.

Usage

sync_project(
  url,
  proj_id,
  token = NULL,
  tls = NULL,
  timeout = 5000L,
  files_key = "files"
)

Value

An environment of class "autosync_project" (reference semantics) with the following fields and methods:

doc

The live project document, kept in sync with the server.

conn

The underlying sync_client() connection.

paths()

Current sorted file paths.

doc_id(path)

Resolve a path to its document ID.

open(path)

Open the file's document over the project connection and return its autosync_doc handle. Reuses the connection and any already-open document.

refresh()

Re-resolve the file tree to pick up added or removed files (the project document syncs live, so this just settles pending updates).

close()

Disconnect the project connection.

Arguments

url

WebSocket URL of the sync server (e.g., "ws://localhost:3030/" or "wss://sync.automerge.org/"). Note: trailing slash may be required.

proj_id

Document ID of the project.

token

(optional) JWT (ID token) for authenticated servers. Sent as a Bearer token in the Authorization header of the WebSocket upgrade request.

tls

(optional) for secure wss:// connections to servers with self-signed or custom CA certificates, a TLS configuration object created by nanonext::tls_config().

timeout

Timeout in milliseconds for each receive operation. Default 5000.

files_key

Key of the files map within the project document. Default "files".

Details

Opening a file syncs that file's document over the same connection rather than dialing the server again, so a session reuses a single WebSocket throughout. Call the opened file's $edit() method to edit it live, or use sync_app() for an interactive browser. Call $close() when finished to disconnect.

Examples

if (FALSE) { # interactive()
proj <- sync_project("wss://quarto-hub.com/ws", proj_id, token = sync_token())
proj                                   # prints the file tree
doc <- proj$open("/charlie/index.qmd") # open a file over the connection
doc$edit(at = "text", ext = ".qmd")    # edit it live
proj$close()                           # disconnect when finished
}