RFC 1010 Implementation Details of the Protocol Changes

[fantix]

This is superseded by #4009.

Server Notifications of Session State Type

On connection, the server will send a ParameterStatus message with name session_state_description, and value as described in:

struct ParameterStatus_SessionStateDescription {
  // Session state descriptor ID.
  uuid            typedesc_id;

  // Session state descriptor.
  bytes           typedesc;
};

The same ParameterStatus message will also be pushed to all active connections when an DDL command that affects the session state type is applied successfully, like a create global command.

Theoretically the client could use this message to build encoders/decoders so as to read or manipulate the session state, but the official client bindings are not yet doing anything with this message.

Server Responses with Session State

All server CommandComplete messages will send two extra fields as the most recent session state:

  struct CommandComplete {
    // Message type ('C').
    uint8           mtype = 0x43;

    // Length of message contents in bytes,
    // including self.
    uint32          message_length;

    // A set of message headers.
    uint16          num_headers;
    Header          headers[num_headers];

    // Command status.
    string          status;
+
+   // Updated session state descriptor ID.
+   uuid            state_typedesc_id;
+
+   // Encoded session state data array. The array is
+   // currently always of size 1.
+   uint16          num_state_data;
+   DataElement     state_data[num_state_data];
};

struct DataElement {
  // Encoded output data.
  uint32          num_data;
  uint8           data[num_data];
};

The exact encoding of DataElement.data is defined by the session state type descriptor. The session state is a free object like this:

{
    module := 'default',
    aliases := [ ( 'alias', 'module::target'), ... ],
    config := cfg::Config {
        session_idle_transaction_timeout: <duration>'0:05:00',
        query_execution_timeout: <duration>'0:00:00',
        allow_dml_in_functions: false,
        allow_bare_ddl: AlwaysAllow,
        apply_access_policies: true,
    },
    globals := { 'mod::key' := value, ... },
}

The client is supposed to store (overwrite if exist) the state_typedesc_id and state_data per connection, and sends them together with the next Parse or Execute message, please see below.

When a DDL command is successfully applied, it may modify session state fields that already have data in the current session, for example:

create global xxx -> str;
set global xxx := 'hello';
alter global xxx set type int64;
drop global xxx;  // or this

In this case, instead of returning CommandComplete, the server will instead return a new message:

struct CommandCompleteWithConsequence {
  // Message type ('c').
  uint8           mtype = 0x63;

  // Length of message contents in bytes,
  // including self.
  uint32          message_length;

  // Command status.
  string          status;

  // Message code.
  uint32          error_code;

  // Error message.
  string          message;

  // Error attributes.
  uint16          num_attributes;
  Header          attributes[num_attributes];
};

error_code is set to a new error type StateSerializationError. This message means the DDL command is applied successfully, but the state cannot be serialized. The client could either choose to drop the connection (official client binding behavior), or update the state according to the type descriptor in the ParameterStatus message and move on.

Other concurrent connections will only receive a ParameterStatus message. The server will not actively drop any connection in this case.

Client Requests with Session State

The client will send two extra fields in messages Parse and Execute:

  struct Parse {
    // Message type ('P').
    uint8           mtype = 0x50;

    // Length of message contents in bytes,
    // including self.
    uint32          message_length;

    // A set of message headers.
    uint16          num_headers;
    Header          headers[num_headers];

    // Data I/O format.
    uint8<IOFormat> io_format;

    // Expected result cardinality
    uint8<Cardinality> expected_cardinality;

    // Command text.
    string          command;
+
+   // Session state descriptor ID.
+   uuid            state_typedesc_id;
+
+   // Encoded session state data array. The array is
+   // currently always of size 1.
+   uint16          num_state_data;
+   DataElement     state_data[num_state_data];
  };

  struct Execute {
    // Message type ('O').
    uint8           mtype = 0x4f;

    // Length of message contents in bytes,
    // including self.
    uint32          message_length;

    // A set of message headers.
    uint16          num_headers;
    Header          headers[num_headers];

    // Data I/O format.
    uint8<IOFormat> io_format;

    // Expected result cardinality.
    uint8<Cardinality> expected_cardinality;

    // Command text.
    string          command_text;
+
+   // Session state descriptor ID.
+   uuid            state_typedesc_id;
+
+   // Encoded session state data array. The array is
+   // currently always of size 1.
+   uint16          num_state_data;
+   DataElement     state_data[num_state_data];

    // Argument data descriptor ID.
    uuid            input_typedesc_id;

    // Output data descriptor ID.
    uuid            output_typedesc_id;

    // Encoded argument data.
    bytes           arguments;
  };

state_typedesc_id and state_data should be set to the most recently received state data from the server in CommandComplete messages. In case when the client doesn't have a stored state, or doesn't want to send a message with state data, state_typedesc_id can be set to a special ID of zero: 00000000-0000-0000-0000-000000000000, indicating an empty/default state.

On receiving these messages, the server would check the state_typedesc_id against the current one of the current database. On mismatch, the server will send an ErrorResponse message with a new error type: StateMismatchError. The client is safe to retry with an updated state, or simply drop the connection with an error (current official client bindings behavior).

Capabilities in Official Client Bindings

The client bindings shall provide withGlobals() API for setting globals. At the same time, EdgeQL command SET GLOBAL should be forbidden in official client bindings. In RFC 1010, set global requires the capability session config, but that is also used by configure session commands. So we'd probably need a new capability for set global and reset global commands, like session global or so.

[fantix]

UPDATE

1. State is not needed in Parse message.
2. We dropped the "session" term from session_state_description, so it's just state_description.
3. We will drop DataElement and use something more readable, so the Execute message is now like:

  struct Execute {
    // Message type ('O').
    uint8           mtype = 0x4f;

    // Length of message contents in bytes,
    // including self.
    uint32          message_length;

    // A set of message headers.
    uint16          num_headers;
    Header          headers[num_headers];

    // Data I/O format.
    uint8<IOFormat> io_format;

    // Expected result cardinality.
    uint8<Cardinality> expected_cardinality;

    // Command text.
    string          command_text;

    // Argument data descriptor ID.
    uuid            input_typedesc_id;

    // Output data descriptor ID.
    uuid            output_typedesc_id;
+
+   // Session state descriptor ID.
+   uuid            state_typedesc_id;

    // Encoded argument data.
    bytes           arguments;
+
+   // Encoded state data.
+   bytes           state_data;
  };

4. No more CommandCompleteWithConsequence and StateSerializationError because we are adding alter global ... set type ... using.
5. Re capabilities: session config will cover all set global, reset global, as well as current configure session, set alias, set module and their "reset" variants.

[fantix]

UPDATE 2

State is still needed in Parse. Here's the latest Parse and Execute message change:

 struct Parse {
   // Message type ('P').
   uint8           mtype = 0x50;

   // Length of message contents in bytes,
   // including self.
   uint32          message_length;

   // A set of message headers.
   uint16          num_headers;
   Header          headers[num_headers];

   // A bit mask of allowed capabilities.
   uint64<Capability> allowed_capabilities;

   // A bit mask of query options.
   uint64<CompilationFlag> compilation_flags;

   // Implicit LIMIT clause on returned sets.
   uint64          implicit_limit;

   // Data output format.
   uint8<OutputFormat> output_format;

   // Expected result cardinality.
   uint8<Cardinality> expected_cardinality;

   // Command text.
   string          command_text;
+
+  // State data descriptor ID.
+  uuid            state_typedesc_id;
+
+  // Encoded state data.
+  bytes           state_data;
 };

 struct Execute {
   // Message type ('O').
   uint8           mtype = 0x4f;

   // Length of message contents in bytes,
   // including self.
   uint32          message_length;

   // A set of message headers.
   uint16          num_headers;
   Header          headers[num_headers];

   // A bit mask of allowed capabilities.
   uint64<Capability> allowed_capabilities;

   // A bit mask of query options.
   uint64<CompilationFlag> compilation_flags;

   // Implicit LIMIT clause on returned sets.
   uint64          implicit_limit;

   // Data output format.
   uint8<OutputFormat> output_format;

   // Expected result cardinality.
   uint8<Cardinality> expected_cardinality;

   // Command text.
   string          command_text;
+
+  // State data descriptor ID.
+  uuid            state_typedesc_id;
+
+  // Encoded state data.
+  bytes           state_data;

   // Argument data descriptor ID.
   uuid            input_typedesc_id;

   // Output data descriptor ID.
   uuid            output_typedesc_id;

   // Encoded argument data.
   bytes           arguments;
 };

[fantix]

UPDATE 3

We would like to drop the asynchronous ParameterStatus_SessionStateDescription, because the state data descriptor should be a synchronous message sent when needed, just like the current CommandDataDescription message.

We will add a new message StateDataDescription:

struct StateDataDescription {
  // Message type ('s').
  uint8           mtype = 0x73;

  // Length of message contents in bytes,
  // including self.
  uint32          message_length;

  // State descriptor ID.
  uuid            typedesc_id;

  // State descriptor.
  bytes           typedesc;
};

This message will be sent when:

1. state_typedesc_id in Parse mismatches the state id on the server-side.

StateDataDescription will be returned from the server together with a StateMismatchError in an ErrorResponse message.

The client bindings could use an always-invalid state type id FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF in Parse at the very beginning in order to get an initial state data descriptor to start encoding state if set, and ignore the expected error. This means the very first query() in a client may issue 2 Parse messages, one to get the state data descriptor, another to get the input data descriptor (if input is set & cache is empty).

In other cases, the error should be retried upon re-encoding the same state with the new state data descriptor, until succees or encoding error.

The REPL would do the same smart retrying, but doesn't need the initial Parse for state data descriptor because currently the REPL only uses the state returned from the server.

2. state_typedesc_id in Execute mismatches the state id on the server-side.

StateDataDescription will be returned from the server together with a StateMismatchError in an ErrorResponse message, if the state type id mismatch is the only error; or both StateDataDescription and CommandDataDescription messages will be returned from the server if both state type id and input type id mismatch, followed by a InputDataError in an ErrorResponse message.

Likewise, the client bindings could try re-encoding the state with the codecs built from the updated descriptor, and retry Execute, just like dealing with the input arguments.

[fantix]

or both StateDataDescription and CommandDataDescription messages will be returned from the server if both state type id and input type id mismatch, followed by a InputDataError in an ErrorResponse message.

This is actually not going to happen - because Execute might have to compile the command to know the proper input type id, and compilation needs a decoded state.