Fixes #41, #220, #235, #239, #244, #246, #248, #257, #266 and #271.

docs/deploying/maincloud.md

@@ -12,6 +12,8 @@ Maincloud is a managed cloud service that provides developers an easy way to dep
 spacetime publish -s maincloud my-cool-module
 ```
 
+`maincloud` is the nickname for the hostname `maincloud.spacetimedb.com`, which is pre-configured in the SpacetimeDB CLI. See [`spacetime server`↴](/docs/cli-reference#spacetime-server) for more information. Use `wss://maincloud.spacetimedb.com` as URI to connect to maincloud from clients.
+
 ## Connecting your Identity to the Web Dashboard
 
 By logging in your CLI via spacetimedb.com, you can view your published modules on the web dashboard.

docs/how-to/incremental-migrations.md

@@ -120,7 +120,7 @@ $ spacetime sql incr-migration-demo 'SELECT * FROM character'
  <snip>    | "Gefjon" | 2     | (Fighter = ()) 
 ```
 
-See [the SATS JSON reference](/docs/sats-json) for more on the encoding of arguments to `spacetime call`.
+See [the SATS JSON reference](/docs/internals/sats-json) for more on the encoding of arguments to `spacetime call`.
 
 Now we want to add a new feature: each player should be able to align themselves with the forces of good or evil, so we can get some healthy competition going between our players. We'll start each character off with `Alliance::Neutral`, and then offer them a reducer `choose_alliance` to set it to either `Alliance::Good` or `Alliance::Evil`. Our first attempt will be to add a new column to the type `Character`:
 

docs/http/database.md

@@ -30,7 +30,7 @@ Accessible through the CLI as `spacetime publish`.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -63,7 +63,7 @@ Accessible through the CLI as `spacetime publish`.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -123,7 +123,7 @@ Accessible through the CLI as `spacetime delete <identity>`.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 ## `GET /v1/database/:name_or_identity/names`
 
@@ -147,7 +147,7 @@ Add a new name for this database.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -180,7 +180,7 @@ Set the list of names for this database.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -224,16 +224,16 @@ For more information about WebSocket headers, see [RFC 6455](https://datatracker
 | `Sec-WebSocket-Version`  | `13`                                                                  |
 | `Sec-WebSocket-Key`      | A 16-byte value, generated randomly by the client, encoded as Base64. |
 
-The SpacetimeDB binary WebSocket protocol, `v1.bsatn.spacetimedb`, encodes messages as well as reducer and row data using [BSATN](/docs/bsatn).
+The SpacetimeDB binary WebSocket protocol, `v1.bsatn.spacetimedb`, encodes messages as well as reducer and row data using [BSATN](/docs/internals/bsatn).
 Its messages are defined [here](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/client-api-messages/src/websocket.rs).
 
-The SpacetimeDB text WebSocket protocol, `v1.json.spacetimedb`, encodes messages according to the [SATS-JSON format](/docs/sats-json).
+The SpacetimeDB text WebSocket protocol, `v1.json.spacetimedb`, encodes messages according to the [SATS-JSON format](/docs/internals/sats-json).
 
 #### Optional Headers
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 ## `POST /v1/database/:name_or_identity/call/:reducer`
 
@@ -249,7 +249,7 @@ Invoke a reducer in a database.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -409,7 +409,7 @@ Accessible through the CLI as `spacetime logs <name_or_identity>`.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Returns
 
@@ -425,7 +425,7 @@ Accessible through the CLI as `spacetime sql <name_or_identity> <query>`.
 
 | Name            | Value                                                                 |
 | --------------- | --------------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [as Bearer auth](/docs/http#authorization-headers). |
+| `Authorization` | A Spacetime token [as Bearer auth](/docs/http/authorization#authorization-headers). |
 
 #### Data
 
@@ -442,6 +442,6 @@ Returns a JSON array of statement results, each of which takes the form:
 }
 ```
 
-The `schema` will be a [JSON-encoded `ProductType`](/docs/sats-json) describing the type of the returned rows.
+The `schema` will be a [JSON-encoded `ProductType`](/docs/internals/sats-json) describing the type of the returned rows.
 
-The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/sats-json), each of which conforms to the `schema`.
+The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/internals/sats-json), each of which conforms to the `schema`.

docs/http/identity.md

@@ -35,7 +35,7 @@ Generate a short-lived access token which can be used in untrusted contexts, e.g
 
 | Name            | Value                                                           |
 | --------------- | --------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). |
+| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). |
 
 #### Returns
 
