@tdxvolt/volt-client-grpc 0.1.1 → 0.11.0

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.1",
+  "version": "0.11.0",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {
@@ -47,4 +47,4 @@
     "node-forge": "^0.9.0",
     "uuid": "^8.1.0"
   }
-}
+}

package/protobuf/tdx/volt_api/data/v1/sqlite.proto

@@ -3,19 +3,19 @@ syntax = "proto3";
 package tdx.volt_api.data.v1;
 
 // Just reflect SQLite types for now.
-enum ColumnType {
-  COLUMN_TYPE_UNKNOWN = 0;
-  COLUMN_TYPE_TEXT = 1;
-  COLUMN_TYPE_INTEGER = 2;
-  COLUMN_TYPE_REAL = 3;
-  COLUMN_TYPE_BLOB = 4;
-  COLUMN_TYPE_NULL = 5;
+enum DataType {
+  DATA_TYPE_UNKNOWN = 0;
+  DATA_TYPE_TEXT = 1;
+  DATA_TYPE_INTEGER = 2;
+  DATA_TYPE_REAL = 3;
+  DATA_TYPE_BLOB = 4;
+  DATA_TYPE_NULL = 5;
 }
 
 message Column {
   string name = 1;
   string description = 2;
-  ColumnType type = 3;
+  DataType type = 3;
 }
 
 message Schema {
@@ -25,12 +25,12 @@ message Schema {
 }
 
 message Variant {
-  ColumnType type = 1;
   oneof data {
-    string text = 2;
-    int64 integer = 3;
-    double real = 4;
-    bytes blob = 5;
+    string text = 1;
+    int64 integer = 2;
+    double real = 3;
+    bytes blob = 4;
+    bool null = 5;
   }
 }
 

package/protobuf/tdx/volt_api/data/v1/sqlite_database_api.proto

@@ -4,6 +4,7 @@ package tdx.volt_api.data.v1;
 
 import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/data/v1/sqlite.proto";
+import "tdx/volt_api/volt/v1/volt.proto";
 
 // The Sqlite Database API exposes functions that enable clients to manipulate data in a given Volt database.
 // Use the Sqlite Server API to create the database resource.
@@ -45,8 +46,15 @@ message SqlExecuteRequest {
 
   // This can be used to limit the number of rows returned by `SELECT` statements to avoid overloading a client. It is similar to using 'LIMIT/OFFSET' clauses on the 'SELECT' statement, but this method is easier to manage and the entire result set will be prepared on the Volt, and the client can then page through it by sending successive messages.
   uint32 page_size = 3;
+
+  // The list of values to set for each parameter defined in a database query.
+  // This field is only relevant to 'query' databases, i.e. those with kind `tdx:sqlite-query`.
+  // The values in the list should be in the same order as the parameters defined by the query attributes.
+  // A query may have no parameters defined, in which case leave this field empty.
+  repeated tdx.volt_api.volt.v1.AttributeValue parameter = 4;
 }
 
+// One of the following fields will be present in any given message.
 message SqlExecuteResponse {
   oneof payload {
     // A status will be sent on error.

package/protobuf/tdx/volt_api/data/v1/sqlite_server_api.proto

@@ -30,6 +30,11 @@ message CreateDatabaseRequest {
 
   // The discovery mode of the underlying Volt resource.
   tdx.volt_api.volt.v1.DiscoveryMode discoverable = 6;
+
+  // Alias(es) that can be used to refer to the database rather than the id.
+  // Each alias must be unique to the Volt, this is enforced by the API.
+  // No format restrictions are currently applied to alias, but this may change in future, for the time being it makes sense to stick to alphanumeric characters and '_' or '-'.
+  repeated string alias = 7;
 }
 
 message CreateDatabaseResponse {

package/protobuf/tdx/volt_api/{tunnel → relay}/v1/proxy_api.proto

@@ -1,9 +1,9 @@
 syntax = "proto3";
 
-package tdx.volt_api.tunnel.v1;
+package tdx.volt_api.relay.v1;
 
 // Placeholder API for the proxy.
 // Methods are injected into this service at runtime
-// when a remote volt connects via the TunnelAPI.
+// when a remote volt connects via the RelayAPI.
 service ProxyAPI {
 }

package/protobuf/tdx/volt_api/{tunnel/v1/tunnel_api.proto → relay/v1/relay_api.proto}

@@ -1,16 +1,17 @@
 syntax = "proto3";
 
-package tdx.volt_api.tunnel.v1;
+package tdx.volt_api.relay.v1;
 
 import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/remote.proto";
 import "tdx/volt_api/volt/v1/volt.proto";
 
-service TunnelAPI {
-  // Retrieve the list of Volts available on the tunnel server (Volt-based or cloud-based).
+service RelayAPI {
+  // Retrieve the list of Volts available on the Relay Volt or cloud-based tunnel.
   rpc GetVoltEndpoint(GetVoltEndpointRequest) returns (GetVoltEndpointResponse);
 
   // This is the actual tunnel stream.
+  // Note although this API semantically describes the tunnel stream, it isn't actually implemented anywhere. It is used by client libraries to easily serialise tunnel payloads.
   rpc Tunnel(stream tdx.volt_api.volt.v1.RemoteRequest) returns (stream tdx.volt_api.volt.v1.RemoteResponse);
 
   // This is the tunnel stream for cloud-based tunnels.
@@ -30,12 +31,12 @@ message GetVoltEndpointRequest {
 
 message GetVoltEndpointResponse {
   tdx.volt_api.volt.v1.Status status = 1;
-  repeated tdx.volt_api.volt.v1.VoltEndpoint endpoints = 2;
+  repeated tdx.volt_api.volt.v1.VoltEndpoint endpoint = 2;
 }
 
 message TunnelStart {
   uint32 preferred_port = 1;
-  string local_address = 2;
+  string address = 2;
   string public_key = 3;
   string fingerprint = 4;
   string ca_pem = 5;

package/protobuf/tdx/volt_api/sync/v1/sync.proto

@@ -2,13 +2,56 @@ syntax = "proto3";
 
 package tdx.volt_api.sync.v1;
 
+// Wraps arbitrary protobuf messages, with an index into the `ProtobufSyncConfigurationHeader` to indicate the specific message type this message wraps.
+message ProtobufSyncWrapper {
+  oneof header_lookup {
+    // The index number of the header for this message type in the Volt logger configuration file.
+    uint32 header_index = 1;
+
+    // The name of the header for this message type, will be used to lookup against the `id` field in `ProtobufSyncConfiguration`.
+    // This will incur an overhead in terms of the packet size, but might be preferrable if volume is low or managing the header index is difficult.
+    string header_id = 2;
+  }
+
+  // The message payload, in serialised protobuf binary format.
+  // n.b. the serialisation should **not** be length-prefixed.
+  bytes payload = 3;
+}
+
+// Describes a single message type.
+// A set of one or more of these messages is specified in `ProtobufSyncConfigurationHeader`.
 message ProtobufSyncConfiguration {
+  // Optional id to associate with this configuration.
+  // This can be used in the `header_id` field of `ProtobufSyncWrapper` above to reference the configuration.
+  // If omitted the numerical index of the configuration in `ProtobufSyncConfigurationHeader` will be used instead.
+  string id = 1;
+
   // The actual protobuf definition text.
-  string message_proto = 1;
-  // The name of the message within `message_proto` above that represents the data to be synched.
-  string message_name = 2;
-  // The name of the table within the target database.
-  string table_name = 3;
+  // Copy and paste the source protobuf definition from the `.proto` file.
+  // Only simple protobuf structures are currently supported, e.g. no imports from other packages etc.
+  string message_proto = 2;
+
+  // The name of the message within `message_proto` above that represents the data to be sync'd, e.g. `TCPDumpPacket`.
+  string message_name = 3;
+
+  // The name of the table within the target database into which the message data for this type should be written.
+  string table_name = 4;
+}
+
+// This message is written at the beginning of every file to be ingested using the `protoDbSync` utility.
+// It contains a `header` entry for each message type that may appear in the file.
+// If the `volt logger` command is used, it will create this header automatically based on the configuration it's given.
+message ProtobufSyncConfigurationHeader {
+  // This should ideally be a persistent UUID, at minimum it must be unique within the set of types of file any given instance of `protoDbSync` is processing in a given folder.
+  // It is used to match up orphaned or split packets that might occur when receiving data from a wire, for example, if a log file is rotated midway through a packet arriving on the wire.
+  // This id should persist for the life time of the set of data it describes, i.e. if a wire publication is stopped and restarted at some later point, the same id should be used if possible.
+  string id = 1;
+
+  // The set of possible configurations that can appear in any given protobuf sync data file.
+  // A serialised instance of this message must appear at the top of each data file.
+  // Each subsequent serialised message in the data file must be an instance of `ProtobufSyncWrapper`, and the `header_lookup` field refers to an entry in this list.
+  repeated ProtobufSyncConfiguration configuration = 2;
+
   // Optional maximum size of the serialised messages, this doesn't need to be exact and the default is 64K if omitted.
-  int32 maximum_message_size = 6;
+  int32 maximum_message_size = 3;
 }

package/protobuf/tdx/volt_api/volt/v1/discovery_api.proto

@@ -14,8 +14,8 @@ service DiscoveryAPI {
 }
 
 message DiscoverRequest {
-  // Set to require that only Volts that expose a tunnel be included in the response.
-  bool require_tunnel = 1;
+  // Set to require that only Volts that expose a Relay be included in the response.
+  bool require_relay = 1;
 }
 
 message SignedEndpoint {
@@ -35,5 +35,5 @@ message DiscoverResponse {
   tdx.volt_api.volt.v1.Status status = 1;
 
   // A list of endpoints that match the request criteria.
-  repeated SignedEndpoint endpoints = 2;
+  repeated SignedEndpoint endpoint = 2;
 }

package/protobuf/tdx/volt_api/volt/v1/file_api.proto

@@ -14,9 +14,17 @@ service FileAPI {
   // Get file resource metadata.
   rpc GetFile(GetFileRequest) returns (GetFileResponse);
 
+  // Get the content of a file.
+  // Note this rpc will fail if the size of the file content is greater than 64MB, in which case use DownloadFile instead.
+  rpc GetFileContent(GetFileContentRequest) returns (GetFileContentResponse);
+
   // Get the file resource metadata of all descendants of a given file resource. 
   rpc GetFileDescendants(GetFileDescendantsRequest) returns (GetFileDescendantsResponse);
 
+  // Set the content of a file.
+  // Note this rpc will fail if the size of the file content is greater than 64MB, in which case use UploadFile instead.
+  rpc SetFileContent(SetFileContentRequest) returns (SetFileContentResponse);
+
   // Upload data to a file resource.
   rpc UploadFile(stream UploadFileRequest) returns (stream UploadFileResponse);
 }
@@ -55,6 +63,22 @@ message GetFileResponse {
   File file = 2;
 }
 
+message GetFileContentRequest {
+  // The resource id of the base folder.
+  string resource_id = 1;
+
+  // Optional - the path to the file, relative to the base folder. Required for linked folders.
+  string file_path = 2;
+}
+
+message GetFileContentResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The file content.
+  bytes content = 2;
+}
+
 message GetFileDescendantsRequest {
   // The resource id of the base folder.
   string resource_id = 1;
@@ -74,7 +98,27 @@ message GetFileDescendantsResponse {
   tdx.volt_api.volt.v1.Status status = 1;
 
   // The list of descendants.
-  repeated File descendants = 2;
+  repeated File descendant = 2;
+}
+
+message SetFileContentRequest {
+  // The resource id of the base folder.
+  string resource_id = 1;
+
+  // Optional - the path to the file, relative to the base folder. Required for linked folders.
+  string file_path = 2;
+
+  // Optional store name to use.
+  // If specified, this will be used to extract the extension to set as a resource 'kind', e.g. tdx:ext:json.
+  // If not specified, the extension will be taken from the name of the target resource.
+  string store_name = 3;
+
+  bytes content = 4;
+}
+
+message SetFileContentResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
 }
 
 message UploadFileStart {
@@ -82,6 +126,8 @@ message UploadFileStart {
   string resource_id = 1;
 
   // Optional store name to use.
+  // If specified, this will be used to extract the extension to set as a resource 'kind', e.g. tdx:ext:json.
+  // If not specified, the extension will be taken from the name of the target resource.
   string store_name = 2;
 
   // Optionally set streaming mode.

package/protobuf/tdx/volt_api/volt/v1/spark_api.proto

@@ -0,0 +1,121 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+
+// The Spark API allows clients to start and communicate with Spark VMs.
+service SparkAPI {
+  // Start or connect to a spark VM and establish a long-lived communication channel.
+  rpc Spark(stream SparkRequest) returns (stream SparkResponse);
+
+  // Get details of running spark VMs.
+  rpc GetSpark(GetSparkRequest) returns (GetSparkResponse);
+}
+
+// Start a resource-hosted spark.
+// Provenance is determined from the resource owner.
+message StartSparkResource {
+  // The id of the resource containing the VM byte code.
+  string resource_id = 1;
+
+  // JSON-encoded payload to parameterise the spark.
+  string payload = 2;
+
+  // Envelope signature.
+  string signature = 3;
+}
+
+// Start a spark from byte code included in the payload, along with issuer/developer claims and signature.
+message StartSparkAdhoc {
+  // Ad-hoc byte code of VM to run.
+  bytes byte_code = 1;
+
+  // Verifiable credentials associated with this spark.
+  repeated string credential = 2;
+
+  // Envelope signature.
+  string signature = 3;
+
+  // JSON-encoded payload to parameterise the spark.
+  string payload = 4;
+}
+
+// Send commands and payloads to communicate with a running spark.
+message SparkCommand {
+  // Optional id to associate with this command.
+  // If this is omitted, an id will be assigned and returned in the command acknowledgement.
+  string command_id = 1;
+
+  // The command to send to the spark.
+  string command = 2;
+
+  // The command payload.
+  string payload = 3;
+
+  // Command verifiable credential.
+  string credential = 4;
+
+  // Command signature.
+  string signature = 5;
+}
+
+// The request must contain one of the messages indicated below.
+message SparkRequest {
+  oneof payload {
+    StartSparkResource start_resource = 1;
+    StartSparkAdhoc start_adhoc = 2;
+    SparkCommand command = 3;
+  }
+}
+
+// Receive events and payload from a running spark.
+message SparkData {
+  // The command id to which this data corresponds.
+  string command_id = 1;
+
+  oneof payload {
+    // Acknowledges receipt of a spark command.
+    bool acknowledge = 2;
+
+    // Indicates the command has completed.
+    bool ended = 3;
+
+    // Will contain error details on command failure.
+    string error = 4;
+
+    // Data emitted by a command, usually in stringified JSON format.
+    string data = 5;
+  }
+}
+
+// Details of a spark instance.
+message SparkInstance {
+  // The UUID assigned to the spark instance.
+  string spark_id = 1;
+}
+
+// The response will contain one of the messages indicated below.
+message SparkResponse {
+  oneof payload {
+    // Details of any error that occurred on the call.
+    tdx.volt_api.volt.v1.Status status = 1;
+
+    // Details of the spark instance, sent in response to a start command.
+    SparkInstance spark_instance = 2;
+
+    // Payload data emitted by the spark.
+    SparkData spark_data = 3;
+  }
+}
+
+message GetSparkRequest {
+  string spark_id = 1;
+}
+
+// One of the following fields will be present in the response.
+message GetSparkResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+

package/protobuf/tdx/volt_api/volt/v1/volt.proto

@@ -11,10 +11,10 @@ enum DiscoveryMode {
   // Any bound local identity can discover.
   DISCOVERY_MODE_PUBLIC = 2;
 
-  // Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (tunnelled) clients.
+  // Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (Relayed) clients.
   DISCOVERY_MODE_TRUSTED_GLOBAL = 3;
 
-  // Any bound identity can discover, and the service will be available to local and non-local (tunnelled) clients.
+  // Any bound identity can discover, and the service will be available to local and non-local (Relayed) clients.
   DISCOVERY_MODE_PUBLIC_GLOBAL = 4;
 }
 
@@ -53,8 +53,8 @@ enum ShareMode {
 
 // Represents an outbound connection from a Volt to a remote service that will act as a proxy for that Volt.
 // This enables Volts to bypass firewall and NATs.
-// Example 1 - connection from a Volt to the cloud-based Volt tunnel at volt.tdxcloud.com
-// Example 2 - connection from a Volt to another Volt running on the public internet, such as tdxvolt.com
+// Example 1 - connection from a Volt to the cloud-based Volt tunnel at cloud.tdxvolt.com
+// Example 2 - connection from a Volt to Relay Volt running on the public internet, such as tdxvolt.com
 message ProxyConnection {
   // Unique connection id.
   string id = 1;
@@ -74,7 +74,7 @@ message ProxyConnection {
   // Indicates this connection is currently in use.
   bool connected = 6;
 
-  // Indicates this is a connection to a cloud-based tunnel, rather than to another Volt.
+  // Indicates this is a connection to a cloud-based tunnel, rather than to a Relay Volt.
   bool is_cloud_connection = 7;
 
   // Indicates that this connection will handle HTTP proxying as well as GRPC.
@@ -82,6 +82,9 @@ message ProxyConnection {
 
   // Set to indicate the Volt API itself is not automatically exposed to the connection.
   bool disable_volt_api = 9;
+
+  // Optional challenge that can be presented in the bind phase when initialising the connection.
+  string challenge = 10;
 }
 
 enum SecureMode {
@@ -158,12 +161,12 @@ message VoltParameters {
   // Internal use only.
   bool enable_messaging = 22;
 
-  // Set to indicate this Volt exposes a tunnel interface.
+  // Set to indicate this Volt acts as a Relay.
   // This means this Volt can act as a proxy for other Volts (or in fact any client) that connect to it.
-  bool has_tunnel = 23;
+  bool has_relay = 23;
 
-  // Set to run the tunnel open to any client, i.e. clients can utilise the tunnel without binding to this Volt.
-  bool tunnel_open = 24;
+  // Set to run the Relay open to any client, i.e. clients can utilise the Relay without first binding to this Volt.
+  bool relay_open = 24;
 
   // Determines if the Volt HTTP server is enabled.
   bool enable_http_server = 25;
@@ -190,11 +193,11 @@ message VoltParameters {
   // Indicates that these parameters refer to a connection to a remote Volt rather than a local Volt.
   string connection_id = 32;
 
-  // The certificate authority of the tunnel if this is a remote connection via a tunnel.
-  string tunnel_ca_pem = 33;
+  // The certificate authority of the Relay if this is a remote connection via a Relay.
+  string relay_ca_pem = 33;
 
   // Set to indicate this is a remote connection to a Volt via a cloud tunnel.
-  bool is_cloud_tunnel = 34;
+  bool is_cloud_relay = 34;
 
   // An optional alias that can be used to refer to the Volt rather than the `id` field.
   // This alias must be unique within the scope of the Battery in which the Volt is stored.
@@ -214,11 +217,11 @@ message VoltEndpoint {
   // The actual host/ip the volt is physically running on (might be a local ip if behind firewall).
   string local_address = 4;
 
-  // The global (tunnel) address of the volt. Any given volt may be advertising on more than one tunnel instance. The value given here will depend on the tunnel instance that handled the endpoint query response.
-  string tunnel_address = 5;
+  // The global (Relay) address of the volt. Any given volt may be advertising on more than one Relay instance. The value given here will depend on the Relay instance that handled the endpoint query response.
+  string relay_address = 5;
 
-  // The root certificate of the tunnel instance referred to in `tunnel_address`.
-  string tunnel_ca_pem = 6;
+  // The root certificate of the Relay instance referred to in `relay_address`.
+  string relay_ca_pem = 6;
 
   // The self-signed certificate used by the volt to sign client certificates.
   string ca_pem = 7;
@@ -232,8 +235,10 @@ message VoltEndpoint {
   // The online status of the Volt.
   OnlineStatus online_status = 10;
 
-  // Set to indicate that this Volt exposes a tunnel interface.
-  bool has_tunnel = 11;
+  // Set to indicate that this Volt acts as a Relay.
+  bool has_relay = 11;
+
+  Version api_version = 12;
 }
 
 // Internal use only.
@@ -260,8 +265,8 @@ message ServiceDescription {
   // The id of the server resource that is hosting this service.
   string server_id = 1;
 
-  // The local address of the grpc server hosting this service.
-  string local_address = 2;
+  // The address of the grpc server hosting this service.
+  string address = 2;
 
   // The discovery mode.
   DiscoveryMode discoverable = 4;
@@ -279,7 +284,7 @@ message ServiceDescription {
   string ca_pem = 8;
 
   // Internal use only.
-  repeated MethodDescription methods = 100;
+  repeated MethodDescription method = 100;
 }
 
 // Resource attribute data types.
@@ -316,7 +321,7 @@ message ResourceAttribute {
 
   AttributeDataType data_type = 4;
 
-  repeated AttributeValue values = 5;
+  repeated AttributeValue value = 5;
 }
 
 // Using `major` and `minor` here upsets the GNU C Library, so we add a `version_` prefix.
@@ -347,7 +352,7 @@ message Resource {
   ServiceDescription service_description = 8;
 
   // Attributes assigned to the resource.
-  repeated ResourceAttribute attributes = 9;
+  repeated ResourceAttribute attribute = 9;
 
   // The version of the platform.
   Version platform_version = 10;
@@ -382,10 +387,13 @@ message Resource {
   // The path to the resource store.
   string store = 114;
 
+  // Alias(es) that can be used to refer to the resource rather than the id.
+  // Each alias must be unique to the Volt, this is enforced by the API.
+  // No format restrictions are currently applied to alias, but this may change in future, for the time being it makes sense to stick to alphanumeric characters and '_' or '-'.
   repeated string alias = 115;
 
   // Not yet supported.
-  repeated Resource children = 200;
+  repeated Resource child = 200;
 }
 
 enum IdentityType {
@@ -444,7 +452,7 @@ message IdentityAlias {
 // A Volt identity encompasses a Resource and a set of identity aliases.
 message Identity {
   Resource resource = 1;
-  repeated IdentityAlias aliases = 2;
+  repeated IdentityAlias alias = 2;
 }
 
 enum BindCredentialType {