From 8aa74961eef2b9bddfff72a40f5430d72ed74414 Mon Sep 17 00:00:00 2001 From: Phoebe Goldman Date: Wed, 26 Jul 2023 11:17:10 -0400 Subject: [PATCH 1/2] Update `client_api.proto` docs based on my new understanding. --- .../protobuf/client_api.proto | 54 ++++++++----------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/crates/client-api-messages/protobuf/client_api.proto b/crates/client-api-messages/protobuf/client_api.proto index c2374ce42e..8452355d73 100644 --- a/crates/client-api-messages/protobuf/client_api.proto +++ b/crates/client-api-messages/protobuf/client_api.proto @@ -26,8 +26,12 @@ message Message { /// Received by database from client to inform of user's identity and token. /// -/// Do you receive this if you provide a token when connecting, or only if you connect -/// anonymously? Find out and document - pgoldman 2023-06-06. +/// The database will always send an `IdentityToken` message +/// as the first message for a new WebSocket connection. +/// If the client is re-connecting with existing credentials, +/// the message will include those credentials. +/// If the client connected anonymously, +/// the database will generate new credentials to identify it. message IdentityToken { bytes identity = 1; string token = 2; @@ -40,15 +44,11 @@ message IdentityToken { /// /// `reducer` is the string name of a reducer to run. /// -/// `argBytes` is the arguments to the reducer, encoded as BSATN. (Possibly as SATN if -/// you're in the text API? Find out and document - pgoldman 2023-06-05) +/// `argBytes` is the arguments to the reducer, encoded as BSATN. /// /// SpacetimeDB models reducers as taking a single `AlgebraicValue` as an argument, which /// generally will be a `ProductValue` containing all of the args (except the /// `ReducerContext`, which is injected by the host, not provided in this API). -/// -/// I don't think clients will ever receive a `FunctionCall` from the database, except -/// wrapped in an `Event` - pgoldman 2023-06-05. message FunctionCall { // TODO: Maybe this should be replaced with an int identifier for performance? string reducer = 1; @@ -71,21 +71,17 @@ message FunctionCall { /// will be subscribed to `B` but not `A`. In this case, the client will receive a /// `SubscriptionUpdate` containing every existing row that matches `B`, even if some were /// already in `A`. -/// -/// I don't think clients will ever receive a `Subscribe` from the database - pgoldman -/// 2023-06-05. message Subscribe { repeated string query_strings = 1; } /// Part of a `TransactionUpdate` received by client from database upon a reducer run. /// -/// `timestamp` is the time when the reducer ran (started? finished? Find out and document -/// - pgoldman 2023-06-05), as microseconds since the Unix epoch. +/// `timestamp` is the time when the reducer started, as microseconds since the Unix epoch. /// -/// `callerIdentity` is the identity token of the user who requested the reducer -/// run. (What if it's run by the database without a client request? Is -/// `callerIdentity` empty? Find out and document - pgoldman 2023-06-05). +/// `callerIdentity` is the identity of the user who requested the reducer run. +/// For event-driven and scheduled reducers, +/// it is the identity of the database owner. /// /// `functionCall` contains the name of the reducer which ran and the arguments it /// received. @@ -98,22 +94,17 @@ message Subscribe { /// `status` of `failed` means that the reducer panicked, and any changes it attempted to /// make were rolled back. /// -/// `status` of `failed` means that the reducer was interrupted due to insufficient -/// energy/funds, and any changes it attempted to make were rolled -/// back. (Verify this - pgoldman 2023-06-05). +/// `status` of `out_of_energy` means that the reducer was interrupted +/// due to insufficient energy/funds, +/// and any changes it attempted to make were rolled back. /// -/// `message` what does it do? Find out and document - pgoldman 2023-06-05. +/// `message` is the error message with which the reducer failed. +/// For `committed` or `out_of_energy` statuses, +/// it is the empty string. /// /// `energy_quanta_used` and `host_execution_duration_micros` seem self-explanatory; they /// describe the amount of energy credits consumed by running the reducer, and how long it /// took to run. -/// -/// Do clients receive `TransactionUpdate`s / `Event`s for reducer runs which don't touch -/// any of the client's subscribed rows? Find out and document - pgoldman 2023-06-05. -/// -/// Will a client ever receive an `Event` not wrapped in a `TransactionUpdate`? Possibly -/// when `status = failed` or `status = out_of_energy`? Find out and document - pgoldman -/// 2023-06-05. message Event { enum Status { committed = 0; @@ -154,9 +145,6 @@ message SubscriptionUpdate { /// or may not change between runs. /// /// `tableRowOperations` are actual modified rows. -/// -/// Can a client send `TableUpdate`s to the database to alter the database? I don't think -/// so, but would be good to know for sure - pgoldman 2023-06-05. message TableUpdate { uint32 tableId = 1; string tableName = 2; @@ -178,8 +166,7 @@ message TableUpdate { /// tables with a `#[primarykey]` annotation on one column, the `row_pk` is not /// that primary key. /// -/// `row` is the row itself, encoded as BSATN (or possibly SATN for the text api? Find out -/// and document - pgoldman 2023-06-05). +/// `row` is the row itself, encoded as BSATN. message TableRowOperation { enum OperationType { DELETE = 0; @@ -192,8 +179,9 @@ message TableRowOperation { /// Received by client from database upon a reducer run. /// -/// Do clients receive `TransactionUpdate`s for reducer runs which do not alter any of the -/// client's subscribed rows? Find out and document - pgoldman 2023-06-05. +/// Clients receive `TransactionUpdate`s only for reducers +/// which update at least one of their subscribed rows, +/// or for their own `failed` or `out_of_energy` reducer invocations. /// /// `event` contains information about the reducer. /// From 68daaae8e7ae13fe0674739ea18a0b6956eb12de Mon Sep 17 00:00:00 2001 From: Phoebe Goldman Date: Wed, 26 Jul 2023 11:56:18 -0400 Subject: [PATCH 2/2] Add bullet points to field lists --- .../protobuf/client_api.proto | 67 ++++++++++--------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/crates/client-api-messages/protobuf/client_api.proto b/crates/client-api-messages/protobuf/client_api.proto index 8452355d73..9f4d1bbd1f 100644 --- a/crates/client-api-messages/protobuf/client_api.proto +++ b/crates/client-api-messages/protobuf/client_api.proto @@ -42,9 +42,9 @@ message IdentityToken { /// Sent by client to database to request a reducer runs. /// -/// `reducer` is the string name of a reducer to run. +/// - `reducer` is the string name of a reducer to run. /// -/// `argBytes` is the arguments to the reducer, encoded as BSATN. +/// - `argBytes` is the arguments to the reducer, encoded as BSATN. /// /// SpacetimeDB models reducers as taking a single `AlgebraicValue` as an argument, which /// generally will be a `ProductValue` containing all of the args (except the @@ -77,34 +77,35 @@ message Subscribe { /// Part of a `TransactionUpdate` received by client from database upon a reducer run. /// -/// `timestamp` is the time when the reducer started, as microseconds since the Unix epoch. +/// - `timestamp` is the time when the reducer started, +/// as microseconds since the Unix epoch. /// -/// `callerIdentity` is the identity of the user who requested the reducer run. -/// For event-driven and scheduled reducers, -/// it is the identity of the database owner. +/// - `callerIdentity` is the identity of the user who requested the reducer run. +/// For event-driven and scheduled reducers, +/// it is the identity of the database owner. /// -/// `functionCall` contains the name of the reducer which ran and the arguments it -/// received. +/// - `functionCall` contains the name of the reducer which ran and the arguments it +/// received. /// -/// `status` of `committed` means that the reducer ran successfully and its changes were -/// committed to the database. The rows altered in the database -/// will be recorded in the parent `TransactionUpdate`'s -/// `SubscriptionUpdate`. +/// - `status` of `committed` means that the reducer ran successfully and its changes were +/// committed to the database. The rows altered in the database +/// will be recorded in the parent `TransactionUpdate`'s +/// `SubscriptionUpdate`. /// -/// `status` of `failed` means that the reducer panicked, and any changes it attempted to -/// make were rolled back. +/// - `status` of `failed` means that the reducer panicked, and any changes it attempted to +/// make were rolled back. /// -/// `status` of `out_of_energy` means that the reducer was interrupted -/// due to insufficient energy/funds, -/// and any changes it attempted to make were rolled back. +/// - `status` of `out_of_energy` means that the reducer was interrupted +/// due to insufficient energy/funds, +/// and any changes it attempted to make were rolled back. /// -/// `message` is the error message with which the reducer failed. -/// For `committed` or `out_of_energy` statuses, -/// it is the empty string. +/// - `message` is the error message with which the reducer failed. +/// For `committed` or `out_of_energy` statuses, +/// it is the empty string. /// -/// `energy_quanta_used` and `host_execution_duration_micros` seem self-explanatory; they -/// describe the amount of energy credits consumed by running the reducer, and how long it -/// took to run. +/// - `energy_quanta_used` and `host_execution_duration_micros` seem self-explanatory; +/// they describe the amount of energy credits consumed by running the reducer, +/// and how long it took to run. message Event { enum Status { committed = 0; @@ -156,17 +157,17 @@ message TableUpdate { /// /// The table being altered is identified by the parent `TableUpdate`. /// -/// `op` of `DELETE` means that the row in question has been removed and is no longer -/// resident in the table. +/// - `op` of `DELETE` means that the row in question has been removed and is no longer +/// resident in the table. /// -/// `op` of `INSERT` means that the row in question has been either newly inserted or -/// updated, and is resident in the table. +/// - `op` of `INSERT` means that the row in question has been either newly inserted or +/// updated, and is resident in the table. /// -/// `row_pk` is a hash of the row computed by the database. As of 2023-06-13, even for -/// tables with a `#[primarykey]` annotation on one column, the `row_pk` is not -/// that primary key. +/// - `row_pk` is a hash of the row computed by the database. As of 2023-06-13, even for +/// tables with a `#[primarykey]` annotation on one column, the `row_pk` is not +/// that primary key. /// -/// `row` is the row itself, encoded as BSATN. +/// - `row` is the row itself, encoded as BSATN. message TableRowOperation { enum OperationType { DELETE = 0; @@ -183,9 +184,9 @@ message TableRowOperation { /// which update at least one of their subscribed rows, /// or for their own `failed` or `out_of_energy` reducer invocations. /// -/// `event` contains information about the reducer. +/// - `event` contains information about the reducer. /// -/// `subscriptionUpdate` contains changes to subscribed rows. +/// - `subscriptionUpdate` contains changes to subscribed rows. message TransactionUpdate { Event event = 1; SubscriptionUpdate subscriptionUpdate = 2;