@@ -77,7 +77,7 @@ Associate an email with a Spacetime identity.
 
 | Name            | Value                                                           |
 | --------------- | --------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). |
+| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). |
 
 ## `GET /v1/identity/:identity/databases`
 
@@ -115,7 +115,7 @@ Verify the validity of an identity/token pair.
 
 | Name            | Value                                                           |
 | --------------- | --------------------------------------------------------------- |
-| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). |
+| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/authorization). |
 
 #### Returns
 

docs/index.md

@@ -75,7 +75,7 @@ A database exports [tables](#table), which store data, and [reducers](#reducer),
 
 A database's schema and business logic is specified by a piece of software called a **module**. Modules can be written in C# or Rust.
 
-(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/docs/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](/install) is used to deploy the application.)
+(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/docs/internals/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](/install) is used to deploy the application.)
 
 ### Table
 A SpacetimeDB **table** is a SQL database table. Tables are declared in a module's native language. For instance, in C#, a table is declared like so:

docs/bsatn.md → docs/internals/bsatn.md

@@ -128,6 +128,6 @@ Where
 All SATS types are BSATN-encoded by converting them to an `AlgebraicValue`,
 then BSATN-encoding that meta-value.
 
-See [the SATN JSON Format](/docs/sats-json)
+See [the SATN JSON Format](/docs/internals/sats-json)
 for more details of the conversion to meta values.
 Note that these meta values are converted to BSATN and _not JSON_.

docs/modules/c-sharp/index.md

@@ -201,7 +201,7 @@ You can also generate code for clients of your module using the `spacetime gener
 
 # How it works
 
-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 `SpacetimeDB.Runtime` package as a dependency of your application.
+Under the hood, SpacetimeDB modules are WebAssembly modules that import a [specific WebAssembly ABI](https://spacetimedb.com/docs/internals/webassembly-abi) and export a small number of special functions. This is automatically configured when you add the `SpacetimeDB.Runtime` package as a dependency of your application.
 
 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. <!-- 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.
 

docs/modules/c-sharp/quickstart.md

@@ -298,7 +298,7 @@ info: Hello, World!
 SpacetimeDB supports a subset of the SQL syntax so that you can easily query the data of your database. We can run a query using the `sql` command.
 
 ```bash
-spacetime sql quickstart-chat "SELECT * FROM Message"
+spacetime sql quickstart-chat "SELECT * FROM message"
 ```
 
 ```bash

docs/modules/index.md

@@ -15,7 +15,7 @@ Rust is the only fully supported language for server modules. Rust is a great op
 
 ### C#
 
