update documentation and bump crate versions for release 0.12 (#206)

* update Rust documentation * update client documentation * bump error crate version * bump tcgeneric crate version * bump tc-value crate version * bump tc-transact crate version * bump tc-btree crate version * Cargo.toml * bump tc-tensor crate version * bump tc-math crate version * bump crate version
haydnv · Jan 15, 2023 · af1fc97 · af1fc97
1 parent 8b5ada5
commit af1fc97
Show file tree

Hide file tree

Showing 29 changed files with 139 additions and 80 deletions.
diff --git a/client/docs/conf.py b/client/docs/conf.py
@@ -22,7 +22,7 @@
 author = 'The TinyChain Contributors'
 
 # The full version, including alpha/beta/rc tags
-release = '0.9'
+release = '0.12'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/client/docs/index.rst b/client/docs/index.rst
@@ -7,7 +7,6 @@ Modules
 .. toctree::
    :maxdepth: 3
 
-   app
    btree
    chain
    generic
@@ -24,6 +23,7 @@ Modules
    scalar.number
    scalar.ref
    scalar.value
+   service
    state
    table
    tensor

diff --git a/client/docs/app.rst → client/docs/service.rst b/client/docs/app.rst → client/docs/service.rst
@@ -1,6 +1,6 @@
-:mod:`app`
+:mod:`service`
 ==========================
 
-.. automodule:: tinychain.app
+.. automodule:: tinychain.service
     :members:
     :show-inheritance:
diff --git a/client/setup.cfg b/client/setup.cfg
@@ -1,8 +1,8 @@
 [metadata]
 name = tinychain
-version = 0.11.0
+version = 0.12.0
 author = The TinyChain Contributors
-author_email = haydn@tinychain.net
+author_email = code@tinychain.net
 description = A Python client for TinyChain: http://git.io/JtryR
 keywords = 'distributed cross-service transaction ml platform'
 long_description = file: README.md

diff --git a/host/Cargo.toml b/host/Cargo.toml
@@ -1,9 +1,9 @@
 [package]
 name = "tinychain"
 version = "0.12.0"
-authors = ["haydn@tinychain.net"]
+authors = ["code@tinychain.net"]
 edition = "2021"
-description = "A next-gen database + application server"
+description = "Next-gen cloud service runtime"
 license = "Apache-2.0"
 readme = "../README.md"
 repository = "https://github.com/haydnv/tinychain.git"
@@ -38,21 +38,21 @@ hyper = { version = "0.14", features = ["full"] }
 log = { version = "0.4", features = ["release_max_level_info"] }
 num_cpus = "1.13"
 pin-project = "1.0"
-rjwt = "0.4"
+rjwt = "~0.4.1"
 safecast = "~0.1.2"
 serde = { version = "1.0", features = [] }
 serde_json = { version = "1.0" }
 sha2 = "0.10"
 tbon = "~0.3.5"
-tc-btree = { path = "btree" }
-tc-error = { path = "error" }
-tc-math = { path = "math", optional = true }
-tc-tensor = { path = "tensor", optional = true }
-tc-transact = { path = "transact", features = ["tensor"] }
-tc-value = { path = "value" }
-tc-table = { path = "table" }
-tcgeneric = { path = "generic" }
-tokio = { version = "1.23", features = ["rt-multi-thread", "signal"] }
+tc-btree = "0.8"
+tc-error = "0.7"
+tc-math = { version = "0.7", optional = true}
+tc-tensor = { version = "0.8", optional = true }
+tc-transact = { version = "0.16", features = ["tensor"] }
+tc-value = "0.8"
+tc-table = "0.7"
+tcgeneric = "0.6"
+tokio = { version = "1.24", features = ["rt-multi-thread", "signal"] }
 tokio-util = { version = "0.7", features = ["io"] }
 uuid = "1.1"
 url = { version = "2.2" }
diff --git a/host/btree/Cargo.toml b/host/btree/Cargo.toml
@@ -1,8 +1,8 @@
 [package]
 name = "tc-btree"
 version = "0.8.0"
-authors = ["haydn@tinychain.net"]
-edition = "2018"
+authors = ["code@tinychain.net"]
+edition = "2021"
 description = "TinyChain's BTree collection type"
 license = "Apache-2.0"
 readme = "README.md"
@@ -19,8 +19,8 @@ futures = "0.3"
 log = { version = "0.4", features = ["release_max_level_warn"] }
 num_cpus = "1.13"
 safecast = "0.1"
-tc-error = { path = "../error" }
-tc-transact = { path = "../transact" }
-tc-value = { path = "../value" }
-tcgeneric = { path = "../generic" }
+tc-error = "0.7"
+tc-transact = "0.16"
+tc-value = "0.8"
+tcgeneric = "0.6"
 uuid = { version = "1.2", features=["v4"] }
diff --git a/host/error/Cargo.toml b/host/error/Cargo.toml
@@ -1,15 +1,15 @@
 [package]
 name = "tc-error"
-version = "0.6.0"
-authors = ["haydn@tinychain.net"]
-edition = "2018"
+version = "0.7.0"
+authors = ["code@tinychain.net"]
+edition = "2021"
 description = "TinyChain's generic error struct"
 license = "Apache-2.0"
 repository = "https://github.com/haydnv/tinychain.git"
 readme = "README.md"
 
 keywords = ["tinychain", "error", "service", "mesh"]
-categories = ["data-structures", "rust-patterns"]
+categories = ["rust-patterns"]
 
 [dependencies]
 destream = "0.5"

diff --git a/host/error/src/lib.rs b/host/error/src/lib.rs
@@ -7,6 +7,7 @@ use std::fmt;
 
 use destream::en;
 
+/// A result of type `T`, or a [`TCError`]
 pub type TCResult<T> = Result<T, TCError>;
 
 struct ErrorData {

diff --git a/host/generic/Cargo.toml b/host/generic/Cargo.toml
@@ -1,8 +1,8 @@
 [package]
 name = "tcgeneric"
-version = "0.5.0"
-authors = ["haydn@tinychain.net"]
-edition = "2018"
+version = "0.6.0"
+authors = ["code@tinychain.net"]
+edition = "2021"
 description = "Generic data types used internally by TinyChain. Unstable."
 license = "Apache-2.0"
 readme = "README.md"
@@ -20,5 +20,5 @@ hr-id = { version = "~0.2.1", features=["all"] }
 safecast = "0.1"
 serde = { version = "1.0", features = [] }
 sha2 = "0.10"
-tc-error = { path = "../error" }
+tc-error = "0.7.0"
 uuid = "1.1"
diff --git a/host/math/Cargo.toml b/host/math/Cargo.toml
@@ -1,9 +1,9 @@
 [package]
 name = "tc-math"
-version = "0.6.0"
-authors = ["haydn@tinychain.net"]
-edition = "2018"
-description = "Mathematical algorithms for TinyChain tensors. Unstable."
+version = "0.7.0"
+authors = ["code@tinychain.net"]
+edition = "2021"
+description = "Mathematical algorithms for TinyChain tensors. DEPRECATED."
 license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/haydnv/tinychain.git"
@@ -13,8 +13,8 @@ categories = ["algorithms", "concurrency", "mathematics", "science"]
 
 [dependencies]
 log = { version = "0.4", features = ["release_max_level_warn"] }
-tc-error = { path = "../error" }
-tc-transact = { path = "../transact", features = ["tensor"] }
-tc-value = { path = "../value" }
-tc-tensor = { path = "../tensor" }
-tcgeneric = { path = "../generic" }
+tc-error = "0.7"
+tc-transact = { version = "0.16", features = ["tensor"] }
+tc-value = "0.8"
+tc-tensor = "0.8"
+tcgeneric = "0.6"
diff --git a/host/src/chain/block.rs b/host/src/chain/block.rs
@@ -1,4 +1,4 @@
-//! A [`Chain`] which stores every mutation of its [`Subject`] in a series of `ChainBlock`s.
+//! A `Chain` which stores every mutation of its subject in a series of `ChainBlock`s.
 //!
 //! Each block in the chain begins with the hash of the previous block.
 
@@ -35,7 +35,7 @@ use super::{ChainInstance, Recover, CHAIN};
 
 pub(crate) const HISTORY: Label = label(".history");
 
-/// A [`Chain`] which stores every mutation of its [`Subject`] in a series of `ChainBlock`s
+/// A `Chain` which stores every mutation of its subject in a series of `ChainBlock`s
 #[derive(Clone)]
 pub struct BlockChain<T> {
     subject: T,

diff --git a/host/src/chain/mod.rs b/host/src/chain/mod.rs
@@ -35,8 +35,10 @@ const BLOCK_SIZE: usize = 1_000_000; // TODO: reduce to 4,096
 const CHAIN: Label = label("chain");
 const PREFIX: PathLabel = path_label(&["state", "chain"]);
 
+/// Defines a method to recover the state of this [`Chain`] from a transaction failure.
 #[async_trait]
 pub trait Recover {
+    /// Recover this state after loading, in case the last transaction failed or was interrupted.
     async fn recover(&self, txn: &Txn) -> TCResult<()>;
 }
 
@@ -49,7 +51,7 @@ pub trait ChainInstance<T> {
     /// Append the given PUT op to the latest block in this `Chain`.
     async fn append_put(&self, txn: &Txn, key: Value, value: State) -> TCResult<()>;
 
-    /// Borrow the [`Subject`] of this [`Chain`] immutably.
+    /// Borrow the subject of this [`Chain`].
     fn subject(&self) -> &T;
 }
 
@@ -106,7 +108,7 @@ impl fmt::Display for ChainType {
     }
 }
 
-/// A data structure responsible for maintaining the transactional integrity of its [`Subject`].
+/// A data structure responsible for maintaining the integrity of a mutable subject.
 // TODO: remove the generic type and replace with:
 // enum Chain { Block(BlockChain<Box<dyn Public>>, Sync(SyncChain<Box<dyn Restore>>) }
 #[derive(Clone)]

diff --git a/host/src/cluster/class.rs b/host/src/cluster/class.rs
@@ -1,3 +1,4 @@
+/// A replicated, versioned set of [`InstanceClass`]es
 use std::convert::TryFrom;
 use std::fmt;
 use std::ops::Deref;
@@ -17,6 +18,7 @@ use crate::txn::Txn;
 
 use super::DirItem;
 
+/// A version of a set of [`InstanceClass`]es
 #[derive(Clone)]
 pub struct Version {
     classes: fs::File<Id, InstanceClass>,
@@ -55,6 +57,7 @@ impl fmt::Display for Version {
     }
 }
 
+/// A versioned set of [`InstanceClass`]es
 #[derive(Clone)]
 pub struct Class {
     dir: fs::Dir,

diff --git a/host/src/cluster/dir.rs b/host/src/cluster/dir.rs
@@ -1,3 +1,5 @@
+//! A directory of [`Cluster`]s
+
 use std::collections::BTreeMap;
 use std::convert::TryFrom;
 use std::fmt;
@@ -25,7 +27,7 @@ use crate::txn::{Actor, Txn};
 
 use super::{Class, Cluster, Library, Replica, Schema, Service, REPLICAS};
 
-/// The type of file stored in a [`library`] directory
+/// The type of file stored in a [`Library`] directory
 pub type File = fs::File<VersionNumber, super::library::Version>;
 
 /// The name of the endpoint which lists the names of each entry in a [`Dir`]
@@ -47,13 +49,15 @@ pub trait DirCreateItem<T: DirItem> {
     ) -> TCResult<Cluster<BlockChain<T>>>;
 }
 
+/// Defines methods common to any item in a [`Dir`].
 #[async_trait]
 pub trait DirItem:
     Persist<fs::Dir, Txn = Txn, Schema = ()> + Transact + Clone + Send + Sync
 {
     type Schema;
     type Version;
 
+    /// Create a new [`Self::Version`] of this [`DirItem`].
     async fn create_version(
         &self,
         txn: &Txn,
@@ -62,6 +66,7 @@ pub trait DirItem:
     ) -> TCResult<Self::Version>;
 }
 
+/// An entry in a [`Dir`] of [`Cluster`]s
 #[derive(Clone)]
 pub enum DirEntry<T> {
     Dir(Cluster<Dir<T>>),
@@ -226,13 +231,15 @@ where
     }
 }
 
+/// Defines a method to create a new subdirectory in a [`Dir`].
 #[async_trait]
 impl<T: Send + Sync> DirCreate for Dir<T>
 where
     DirEntry<T>: Clone,
     Cluster<Self>: Clone,
     Self: Persist<fs::Dir, Txn = Txn, Schema = Schema> + Route + fmt::Display,
 {
+    /// Create a new subdirectory in this [`Dir`].
     async fn create_dir(
         &self,
         txn: &Txn,
@@ -266,11 +273,13 @@ where
     }
 }
 
+/// Defines a method to create a new item in this [`Dir`].
 #[async_trait]
 impl<T: DirItem + Route + fmt::Display> DirCreateItem<T> for Dir<T>
 where
     DirEntry<T>: Clone,
 {
+    /// Create a new item in this [`Dir`].
     async fn create_item(
         &self,
         txn: &Txn,

diff --git a/host/src/cluster/library.rs b/host/src/cluster/library.rs
@@ -1,3 +1,5 @@
+//! A replicated, versioned, stateless [`Library`]
+
 use std::convert::{TryFrom, TryInto};
 use std::fmt;
 
@@ -21,6 +23,7 @@ use crate::txn::Txn;
 
 use super::DirItem;
 
+/// A version of a [`Library`]
 #[derive(Clone)]
 pub struct Version {
     lib: Map<Scalar>,
@@ -112,6 +115,7 @@ impl fmt::Display for Version {
     }
 }
 
+/// A versioned collection of [`Scalar`]s
 #[derive(Clone)]
 pub struct Library {
     file: fs::File<VersionNumber, Version>,

diff --git a/host/src/cluster/mod.rs b/host/src/cluster/mod.rs
@@ -49,6 +49,7 @@ pub trait Replica {
     async fn replicate(&self, txn: &Txn, source: Link) -> TCResult<()>;
 }
 
+/// The static configuration of a [`Cluster`]
 #[derive(Clone)]
 pub struct Schema {
     path: TCPathBuf,

diff --git a/host/src/cluster/service.rs b/host/src/cluster/service.rs
@@ -1,3 +1,5 @@
+//! A replicated, versioned [`Service`]
+
 use std::collections::BTreeMap;
 use std::convert::TryFrom;
 use std::fmt;
@@ -25,11 +27,11 @@ use crate::state::{State, ToState};
 use crate::transact::TxnId;
 use crate::txn::Txn;
 
-pub const CHAINS: Label = label("chains");
 pub(super) const SCHEMA: Label = label("schemata");
 
 const ERR_MISSING_LINK: &str = "missing Link for Service version";
 
+/// An attribute of a [`Version`]
 #[derive(Clone)]
 pub enum Attr {
     Chain(Chain<CollectionBase>),
@@ -48,6 +50,7 @@ impl fmt::Display for Attr {
     }
 }
 
+/// A version of a [`Service`]
 #[derive(Clone)]
 pub struct Version {
     path: TCPathBuf,
@@ -247,6 +250,7 @@ impl fmt::Display for Version {
     }
 }
 
+/// A stateful collection of [`Chain`]s and [`Scalar`] methods ([`Attr`]s)
 #[derive(Clone)]
 pub struct Service {
     dir: fs::Dir,