Update docs for #[spacetimedb(table)] (#61)

* [bfops/public-tables]: update docs for #[spacetimedb(table)]

* [bfops/public-tables]: review

---------

Co-authored-by: Zeke Foppa <github.com/bfops>

Author: bfops

docs/docs/modules/rust/index.md

@@ -31,7 +31,7 @@ use spacetimedb::{spacetimedb, println};
 // This macro lets us interact with a SpacetimeDB table of Person rows.
 // We can insert and delete into, and query, this table by the collection
 // of functions generated by the macro.
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct Person {
     name: String,
 }
@@ -88,10 +88,12 @@ Now we'll get into details on all the macro APIs SpacetimeDB provides, starting
 
 ### Defining tables
 
-`#[spacetimedb(table)]` takes no further arguments, and is applied to a Rust struct with named fields:
+The `#[spacetimedb(table)]` is applied to a Rust struct with named fields.
+By default, tables are considered **private**. This means that they are only readable by the table owner, and by server module code.
+The `#[spacetimedb(table(public))]` macro makes a table public. **Public** tables are readable by all users, but can still only be modified by your server module code.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Table {
     field1: String,
     field2: u32,
@@ -116,10 +118,10 @@ And common data structures:
 - `Option<T> where T: SpacetimeType`
 - `Vec<T> where T: SpacetimeType`
 
-All `#[spacetimedb(table)]` types are `SpacetimeType`s, and accordingly, all of their fields have to be.
+All `#[spacetimedb(table(...))]` types are `SpacetimeType`s, and accordingly, all of their fields have to be.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct AnotherTable {
     // Fine, some builtin types.
     id: u64,
@@ -151,7 +153,7 @@ enum Serial {
 Once the table is created via the macro, other attributes described below can control more aspects of the table. For instance, a particular column can be indexed, or take on values of an automatically incremented counter. These are described in detail below.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Person {
     #[unique]
     id: u64,
@@ -269,7 +271,7 @@ We'll work off these structs to see what functions SpacetimeDB generates:
 This table has a plain old column.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Ordinary {
     ordinary_field: u64,
 }
@@ -278,7 +280,7 @@ struct Ordinary {
 This table has a unique column. Every row in the `Person` table must have distinct values of the `unique_field` column. Attempting to insert a row with a duplicate value will fail.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Unique {
     // A unique column:
     #[unique]
@@ -291,7 +293,7 @@ This table has an automatically incrementing column. SpacetimeDB automatically p
 Only integer types can be `#[unique]`: `u8`, `u16`, `u32`, `u64`, `u128`, `i8`, `i16`, `i32`, `i64` and `i128`.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Autoinc {
     #[autoinc]
     autoinc_field: u64,
@@ -301,7 +303,7 @@ struct Autoinc {
 These attributes can be combined, to create an automatically assigned ID usable for filtering.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Identity {
     #[autoinc]
     #[unique]
@@ -375,7 +377,7 @@ fn insert_id() {
 Given a table, we can iterate over all the rows in it.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 struct Person {
     #[unique]
     id: u64,

docs/docs/modules/rust/quickstart.md

@@ -6,7 +6,11 @@ A SpacetimeDB module is code that gets compiled to WebAssembly and is uploaded t
 
 Each SpacetimeDB module defines a set of tables and a set of reducers.
 
-Each table is defined as a Rust `struct` annotated with `#[spacetimedb(table)]`, where an instance represents a row, and each field represents a column.
+Each table is defined as a Rust `struct` annotated with `#[spacetimedb(table(...))]`, where an instance represents a row, and each field represents a column.
+By default, tables are **private**. This means that they are only readable by the table owner, and by server module code.
+The `#[spacetimedb(table(public))]` macro makes a table public. **Public** tables are readable by all users, but can still only be modified by your server module code.
+
+_Coming soon: We plan to add much more robust access controls than just `public` or `private`. Stay tuned!_
 
 A reducer is a function which traverses and updates the database. Each reducer call runs in its own transaction, and its updates to the database are only committed if the reducer returns successfully. In Rust, reducers are defined as functions annotated with `#[spacetimedb(reducer)]`, and may return a `Result<()>`, with an `Err` return aborting the transaction.
 
@@ -67,7 +71,7 @@ For each `User`, we'll store their `Identity`, an optional name they can set to
 To `server/src/lib.rs`, add the definition of the table `User`:
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct User {
     #[primarykey]
     identity: Identity,
@@ -81,7 +85,7 @@ For each `Message`, we'll store the `Identity` of the user who sent it, the `Tim
 To `server/src/lib.rs`, add the definition of the table `Message`:
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct Message {
     sender: Identity,
     sent: Timestamp,
@@ -179,7 +183,7 @@ You could extend the validation in `validate_message` in similar ways to `valida
 
 Whenever a client connects, the module will run a special reducer, annotated with `#[spacetimedb(connect)]`, if it's defined. By convention, it's named `identity_connected`. We'll use it to create a `User` record for the client if it doesn't yet exist, and to set its online status.
 
-We'll use `User::filter_by_identity` to look up a `User` row for `ctx.sender`, if one exists. If we find one, we'll use `User::update_by_identity` to overwrite it with a row that has `online: true`. If not, we'll use `User::insert` to insert a new row for our new user. All three of these methods are generated by the `#[spacetimedb(table)]` attribute, with rows and behavior based on the row attributes. `filter_by_identity` returns an `Option<User>`, because the unique constraint from the `#[primarykey]` attribute means there will be either zero or one matching rows. `insert` returns a `Result<(), UniqueConstraintViolation>` because of the same unique constraint; if we want to overwrite a `User` row, we need to do so explicitly using `update_by_identity`.
+We'll use `User::filter_by_identity` to look up a `User` row for `ctx.sender`, if one exists. If we find one, we'll use `User::update_by_identity` to overwrite it with a row that has `online: true`. If not, we'll use `User::insert` to insert a new row for our new user. All three of these methods are generated by the `#[spacetimedb(table(...))]` attribute, with rows and behavior based on the row attributes. `filter_by_identity` returns an `Option<User>`, because the unique constraint from the `#[primarykey]` attribute means there will be either zero or one matching rows. `insert` returns a `Result<(), UniqueConstraintViolation>` because of the same unique constraint; if we want to overwrite a `User` row, we need to do so explicitly using `update_by_identity`.
 
 To `server/src/lib.rs`, add the definition of the connect reducer:
 

docs/docs/unity/part-2a-rust.md

@@ -29,13 +29,13 @@ use spacetimedb::{spacetimedb, Identity, SpacetimeType, ReducerContext};
 use log;
 ```
 
-Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of macros, like `#[spacetimedb(table)]` which you can learn more about in our [Rust module reference](/docs/modules/rust). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table.
+Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of macros, like `#[spacetimedb(table(...))]` which you can learn more about in our [Rust module reference](/docs/modules/rust) (including making your tables `private`!). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table.
 
 **Append to the bottom of lib.rs:**
 
 ```rust
 // We're using this table as a singleton, so there should typically only be one element where the version is 0.
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 #[derive(Clone)]
 pub struct Config {
     #[primarykey]
@@ -44,7 +44,7 @@ pub struct Config {
 }
 ```
 
-Next, we're going to define a new `SpacetimeType` called `StdbVector3` which we're going to use to store positions. The difference between a `#[derive(SpacetimeType)]` and a `#[spacetimedb(table)]` is that tables actually store data, whereas the deriving `SpacetimeType` just allows you to create a new column of that type in a SpacetimeDB table. Therefore, `StdbVector3` is not, itself, a table.
+Next, we're going to define a new `SpacetimeType` called `StdbVector3` which we're going to use to store positions. The difference between a `#[derive(SpacetimeType)]` and a `#[spacetimedb(table(...))]` is that tables actually store data, whereas the deriving `SpacetimeType` just allows you to create a new column of that type in a SpacetimeDB table. Therefore, `StdbVector3` is not, itself, a table.
 
 **Append to the bottom of lib.rs:**
 
@@ -64,7 +64,7 @@ Now we're going to create a table which actually uses the `StdbVector3` that we
 // This stores information related to all entities in our game. In this tutorial
 // all entities must at least have an entity_id, a position, a direction and they
 // must specify whether or not they are moving.
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 #[derive(Clone)]
 pub struct EntityComponent {
     #[primarykey]
@@ -87,7 +87,7 @@ Next, we will define the `PlayerComponent` table. The `PlayerComponent` table is
 // All players have this component and it associates an entity with the user's
 // Identity. It also stores their username and whether or not they're logged in.
 #[derive(Clone)]
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct PlayerComponent {
     // An entity_id that matches an entity_id in the `EntityComponent` table.
     #[primarykey]
@@ -264,7 +264,7 @@ First lets add a new `ChatMessage` table to the SpacetimeDB module. Add the foll
 **Append to the bottom of server/src/lib.rs:**
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct ChatMessage {
     // The primary key for this table will be auto-incremented
     #[primarykey]

docs/docs/unity/part-2b-c-sharp.md

@@ -30,7 +30,7 @@ using SpacetimeDB.Module;
 using static SpacetimeDB.Runtime;
 ```
 
-Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of macros, like `#[spacetimedb(table)]` which you can learn more about in our [C# module reference](/docs/modules/c-sharp). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table.
+Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of attributes, like `[SpacetimeDB.Table]` which you can learn more about in our [C# module reference](/docs/modules/c-sharp). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table.
 
 **Append to the bottom of lib.cs:**
 

docs/docs/unity/part-4.md

@@ -34,7 +34,7 @@ pub enum ResourceNodeType {
     Iron,
 }
 
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 #[derive(Clone)]
 pub struct ResourceNodeComponent {
     #[primarykey]
@@ -48,7 +48,7 @@ pub struct ResourceNodeComponent {
 Because resource nodes never move, the `MobileEntityComponent` is overkill. Instead, we will add a new entity component named `StaticLocationComponent` that only stores the position and rotation.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 #[derive(Clone)]
 pub struct StaticLocationComponent {
     #[primarykey]
@@ -62,7 +62,7 @@ pub struct StaticLocationComponent {
 3. We are also going to add a couple of additional column to our Config table. `map_extents` let's our spawner know where it can spawn the nodes. `num_resource_nodes` is the maximum number of nodes to spawn on the map. Update the config table in lib.rs.
 
 ```rust
-#[spacetimedb(table)]
+#[spacetimedb(table(public))]
 pub struct Config {
     // Config is a global table with a single row. This table will be used to
     // store configuration or global variables