docs: Update README.md

README.md

@@ -1,10 +1,22 @@
-# `okufs`
+# `oku-fs`
 
 An implementation of the file system used in the Oku browser.
 
-Files and directories are stored as Iroh documents, allowing them to be shared publicly over the mainline DHT or directly between Oku file system nodes.
+Files and directories are stored in replicas implemented as Iroh documents, allowing them to be shared publicly over the mainline DHT or directly between Oku file system nodes.
 
 An Oku file system node consists of three parts:
 - A running Iroh node.
 - Authorship credentials, consisting of a public and private key pair.
-- A mapping of file paths to Iroh document keys.
+- Replicas, which are Iroh documents containing the file system data.
+    - Replicas have a private key that is used for writing, and a public key that is used for reading and sharing (referred to as a 'namespace ID' or 'document ID').
+    - Replicas have entries comprising a key and a value, where the key is a path and the value is a blob of data.
+    - Paths in a replica can be accessed via a prefix string, so only file paths are stored in the replica; directories are inferred from the paths.
+
+Content discovery occurs over [the mainline DHT](https://en.wikipedia.org/wiki/Mainline_DHT). Content discovery happens as follows:
+1. A node has a document ID. It queries the DHT using this document ID.
+    - Any nodes claiming to have the document with this ID have announced themselves in the DHT prior.
+2. The node receives a list of nodes that claim to have the document.
+3. The node asks the nodes in the list for the document's swarm ticket. It stops when it receives a valid swarm ticket.
+4. The node uses the swarm ticket to connect to the document swarm and download the document.
+
+As a reminder, 'documents' are in fact entire replicas, with multiple files and directories. Fetching individual files or directories has not yet been implemented.

src/discovery.rs

@@ -16,6 +16,8 @@ pub const INITIAL_PUBLISH_DELAY: Duration = Duration::from_millis(500);
 
 /// The port used for communication between other Oku filesystem nodes.
 pub const DISCOVERY_PORT: u16 = 4938;
+
+/// The number of parallel announcements to make to the mainline DHT.
 pub const ANNOUNCE_PARALLELISM: usize = 10;
 
 // pub fn announce_dht(

src/error.rs

@@ -12,34 +12,6 @@ pub enum OkuFsError {
     )]
     /// File system entry not found.
     FsEntryNotFound,
-    #[error("File has no name.")]
-    #[diagnostic(
-        code(fs::file_no_name),
-        url(docsrs),
-        help("Please ensure that the file you are trying to create has a name.")
-    )]
-    /// File has no name.
-    FileNoName,
-    #[error("Cannot get lock on file system entry.")]
-    #[diagnostic(code(fs::cannot_get_lock), url(docsrs))]
-    /// Cannot get lock on file system entry.
-    CannotGetLock,
-    #[error("A file already exists at this path.")]
-    #[diagnostic(code(fs::file_already_exists), url(docsrs))]
-    /// A file already exists at this path.
-    FileAlreadyExists,
-    #[error("A directory already exists at this path.")]
-    #[diagnostic(code(fs::directory_already_exists), url(docsrs))]
-    /// A directory already exists at this path.
-    DirectoryAlreadyExists,
-    #[error("Cannot remove a directory that has children.")]
-    #[diagnostic(code(fs::directory_not_empty), url(docsrs))]
-    /// Cannot remove a directory that has children.
-    DirectoryNotEmpty,
-    #[error("File system root has not been loaded.")]
-    #[diagnostic(code(fs::root_not_loaded), url(docsrs))]
-    /// File system root has not been loaded.
-    RootNotLoaded,
 }
 
 #[derive(Error, Debug, Diagnostic)]
@@ -49,10 +21,6 @@ pub enum OkuDiscoveryError {
     #[diagnostic(code(discovery::invalid_hash_and_format), url(docsrs))]
     /// Invalid hash and format.
     InvalidHashAndFormat,
-    #[error("Unable to discover node address for node ID.")]
-    #[diagnostic(code(discovery::node_address_discovery_failed), url(docsrs))]
-    /// Unable to discover node address for node ID.
-    NodeAddressDiscoveryFailed,
     #[error("Unable to find nodes able to satisfy query.")]
     #[diagnostic(code(discovery::no_nodes_found), url(docsrs))]
     /// Unable to find nodes able to satisfy query.

src/fs.rs

@@ -389,8 +389,6 @@ impl OkuFs {
     /// * `partial` - Whether to discover peers who claim to only have a partial copy of the replica.
     ///
     /// * `verified` - Whether to discover peers who have been verified to have the replica.
-    ///
-    /// * `udp_port` - Optionally-specified UDP port to use for querying the mainline DHT.
     pub async fn get_external_replica(
         &self,
         namespace_id: NamespaceId,