Skip to content
This repository was archived by the owner on Aug 8, 2025. It is now read-only.

More SDK Updates for 0.7.0 #5

Merged
jdetter merged 2 commits into from
Oct 12, 2023
Merged

More SDK Updates for 0.7.0 #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60fee24
Fix Nuget command
jdetter Oct 12, 2023
5493514
Applied Phoebe's patch
jdetter Oct 12, 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
49 changes: 34 additions & 15 deletions docs/Client SDK Languages/C#/SDK Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ The SpacetimeDB client C# for Rust contains all the tools you need to build nati
- [Static Property `AuthToken.Token`](#static-property-authtokentoken)
- [Static Method `AuthToken.SaveToken`](#static-method-authtokensavetoken)
- [Class `Identity`](#class-identity)
- [Class `Address`](#class-address)
- [Customizing logging](#customizing-logging)
- [Interface `ISpacetimeDBLogger`](#interface-ispacetimedblogger)
- [Class `ConsoleLogger`](#class-consolelogger)
Expand Down Expand Up @@ -178,7 +179,7 @@ SpacetimeDBClient.instance.Connect(null, "dev.spacetimedb.net", DBNAME, true);
AuthToken.Init();
Identity localIdentity;
SpacetimeDBClient.instance.Connect(AuthToken.Token, "dev.spacetimedb.net", DBNAME, true);
SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity identity) {
SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity identity, Address address) {
AuthToken.SaveToken(authToken);
localIdentity = identity;
}
Expand All @@ -192,13 +193,13 @@ SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity ide
namespace SpacetimeDB {

class SpacetimeDBClient {
public event Action<string, Identity> onIdentityReceived;
public event Action<string, Identity, Address> onIdentityReceived;
}

}
```

Called when we receive an auth token and [`Identity`](#class-identity) from the server. The [`Identity`](#class-identity) serves as a unique public identifier for a client connected to the database. It can be for several purposes, such as filtering rows in a database for the rows created by a particular user. The auth token is a private access token that allows us to assume an identity.
+Called when we receive an auth token, [`Identity`](#class-identity) and [`Address`](#class-address) from the server. The [`Identity`](#class-identity) serves as a unique public identifier for a user of the database. It can be for several purposes, such as filtering rows in a database for the rows created by a particular user. The auth token is a private access token that allows us to assume an identity. The [`Address`](#class-address) is opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#class-identity).

To store the auth token to the filesystem, use the static method [`AuthToken.SaveToken`](#static-method-authtokensavetoken). You may also want to store the returned [`Identity`](#class-identity) in a local variable.

Expand All @@ -209,7 +210,7 @@ If an existing auth token is used to connect to the database, the same auth toke
AuthToken.Init();
Identity localIdentity;
SpacetimeDBClient.instance.Connect(AuthToken.Token, "dev.spacetimedb.net", DBNAME, true);
SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity identity) {
SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity identity, Address address) {
AuthToken.SaveToken(authToken);
localIdentity = identity;
}
Expand Down Expand Up @@ -856,24 +857,42 @@ Save a token to the filesystem.
### Class `Identity`

```cs
namespace SpacetimeDB {

public struct Identity : IEquatable<Identity>
namespace SpacetimeDB
{
public byte[] Bytes { get; }
public static Identity From(byte[] bytes);
public bool Equals(Identity other);
public static bool operator ==(Identity a, Identity b);
public static bool operator !=(Identity a, Identity b);
}

public struct Identity : IEquatable<Identity>
{
public byte[] Bytes { get; }
public static Identity From(byte[] bytes);
public bool Equals(Identity other);
public static bool operator ==(Identity a, Identity b);
public static bool operator !=(Identity a, Identity b);
}
}
```

A unique public identifier for a client connected to a database.
A unique public identifier for a user of a database.

<!-- FIXME: this is no longer accurate; `Identity` columns are properly `Identity`-type. -->

Columns of type `Identity` inside a module will be represented in the C# SDK as properties of type `byte[]`. `Identity` is essentially just a wrapper around `byte[]`, and you can use the `Bytes` property to get a `byte[]` that can be used to filter tables and so on.

### Class `Identity`
```cs
namespace SpacetimeDB
{
public struct Address : IEquatable<Address>
{
public byte[] Bytes { get; }
public static Address? From(byte[] bytes);
public bool Equals(Address other);
public static bool operator ==(Address a, Address b);
public static bool operator !=(Address a, Address b);
}
}
```

An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#class-identity).

## Customizing logging

The SpacetimeDB C# SDK performs internal logging. Instances of [`ISpacetimeDBLogger`](#interface-ispacetimedblogger) can be passed to [`SpacetimeDBClient.CreateInstance`](#static-method-spacetimedbclientcreateinstance) to customize how SDK logs are delivered to your application.
Expand Down
6 changes: 3 additions & 3 deletions docs/Client SDK Languages/C#/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ Open the project in your IDE of choice.

## Add the NuGet package for the C# SpacetimeDB SDK

Add the `spacetimedbsdk` [NuGet package](https://www.nuget.org/packages/spacetimedbsdk) using Visual Studio NuGet package manager or via the .NET CLI
Add the `SpacetimeDB.ClientSDK` [NuGet package](https://www.nuget.org/packages/spacetimedbsdk) using Visual Studio NuGet package manager or via the .NET CLI

```bash
dotnet add package spacetimedbsdk
dotnet add package SpacetimeDB.ClientSDK
```

## Generate your module types
Expand Down Expand Up @@ -288,7 +288,7 @@ void OnConnect()

## OnIdentityReceived callback

This callback is executed when we receive our credentials from the SpacetimeDB module. We'll use the `AuthToken` module to save our token to local storage, so that we can re-authenticate as the same user the next time we connect. We'll also store the identity in a global variable `local_identity` so that we can use it to check if we are the sender of a message or name change.
This callback is executed when we receive our credentials from the SpacetimeDB module. We'll use the `AuthToken` module to save our token to local storage, so that we can re-authenticate as the same user the next time we connect. We'll also store the identity in a global variable `local_identity` so that we can use it to check if we are the sender of a message or name change. This callback also notifies us of our client's `Address`, an opaque identifier SpacetimeDB modules can use to distinguish connections by the same `Identity`, but we won't use it in our app.

```csharp
void OnIdentityReceived(string authToken, Identity identity, Address _address)
Expand Down
73 changes: 50 additions & 23 deletions docs/Client SDK Languages/Python/SDK Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,9 @@ The following functions and types are used in both the Basic and Async clients.
### API at a glance

| Definition | Description |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| Type [`Identity`](#type-identity) | A unique public identifier for a client. |
| Type [`Address`](#type-address) | An opaque identifier for differentiating connections by the same `Identity`. |
| Type [`ReducerEvent`](#type-reducerevent) | `class` containing information about the reducer that triggered a row update event. |
| Type [`module_bindings::{TABLE}`](#type-table) | Autogenerated `class` type for a table, holding one row. |
| Method [`module_bindings::{TABLE}::filter_by_{COLUMN}`](#method-filter_by_column) | Autogenerated method to iterate over or seek subscribed rows where a column matches a value. |
Expand Down Expand Up @@ -76,7 +77,31 @@ class Identity:
| `__str__` | `None` | Convert the Identity to a hex string |
| `__eq__` | `Identity` | Compare two Identities for equality |

A unique public identifier for a client connected to a database.
A unique public identifier for a user of a database.

### Type `Address`

```python
class Address:
@staticmethod
def from_string(string)

@staticmethod
def from_bytes(data)

def __str__(self)

def __eq__(self, other)
```

| Member | Type | Meaning |
|---------------|-----------|-------------------------------------|
| `from_string` | `str` | Create an Address from a hex string |
| `from_bytes` | `bytes` | Create an Address from raw bytes |
| `__str__` | `None` | Convert the Address to a hex string |
| `__eq__` | `Address` | Compare two Identities for equality |

An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#type-identity).

### Type `ReducerEvent`

Expand All @@ -90,13 +115,14 @@ class ReducerEvent:
self.args = args
```

| Member | Args | Meaning |
| ----------------- | ----------- | --------------------------------------------------------------------------- |
| `caller_identity` | `Identity` | The identity of the user who invoked the reducer |
| `reducer_name` | `str` | The name of the reducer that was invoked |
| `status` | `str` | The status of the reducer invocation ("committed", "failed", "outofenergy") |
| `message` | `str` | The message returned by the reducer if it fails |
| `args` | `List[str]` | The arguments passed to the reducer |
| Member | Type | Meaning |
|-------------------|---------------------|------------------------------------------------------------------------------------|
| `caller_identity` | `Identity` | The identity of the user who invoked the reducer |
| `caller_address` | `Optional[Address]` | The address of the user who invoked the reducer, or `None` for scheduled reducers. |
| `reducer_name` | `str` | The name of the reducer that was invoked |
| `status` | `str` | The status of the reducer invocation ("committed", "failed", "outofenergy") |
| `message` | `str` | The message returned by the reducer if it fails |
| `args` | `List[str]` | The arguments passed to the reducer |

This class contains the information about a reducer event to be passed to row update callbacks.

Expand Down Expand Up @@ -173,7 +199,7 @@ This function is autogenerated for each reducer in your module. It is used to in
### Function `register_on_{REDUCER_NAME}`

```python
def register_on_{REDUCER_NAME}(callback: Callable[[Identity, str, str, ARG1_TYPE, ARG1_TYPE], None])
def register_on_{REDUCER_NAME}(callback: Callable[[Identity, Optional[Address], str, str, ARG1_TYPE, ARG1_TYPE], None])
```

| Argument | Type | Meaning |
Expand All @@ -183,6 +209,7 @@ def register_on_{REDUCER_NAME}(callback: Callable[[Identity, str, str, ARG1_TYPE
Register a callback function to be executed when the reducer is invoked. Callback arguments are:

- `caller_identity`: The identity of the user who invoked the reducer.
- `caller_address`: The address of the user who invoked the reducer, or `None` for scheduled reducers.
- `status`: The status of the reducer invocation ("committed", "failed", "outofenergy").
- `message`: The message returned by the reducer if it fails.
- `args`: Variable number of arguments passed to the reducer.
Expand Down Expand Up @@ -326,7 +353,7 @@ spacetime_client.schedule_event(0.1, application_tick)
### API at a glance

| Definition | Description |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| Function [`SpacetimeDBClient::init`](#function-init) | Create a network manager instance. |
| Function [`SpacetimeDBClient::subscribe`](#function-subscribe) | Subscribe to receive data and transaction updates for the provided queries. |
| Function [`SpacetimeDBClient::register_on_event`](#function-register_on_event) | Register a callback function to handle transaction update events. |
Expand All @@ -349,24 +376,24 @@ def init(
autogen_package: module,
on_connect: Callable[[], NoneType] = None,
on_disconnect: Callable[[str], NoneType] = None,
on_identity: Callable[[str, Identity], NoneType] = None,
on_identity: Callable[[str, Identity, Address], NoneType] = None,
on_error: Callable[[str], NoneType] = None
)
```

Create a network manager instance.

| Argument | Type | Meaning |
| ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `auth_token` | `str` | This is the token generated by SpacetimeDB that matches the user's identity. If None, token will be generated |
| `host` | `str` | Hostname:port for SpacetimeDB connection |
| `address_or_name` | `str` | The name or address of the database to connect to |
| `ssl_enabled` | `bool` | Whether to use SSL when connecting to the server. |
| `autogen_package` | `ModuleType` | Python package where SpacetimeDB module generated files are located. |
| `on_connect` | `Callable[[], None]` | Optional callback called when a connection is made to the SpacetimeDB module. |
| `on_disconnect` | `Callable[[str], None]` | Optional callback called when the Python client is disconnected from the SpacetimeDB module. The argument is the close message. |
| `on_identity` | `Callable[[str, Identity], None]` | Called when the user identity is recieved from SpacetimeDB. First argument is the auth token used to login in future sessions. |
| `on_error` | `Callable[[str], None]` | Optional callback called when the Python client connection encounters an error. The argument is the error message. |
| Argument | Type | Meaning |
|-------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `auth_token` | `str` | This is the token generated by SpacetimeDB that matches the user's identity. If None, token will be generated |
| `host` | `str` | Hostname:port for SpacetimeDB connection |
| `address_or_name` | `str` | The name or address of the database to connect to |
| `ssl_enabled` | `bool` | Whether to use SSL when connecting to the server. |
| `autogen_package` | `ModuleType` | Python package where SpacetimeDB module generated files are located. |
| `on_connect` | `Callable[[], None]` | Optional callback called when a connection is made to the SpacetimeDB module. |
| `on_disconnect` | `Callable[[str], None]` | Optional callback called when the Python client is disconnected from the SpacetimeDB module. The argument is the close message. |
| `on_identity` | `Callable[[str, Identity, Address], None]` | Called when the user identity is recieved from SpacetimeDB. First argument is the auth token used to login in future sessions. Third argument is the client connection's [`Address`](#type-address). |
| `on_error` | `Callable[[str], None]` | Optional callback called when the Python client connection encounters an error. The argument is the error message. |

This function creates a new SpacetimeDBClient instance. It should be called before any other functions in the SpacetimeDBClient class. This init will call connect for you.

Expand Down
Loading