Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update client_api.proto docs based on my new understanding. #101

Merged
merged 2 commits into from
Jul 26, 2023
Merged

Update client_api.proto docs based on my new understanding. #101

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8aa7496
Update `client_api.proto` docs based on my new understanding.
gefjon Jul 26, 2023
68daaae
Add bullet points to field lists
gefjon Jul 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 43 additions & 54 deletions crates/client-api-messages/protobuf/client_api.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -38,17 +42,13 @@ 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. (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;
Expand All @@ -71,49 +71,41 @@ 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.
///
/// `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).
/// - `timestamp` is the time when the reducer started,
/// as microseconds since the Unix epoch.
///
/// `functionCall` contains the name of the reducer which ran and the arguments it
/// received.
/// - `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.
///
/// `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`.
/// - `functionCall` contains the name of the reducer which ran and the arguments it
/// received.
///
/// `status` of `failed` means that the reducer panicked, and any changes it attempted to
/// make were rolled back.
/// - `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 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 `failed` means that the reducer panicked, and any changes it attempted to
/// make were rolled back.
///
/// `message` what does it do? Find out and document - 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.
///
/// `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` is the error message with which the reducer failed.
/// For `committed` or `out_of_energy` statuses,
/// it is the empty string.
///
/// 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.
/// - `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;
Expand Down Expand Up @@ -154,9 +146,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;
Expand All @@ -168,18 +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 (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;
Expand All @@ -192,12 +180,13 @@ 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.
/// - `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;
Expand Down