Replies: 1 comment
-
CHANGELOG2022-07-07
|
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
#3933 has been updated quite a few times, this is a summarized version of the results.
1. The Concept of State
State is defined as a payload of data that provides a context for EdgeQL commands to run with. Currently, state is consist of module aliases, "session" config and global values, for example:
State is sent from the client with
Parse
andExecute
messages, and returned from the server inCommandComplete
messages. The server compiles and executes the given command(s) in the context of the given state, and command(s) inExecute
may modify the state, thenCommandComplete
would include an updated state.State is serialized in the same way as input/output arguments are serialized. A new type descriptor "input shape descriptor" is used to describe state data as sparse objects. This is similar to the object shape descriptor, only that sparse objects will skip serializing missing properties. For example, the state itself is a sparse object, values of its keys
config
andglobals
are also sparse objects.2. On establishing connections
Once the server has confirmed successful authentication with AuthenticationOK, it then sends the following messages:
StateDataDescription
messageThe new
StateDataDescription
message contains an input shape descriptor of the state in the following format:The client could build codecs from the type descriptor and cache them for future state (de-)serialization on demand.
3. Send command request with state
The
Parse
andExecute
messages are updated to allow the client send states:If the client decides not to send state, the
state_typedesc_id
can be set to a special null type ID00000000-0000-0000-0000-000000000000
, the server will then use the default state to compile and/or execute the given commands accordingly.Otherwise, the given
state_typedesc_id
is expected to match the current state type on the server-side. On mismatch, the server will return aStateDataDescription
message with the current state type descriptor, immediately followed by a new errorStateMismatchError
in anErrorResponse
message.4. Server returns state
On successful execution of EdgeQL commands, the server will return:
CommandDataDescription
if the output type identifier mismatches;Data
messages.StateDataDescription
if the given command(s) modified the state type (e.g. creating a new global);CommandComplete
message with the state as follows:If the executed command didn't change the state values, the
state_typedesc_id
will be set to the same special null type ID00000000-0000-0000-0000-000000000000
, indicating the state was not changed. In this case,state_data
is a zero-lengthedbytes
. If the state values are changed by the command, thestate_typedesc_id
is guaranteed to be the same as it was in theExecute
request message, even if the state schema is concurrently changed in other sessions, unless thisExecute
is also changing the state schema.Please note, state DDL and mutation of the state values are transactional. That means,
rollback
command could return aStateDataDescription
message and aCommandComplete
message with concrete state data, if the state schema or state values were updated in the transaction to be rolled back.5. Client bindings guideline
The client bindings is recommended to provide special APIs for users to set state. Particularly,
client.with_config()
,client.with_aliases()
andclient.with_globals()
. Becauseclient
is assumed to be safely used in multithreading or different asynchronous tasks/coroutines, EdgeQL commands that modify the state likeset global
,set alias
,set module
,configure session
and theirreset
variants would be racy. These commands are covered in the capabilitysession config
, so the client could either disable this capability inquery()
andexecute()
, or prevent the server-returned state from affecting other threads/tasks/coroutines.6. State type changes while state is not default
If a global type is changed while its value is set, the DDL must use
set global ... set type ... using ...
to instruct the server to convert the value.If the state type is concurrently modified by other clients,
StateMismatchError
will be raised from the server handling the next command with an outdated state type identifier. The client should be ready to handle this error, by e.g. re-encoding the state with the codecs built from the updated state type descriptors. If the state cannot be encoded, the client could drop the connection with a proper error.Beta Was this translation helpful? Give feedback.
All reactions