Update Rust module documentation #2050

kazimuth · 2024-12-10T21:39:58Z

Description of Changes

While I'm rewriting the reference, I figured I'd do this as well.

Expected complexity level and risk

0

Testing

Added doctests

More docs One more patch More table docs More docs Denser sats comments Move comments More doc rewriting Substantial rewrite of main doc slug More links and emphasis Hmm Document macros inline in the bindings crate to make links better Fix some errors in rust module bindings docs + work on schedule documentation Table macro docs polish A day of writing

kazimuth · 2025-01-15T18:11:58Z

There are still a number of doctest failures that need to be fixed, and some warnings in upstream crates of bindings as well, but I'm opening this up for textual review now.

kazimuth · 2025-01-16T15:50:35Z

crates/bindings/README.md

@@ -0,0 +1,517 @@
+# SpacetimeDB Rust Module Library


I recommend reviewing starting here

gefjon

This is great stuff, thanks!

gefjon · 2025-01-17T16:17:43Z

crates/bindings/README.md

+            but *are* resolved when compiled by Rustdoc.
+-->
+
+[SpacetimeDB](https://spacetimedb.com/) allows using the Rust language to write server-side applications called **modules**. Modules run **inside** a SQL database. They have direct access to database tables, and expose public functions called **reducers** that can be invoked over the network. Clients connect directly to the database to read data.


Suggested change

[SpacetimeDB](https://spacetimedb.com/) allows using the Rust language to write server-side applications called **modules**. Modules run **inside** a SQL database. They have direct access to database tables, and expose public functions called **reducers** that can be invoked over the network. Clients connect directly to the database to read data.

[SpacetimeDB](https://spacetimedb.com/) allows using the Rust language to write server-side applications called **modules**. Modules run inside a relational database. They have direct access to database tables, and expose public functions called **reducers** that can be invoked over the network. Clients connect directly to the database to read data.

The defining feature of our DBs are not their SQL handling; modules do not interact with their DBs via SQL.

"inside" is not a vocab word here, and so should not use the same formatting as "modules" and "reducers." I also don't think it needs to be emphasized.

gefjon · 2025-01-17T16:22:28Z

crates/bindings/README.md

+
+Rust modules are written with the the Rust Module Library (this crate). They are built using [cargo](https://doc.rust-lang.org/cargo/) and deployed using the [`spacetime` CLI tool](https://spacetimedb.com/install). Rust modules can import any Rust [crate](https://crates.io/) that supports being compiled to WebAssembly.
+
+(Note: Rust can also be used to write **clients** of SpacetimeDB databases, but this requires using a completely different library, the SpacetimeDB Rust Client SDK. See the documentation on [clients] for more information.)


How does this link work? There's no header or anchor in this file for it to go to, but when I click on it in the GitHub Markdown viewer, somehow it sends me to https://spacetimedb.com/docs/#client .

gefjon · 2025-01-17T16:25:37Z

crates/bindings/README.md

+Created new database with identity: <hex string>
+```
+
+This hex string is the [`Identity`] of the created database. It distinguishes the created database from the other databases running on the SpacetimeDB network.  It is used when administering the module, for example using the [`spacetime logs <DATABASE_IDENTITY>`](#the-log-crate) command. You should save it to a text file so that you can remember it. <!-- TODO: is there a CLI command that says "list all Identities running this version of a module?" -->


is there a CLI command that says "list all Identities running this version of a module?

Nope.

gefjon · 2025-01-17T16:26:34Z

crates/bindings/README.md

+spacetime publish
+```
+
+When you publish your module, a database will be created with the requested tables, and the module will be installed inside it.
+
+The output of `spacetime publish` will end with a line:
+```text
+Created new database with identity: <hex string>
+```
+
+This hex string is the [`Identity`] of the created database. It distinguishes the created database from the other databases running on the SpacetimeDB network.  It is used when administering the module, for example using the [`spacetime logs <DATABASE_IDENTITY>`](#the-log-crate) command. You should save it to a text file so that you can remember it. <!-- TODO: is there a CLI command that says "list all Identities running this version of a module?" -->


I recommend telling readers to name their DBs. "Make sure to write down this hex string!" is pretty terrible compared to "give it a fun name you'll remember! Also, it has this hex string. Anywhere you use the name, you can use the hex string too."

gefjon · 2025-01-17T16:29:08Z

crates/bindings/README.md

+
+Under the hood, SpacetimeDB modules are WebAssembly modules that import a [specific WebAssembly ABI](https://spacetimedb.com/docs/webassembly-abi) and export a small number of special functions. This is automatically configured when you add the `spacetime` crate as a dependency of your application.
+
+The SpacetimeDB host is an application that hosts SpacetimeDB databases. It is [source available](https://github.com/clockworklabs/SpacetimeDB). You can run your own host, or you can upload your module to the public SpacetimeDB network. <!-- TODO: want a link to some dashboard for the public network. --> The network will create a database for you and install your module in it to serve client requests.


Suggested change

The SpacetimeDB host is an application that hosts SpacetimeDB databases. It is [source available](https://github.com/clockworklabs/SpacetimeDB). You can run your own host, or you can upload your module to the public SpacetimeDB network.  The network will create a database for you and install your module in it to serve client requests.

The SpacetimeDB host is an application that hosts SpacetimeDB databases. [Its source code is available](https://github.com/clockworklabs/SpacetimeDB) under [the Business Source License with an Additional Use Grant](https://github.com/clockworklabs/SpacetimeDB/blob/master/LICENSE.txt). You can run your own host, or you can upload your module to the public SpacetimeDB network.  The network will create a database for you and install your module in it to serve client requests.

gefjon · 2025-01-17T17:46:16Z

crates/sats/src/de.rs

@@ -542,7 +542,7 @@ pub trait DeserializeSeed<'de> {
 use crate::de::impls::BorrowedSliceVisitor;
 pub use spacetimedb_bindings_macro::Deserialize;

-/// A **datastructure** that can be deserialized from any data format supported by SATS.
+/// A **data structure** that can be deserialized from any data format supported by the SpacetimeDB Algebraic Type System.


Emphasis is weird and ugly here.

gefjon · 2025-01-17T17:46:31Z

crates/sats/src/ser.rs

+/// Do not manually implement this trait unless you know what you are doing.
+/// Incorrect implementations are safe, but can result in data loss.
+///


Same note about this warning.

gefjon · 2025-01-17T17:47:13Z

crates/sats/src/typespace.rs

+///
+/// Deriving this trait also derives [`Serialize`](crate::ser::Serialize), [`Deserialize`](crate::de::Deserialize),
+/// and [`Debug`](std::fmt::Debug). (There are currently no trait bounds on `SpacetimeType` documenting this fact.)
+/// These traits are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.


Suggested change

/// These traits are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.

/// `Serialize` and `Deserialize` are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.

gefjon · 2025-01-17T17:48:59Z

crates/sats/src/typespace.rs

+/// and [`Debug`](std::fmt::Debug). (There are currently no trait bounds on `SpacetimeType` documenting this fact.)
+/// These traits are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.
+///
+/// Any Rust type implementing `SpacetimeType` can be used in table and reducer declarations. A derive macro is provided, and can be used on both structs and enums:


Can you be more specific? I believe we don't allow tuple structs. I'm not sure whether or not we allow unit structs. I think on enums we only allow unit variants and single-element tuple variants, not struct variants or n-tuple variants. I could be wrong though; you should check.

gefjon · 2025-01-17T17:57:54Z

crates/sats/src/typespace.rs

+///
+/// (Storing collections in rows of a database table is a form of [denormalization](https://en.wikipedia.org/wiki/Denormalization).)
+///
+/// Do not manually implement this trait unless you are VERY sure you know what you're doing. Incorrect implementations can result in data loss!


Same thing about the warning here.

kazimuth mentioned this pull request Dec 10, 2024

Starting work on rust reference clockworklabs/spacetime-docs#114

Open

kazimuth force-pushed the jgilles/rust-docs-update branch from 6137dc2 to 1d89177 Compare December 17, 2024 21:55

kazimuth force-pushed the jgilles/rust-docs-update branch 2 times, most recently from 68c8c19 to 0f1c3df Compare January 10, 2025 19:26

kazimuth added 11 commits January 15, 2025 13:07

WIP editing

854562c

TODO on Identity APIs

6d9c0d4

Update BTreeIndex docs

291051d

Move lifecycle docs to root

ca0a0c6

Move reducer docs again, fix links

410bbe0

Minor crate root edits

11ea687

Reducer commentary

8525b0e

Edits

efd7545

Finish writing docs

e7224ae

Fix links

1256125

kazimuth force-pushed the jgilles/rust-docs-update branch from 09b3a03 to 1256125 Compare January 15, 2025 18:10

kazimuth marked this pull request as ready for review January 15, 2025 18:11

kazimuth added 10 commits January 15, 2025 13:13

Typo

7e0d282

Remove dead docs

be38e13

Typo

8e9368d

Fix outdated API

8a39fe2

More small fixes

97126f0

Add 'Automatic Migrations' section

1ba9878

Think incredibly hard....

88837f4

Weird space

14d5b04

More formatting and spacing, use no_run instead of ignore

379e703

Less passive

f792d8a

kazimuth requested review from gefjon and joshua-spacetime January 15, 2025 19:39

kazimuth removed the request for review from joshua-spacetime January 15, 2025 19:39

kazimuth commented Jan 16, 2025

View reviewed changes

crates/bindings/README.md

@@ -0,0 +1,517 @@

# SpacetimeDB Rust Module Library

Copy link

Contributor Author

kazimuth Jan 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend reviewing starting here

gefjon reviewed Jan 17, 2025

View reviewed changes

bfops added release-any To be landed in any release window no runtime change This change does not affect the final binaries labels Jan 21, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Rust module documentation #2050

Update Rust module documentation #2050

kazimuth commented Dec 10, 2024

kazimuth commented Jan 15, 2025

kazimuth Jan 16, 2025

gefjon left a comment

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

gefjon Jan 17, 2025

	[SpacetimeDB](https://spacetimedb.com/) allows using the Rust language to write server-side applications called modules. Modules run inside a SQL database. They have direct access to database tables, and expose public functions called reducers that can be invoked over the network. Clients connect directly to the database to read data.
	[SpacetimeDB](https://spacetimedb.com/) allows using the Rust language to write server-side applications called modules. Modules run inside a relational database. They have direct access to database tables, and expose public functions called reducers that can be invoked over the network. Clients connect directly to the database to read data.


		Rust modules are written with the the Rust Module Library (this crate). They are built using [cargo](https://doc.rust-lang.org/cargo/) and deployed using the [`spacetime` CLI tool](https://spacetimedb.com/install). Rust modules can import any Rust [crate](https://crates.io/) that supports being compiled to WebAssembly.

		(Note: Rust can also be used to write clients of SpacetimeDB databases, but this requires using a completely different library, the SpacetimeDB Rust Client SDK. See the documentation on [clients] for more information.)


		Under the hood, SpacetimeDB modules are WebAssembly modules that import a [specific WebAssembly ABI](https://spacetimedb.com/docs/webassembly-abi) and export a small number of special functions. This is automatically configured when you add the `spacetime` crate as a dependency of your application.

		The SpacetimeDB host is an application that hosts SpacetimeDB databases. It is [source available](https://github.com/clockworklabs/SpacetimeDB). You can run your own host, or you can upload your module to the public SpacetimeDB network. <!-- TODO: want a link to some dashboard for the public network. --> The network will create a database for you and install your module in it to serve client requests.

	/// These traits are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.
	/// `Serialize` and `Deserialize` are used to convert Rust data structures to other formats, suitable for storing on disk or passing over the network. `Debug` is simply for debugging convenience.

Update Rust module documentation #2050

Are you sure you want to change the base?

Update Rust module documentation #2050

Conversation

kazimuth commented Dec 10, 2024

Description of Changes

Expected complexity level and risk

Testing

kazimuth commented Jan 15, 2025

Choose a reason for hiding this comment

gefjon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment