Add address: Address to ReducerContext

[gefjon]

Description of Changes

Initial support for identifying connections via an Address, passed as the caller address in ReducerContext.

Notable design choices:

• The same type Address is used for clients and dbs, as opposed to having distinct DbAddress and ClientAddress types.
• init and update receive the address of the caller of publish, or None if the caller did not supply an address. This is useful for SpacetimeDB-cloud.
• Scheduled reducers do not receive an address.
• Clients may specify an Address as a query parameter to the subscribe and call endpoints. If they do not, an Address will be randomly generated for them.
• The Rust SDK always generates a random Address the first time it connects, and uses that Address for the duration of the process. This will allow modules to detect re-connecting clients in the case of an unintentional disconnect, e.g. caused by an intermittent internet connection.

Breaking changes that aren't particularly design decisions:

• The IdentityToken message adds a new field address, which holds the client's address. This will allow clients which do not generate their own Address to discover the address generated by the server, and clients which do generate their own Address to verify it.
• The Event message (actually a part of TransactionUpdate) adds a new field callerAddress, which holds the address of the client which called the reducer. The all-zeros address is used as a sentinel for None (same as for host-module communcation).
• The database info stored in the Sled DB now holds the publisher's address. This is an unfortunate necessity to passing it through from the publish endpoint to the init/update reducer. This also will probably be a merge conflict with cloud-next.
• Address is now a product type with a single field, __address_bytes. This is similar to how we treat Identity, and allows the CLI's codegen to reference an appropriate SDK-side Address type rather than a u128 or an array of bytes.
• The Rust SDK's on_connect callbacks (some SDKs call this onIdentityReceived or similar) takes an additional argument, the client's Address.
• The Rust SDK's reducer callbacks take an additional argument of type Option<Address>, the address of the caller of the reducer.

Still to do:

• SDK support.
  • Rust
  • C# in Add support for client address; re-run spacetime generate for quickstart client com.clockworklabs.spacetimedbsdk#54
  • TypeScript in Client address support for TypeScript SDK spacetimedb-typescript-sdk#23
  • Python in Add client-address support spacetimedb-python-sdk#9
• Documentation.
  • Update module quickstarts.
  • Update client quickstarts.
  • Update module references.
  • Update client references.
  • Rename identity_connected/identity_disconnected to client_connected/client_disconnected
    • In docs.
    • In examples.
    • In spacetime init default modules.
• Refuse new connections if an existing connection with the same (Identity, Address) pair exists.
  • Likely deferring to a later PR.
• Bump module ABI version.
  • Likely we'll do a single ABI version bump with the release, rather than per-PR version bumps.
• Send failed reducer messages only to the connection with the address that called them, not to all connections with the same identity. This may already be the behavior implemented, but might not be.
  • Appears to already be the behavior.
• Include the caller address in reducer event messages reported to clients, alongside the caller identity.
• C# module support.

API and ABI

• This is a breaking change to the module ABI
• This is a breaking change to the module API
• This is a breaking change to the ClientAPI
• This is a breaking change to the SDK API

If the API is breaking, please state below what will break

ReducerContext contains an additional field, so low-level macro-generated reducer functions take an additional argument.

Technically this is a SemVer breaking change to the module API, as previous exhaustive destructurings of ReducerContext will no longer compile. For modules which don't want the new functionality, they can trivially add a , .. to their patterns.

The Rust SDK's on_connect callbacks (some SDKs call this onIdentityReceived or similar) takes an additional argument, the client's Address.

This is a non-breaking change to the HTTP API, as it adds an optional query parameter to the subscribe and call endpoints.

This adds a field to two of our client API protobuf messages (IdentityToken; Event). I don't understand protobuf deeply enough to know if this counts as a breaking change.

[kim]

For automatic reducers (init, scheduled, &c), the passed Address is the database's address, not the address of the client which called publish.

Is this true? Could you point me to the code which does this?

As I said elsewhere, I would assume that if those reducers get passed the identity of the caller, then we should also be able to get at the corresponding address.

[kim]

Yes this is fine -- as of now, the address is (implicitly) scoped to the identity, so is very unlikely to collide. Unless this fact is not considered, of course.

cloud-next also defines [ControlStateWriteAccess::create_address], so we could use that when porting this patch over.

[cloutiertyler]

Why wouldn't init be the caller? I think in this case those two are the same, but I would expect init would be the caller, and that might be meaningful down the road.

[gefjon]

Is this true? Could you point me to the code which does this?

For scheduled reducers:

SpacetimeDB/crates/core/src/host/scheduler.rs

Line 273 in f9abfcd

let address = info.address;

For init:

SpacetimeDB/crates/core/src/host/wasm_common/module_host_actor.rs

Line 341 in f9abfcd

let caller_address = self.database_instance_context().address;

As I said elsewhere, I would assume that if those reducers get passed the identity of the caller, then we should also be able to get at the corresponding address.

I think this is the wrong intuition; I would say that automatic reducers get passed the identity associated with the database, which is its owner's identity. The person which called publish arguably indirectly causes init/update to be invoked, but I don't think there's any case that they're the caller_address of scheduled or repeating reducers.

Philosophy aside, is there a case where it would be useful for a module to know the Address that published it? I don't think knowing its own Address is currently useful, but I imagine it will become useful when we implement inter-module communication.

[kim]

Philosophy aside, is there a case where it would be useful for a module to know the Address that published it? I don't think knowing its own Address is currently useful, but I imagine it will become useful when we implement inter-module communication.

So, the problem is this: with the current authentication model, nodes in the distributed setup have to have the same Identity -- otherwise, we'd need to provision eligible identities more or less manually. So the idea is that the "control" identity is trusted, because it created the database, and every other node will use that same identity but with a different address. That is: the client address in this context is, in fact, a node identity.

Now: in the bootstrap scenario, the init reducer will need to know the node identity of the bootstrap node, so it can assign instances to it.

Does that make sense?

[cloutiertyler]

I think this is the wrong intuition; I would say that automatic reducers get passed the identity associated with the database, which is its owner's identity. The person which called publish arguably indirectly causes init/update to be invoked, but I don't think there's any case that they're the caller_address of scheduled or repeating reducers.

I'm not so sure about this. I think init/update is really triggered by the caller, not by the database itself, but I could be convinced otherwise. Right now these two are always the same, so it doesn't matter.

[gefjon]

I think init/update is really triggered by the caller, not by the database itsel

Kim convinced me of this offline. The behavior in this PR for automatic reducers is:

• init gets the client_address passed to the publish HTTP endpoint, or None if no client_address was supplied when publishing.
• Scheduled reducers always get None as the caller address.

[cloutiertyler]

Heroic job with this PR, @gefjon. And the PR comment is 👨‍🍳👌