-We have C# support available in experimental status. C# can be a good choice for developers who are already using Unity or .net for their client applications.
+We have C# support available. C# can be a good choice for developers who are already using Unity or .net for their client applications.
 
 - [C# Module Reference](/docs/modules/c-sharp)
 - [C# Module Quickstart Guide](/docs/modules/c-sharp/quickstart)

docs/modules/rust/quickstart.md

@@ -224,11 +224,15 @@ pub fn identity_disconnected(ctx: &ReducerContext) {
 }
 ```
 
+## Start the Server
+
+If you haven't already started the SpacetimeDB server, run the `spacetime start` command in a _separate_ terminal and leave it running while you continue following along.
+
 ## Publish the module
 
 And that's all of our module code! We'll run `spacetime publish` to compile our module and publish it on SpacetimeDB. `spacetime publish` takes an optional name which will map to the database's unique `Identity`. Clients can connect either by name or by `Identity`, but names are much more user-friendly. If you'd like, come up with a unique name that contains only URL-safe characters (letters, numbers, hyphens and underscores), and fill it in where we've written `quickstart-chat`.
 
-From the `quickstart-chat` directory, run:
+From the `quickstart-chat` directory, run in another tab:
 
 ```bash
 spacetime publish --project-path server quickstart-chat
@@ -239,7 +243,7 @@ spacetime publish --project-path server quickstart-chat
 You can use the CLI (command line interface) to run reducers. The arguments to the reducer are passed in JSON format.
 
 ```bash
-spacetime call quickstart-chat send_message 'Hello, World!'
+spacetime call quickstart-chat send_message "Hello, World!"
 ```
 
 Once we've called our `send_message` reducer, we can check to make sure it ran by running the `logs` command.

docs/nav.js

@@ -18,6 +18,8 @@ const nav = {
         page('2 - Connecting to SpacetimeDB', 'unity/part-2', 'unity/part-2.md'),
         page('3 - Gameplay', 'unity/part-3', 'unity/part-3.md'),
         page('4 - Moving and Colliding', 'unity/part-4', 'unity/part-4.md'),
+        section('SQL'),
+        page('SQL Reference', 'sql', 'sql/index.md'),
         section('CLI Reference'),
         page('CLI Reference', 'cli-reference', 'cli-reference.md'),
         page('SpacetimeDB Standalone Configuration', 'cli-reference/standalone-config', 'cli-reference/standalone-config.md'),
@@ -35,20 +37,18 @@ const nav = {
         page('Rust Reference', 'sdks/rust', 'sdks/rust/index.md'),
         page('TypeScript Quickstart', 'sdks/typescript/quickstart', 'sdks/typescript/quickstart.md'),
         page('TypeScript Reference', 'sdks/typescript', 'sdks/typescript/index.md'),
-        section('SQL'),
-        page('SQL Reference', 'sql', 'sql/index.md'),
         section('Subscriptions'),
         page('Subscription Reference', 'subscriptions', 'subscriptions/index.md'),
         section('How To'),
         page('Incremental Migrations', 'how-to/incremental-migrations', 'how-to/incremental-migrations.md'),
         section('HTTP API'),
-        page('HTTP', 'http', 'http/index.md'),
+        page('Authorization', 'http/authorization', 'http/authorization.md'),
         page('`/identity`', 'http/identity', 'http/identity.md'),
         page('`/database`', 'http/database', 'http/database.md'),
         section('Internals'),
-        page('Module ABI Reference', 'webassembly-abi', 'webassembly-abi/index.md'),
-        page('SATS-JSON Data Format', 'sats-json', 'sats-json.md'),
-        page('BSATN Data Format', 'bsatn', 'bsatn.md'),
+        page('Module ABI Reference', 'webassembly-abi', 'internals/webassembly-abi.md'),
+        page('SATS-JSON Data Format', 'sats-json', 'internals/sats-json.md'),
+        page('BSATN Data Format', 'bsatn', 'internals/bsatn.md'),
         section('Appendix'),
         page('Appendix', 'appendix', 'appendix.md'),
     ],

docs/sdks/c-sharp/index.md

@@ -68,6 +68,8 @@ class DbConnection
 
 Construct a `DbConnection` by calling `DbConnection.Builder()`, chaining configuration methods, and finally calling `.Build()`. At a minimum, you must specify `WithUri` to provide the URI of the SpacetimeDB instance, and `WithModuleName` to specify the module's name or identity.
 
+Please be aware that you must [advance the connection](#advance-the-connection-and-process-messages) to process messages. If you don't do that, no callbacks will ever be invoked!
+
 | Name                                                    | Description                                                                                |
 |---------------------------------------------------------|--------------------------------------------------------------------------------------------|
 | [WithUri method](#method-withuri)                       | Set the URI of the SpacetimeDB instance hosting the remote database.                       |
@@ -159,7 +161,9 @@ After configuring the connection and registering callbacks, attempt to open the
 
 ## Advance the connection and process messages
 
-In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked.
+In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages.
+
+> NOTE: If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked.
 
 | Name                                        | Description                                           |
 |---------------------------------------------|-------------------------------------------------------|

docs/sdks/rust/index.md

@@ -67,6 +67,8 @@ impl DbConnection {
 
 Construct a `DbConnection` by calling `DbConnection::builder()` and chaining configuration methods, then calling `.build()`. You must at least specify `with_uri`, to supply the URI of the SpacetimeDB to which you published your module, and `with_module_name`, to supply the human-readable SpacetimeDB domain name or the raw `Identity` which identifies the module.
 
+Please be aware that you must [advance the connection](#advance-the-connection-and-process-messages) to process messages. If you don't do that, no callbacks will ever be invoked!
+
 | Name                                                      | Description                                                                          |
 |-----------------------------------------------------------|--------------------------------------------------------------------------------------|
 | [`with_uri` method](#method-with_uri)                     | Set the URI of the SpacetimeDB instance which hosts the remote database.             |
@@ -160,7 +162,9 @@ After configuring the connection and registering callbacks, attempt to open the
 
 ### Advance the connection and process messages
 
-In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked.
+In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the `DbConnection` spends compute time and processes messages.
+
+> NOTE: If you do not arrange for the connection to advance by calling one of these methods, the `DbConnection` will never advance, and no callbacks will ever be invoked.
 
 | Name                                          | Description                                           |
 |-----------------------------------------------|-------------------------------------------------------|