@tdxvolt/volt-client-grpc 0.20.31 → 0.20.32

package/lib/index.cjs

@@ -1770,6 +1770,12 @@ service SyncAPI {
   // Watch synapse paths for changes.
   rpc WatchSynapsePath(stream WatchSynapsePathRequest) returns (stream WatchSynapsePathResponse);
 
+  // Get the state of a synapse document on this Volt. Reports whether the content this Volt holds matches the \`__hash\` advertised in the synapse metadata.
+  rpc GetSynapseDocumentState(GetSynapseDocumentStateRequest) returns (GetSynapseDocumentStateResponse);
+
+  // Watch synapse documents for state changes. The server sends the current state of every watched document before any subsequent transitions, so a watcher started after content lands does not miss it.
+  rpc WatchSynapseDocumentState(stream WatchSynapseDocumentStateRequest) returns (stream WatchSynapseDocumentStateResponse);
+
   // Write a single value to a given synapse JSON path.
   rpc WriteSynapsePath(WriteSynapsePathRequest) returns (WriteSynapsePathResponse);
 
@@ -1980,8 +1986,8 @@ message SetSynapseDocumentMetadataRequest {
   // Any additional application-specific JSON to attach to the document.
   string json = 4;
 
-  // Set to true when the document content is already present (content-first) or the document is intentionally empty, so the server bootstraps \`__hash\` immediately. Leave false (the default) when content will be written after this call.
-  bool content_ready = 6;
+  // Set to true to publish \`__hash\` immediately, because the content is already present (content-first) or the document is intentionally empty. Leave false (the default) when content will be written after this call, in which case the server publishes \`__hash\` once that content arrives. This is creator intent at create time; it says nothing about whether other Volts hold the content (see GetSynapseDocumentState).
+  bool publish_hash = 6;
 
   // For blob documents, the content hash to bind. The server verifies the blob is stored (or the hash is sha256 of empty bytes) and writes \`__hash\`. Omit for a metadata-first create. Must not be set for map/array/text documents; the server computes those hashes from Yjs content.
   string blob_hash = 7;
@@ -2054,9 +2060,6 @@ message SyncDocumentResponse {
 
 // Parameters to start watching synapse paths. Sent as the first message.
 message WatchSynapsePathStart {
-  // DEPRECATED: Use synapse_id instead.
-  string database_id = 1;
-
   // The id of the synapse that contains the document.
   string synapse_id = 4;
 
@@ -2217,16 +2220,100 @@ message RevertSyncDocumentVersionResponse {
   string version_id = 2;
 }
 
+// The state of a synapse document. \`__hash\` in the synapse metadata says what the content is; this says whether this Volt holds it yet. Metadata replicates independently of content, so a document can be ANNOUNCED here and READY on the Volt that produced it.
+enum SynapseDocumentState {
+  SYNAPSE_DOCUMENT_STATE_UNKNOWN = 0;
+
+  // No metadata entry for this document on this Volt.
+  SYNAPSE_DOCUMENT_STATE_ABSENT = 1;
+
+  // Metadata entry exists but no \`__hash\` has been published yet, so no content has been committed. See SetSynapseDocumentMetadata.publish_hash.
+  SYNAPSE_DOCUMENT_STATE_DRAFT = 2;
+
+  // \`__hash\` is published but the content this Volt holds does not match it. The content is still in flight; wait for READY before reading it.
+  SYNAPSE_DOCUMENT_STATE_ANNOUNCED = 3;
+
+  // The content this Volt holds matches \`__hash\`. The document can be read.
+  SYNAPSE_DOCUMENT_STATE_READY = 4;
+
+  // The metadata entry was removed.
+  SYNAPSE_DOCUMENT_STATE_DELETED = 5;
+}
+
+message GetSynapseDocumentStateRequest {
+  // The id of the synapse that contains the document.
+  string synapse_id = 1;
+
+  // The id of the document to query.
+  string document_id = 2;
+}
+
+message GetSynapseDocumentStateResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The state of the document.
+  SynapseDocumentState state = 2;
+
+  // The content hash advertised in the synapse metadata (\`__hash\`). Empty for ABSENT and DRAFT documents.
+  string hash = 3;
+
+  // The content hash this Volt actually holds. Empty when no content has landed here yet. Equal to \`hash\` when the state is READY.
+  string local_hash = 4;
+}
+
+// Parameters to start watching synapse document state. Sent as the first message.
+message WatchSynapseDocumentStateStart {
+  // The id of the synapse to watch.
+  string synapse_id = 1;
+
+  // The ids of the documents to watch. Leave empty to watch every document in the synapse, including documents added after the watch starts.
+  repeated string document_id = 2;
+}
+
+message WatchSynapseDocumentStateRequest {
+  oneof payload {
+    // Start watching; must be sent as the first message.
+    WatchSynapseDocumentStateStart start = 1;
+
+    // Request to stop the watch.
+    bool stop = 2;
+  }
+}
+
+message WatchSynapseDocumentStateUpdate {
+  // The id of the document whose state changed.
+  string document_id = 1;
+
+  SynapseDocumentState state = 2;
+
+  // The content hash advertised in the synapse metadata (\`__hash\`).
+  string hash = 3;
+
+  // The content hash this Volt actually holds.
+  string local_hash = 4;
+}
+
+message WatchSynapseDocumentStateResponse {
+  oneof result {
+    // Details of any error that occurred on the call.
+    tdx.volt_api.volt.v1.Status status = 1;
+
+    // A document state update.
+    WatchSynapseDocumentStateUpdate update = 2;
+  }
+}
+
 message HasSynapseBlobRequest {
   // The id of the synapse that stores the blob.
   string synapse_id = 1;
 
-  // sha256 of the raw file bytes, encoded as unpadded base64url (same family
-  // as VoltDrive content hashes).
+  // SHA-256 of the raw file bytes, encoded as unpadded base64url.
   string hash = 2;
 }
 
 message HasSynapseBlobResponse {
+  // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
 
   // True if a blob with this hash is already stored.
@@ -2234,6 +2321,7 @@ message HasSynapseBlobResponse {
 }
 
 message PutSynapseBlobStart {
+  // The id of the synapse that stores the blob.
   string synapse_id = 1;
 
   // Expected sha256 (base64url) of the concatenated payload bytes.
@@ -2264,13 +2352,20 @@ message PutSynapseBlobResponse {
 }
 
 message GetSynapseBlobRequest {
+  // The id of the synapse that stores the blob.
   string synapse_id = 1;
+
+  // SHA-256 of the raw file bytes, encoded as unpadded base64url.
   string hash = 2;
 }
 
 message GetSynapseBlobResponse {
+  // The next chunk of blob data or details of any error that occurred on the call.
   oneof payload {
+    // The next chunk of blob data.
     bytes block = 1;
+
+    // Details of any error that occurred on the call.
     tdx.volt_api.volt.v1.Status status = 2;
   }
 }
@@ -2648,6 +2743,9 @@ message VoltParameters {
 
   // Optional per-method gRPC rate limits (see GrpcRpcRateLimit). Keyed by peer identity or fingerprint.
   repeated GrpcRpcRateLimit grpc_rpc_rate_limit = 57;
+
+  // Deadline in milliseconds for outbound unary gRPC calls made by this Volt (relay, synapse, mirroring, drive and DID registry calls). If unset or zero, the built-in defaults are used.
+  uint32 grpc_unary_deadline = 58;
 }
 
 message VoltEndpoint {
@@ -7091,6 +7189,10 @@ class VoltClient extends EventEmitter__default["default"] {
     );
   }
 
+  GetSynapseDocumentState(request) {
+    return unaryCallInternal.call(this, "GetSynapseDocumentState", request);
+  }
+
   SaveSynapse(request) {
     return unaryCallInternal.call(this, "SaveSynapse", request);
   }
@@ -7114,6 +7216,16 @@ class VoltClient extends EventEmitter__default["default"] {
     return syncDocumentCall.start(grpcClient, request);
   }
 
+  WatchSynapseDocumentState(request) {
+    this.getVoltAPIClient();
+
+    new GRPCCall(
+      this,
+      "WatchSynapseDocumentState",
+      "METHOD_TYPE_BIDI"
+    );
+  }
+
   WatchSynapsePath(request) {
     const grpcClient = this.getVoltAPIClient();
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.20.31",
+  "version": "0.20.32",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {
@@ -33,8 +33,8 @@
   "author": "toby.ealden@gmail.com",
   "license": "ISC",
   "dependencies": {
-    "@tdxvolt/volt-client-web": "^0.20.31",
-    "@tdxvolt/volt-utility": "^0.20.31",
+    "@tdxvolt/volt-client-web": "^0.20.32",
+    "@tdxvolt/volt-utility": "^0.20.32",
     "debug": "^4.1.1",
     "ip": "^1.1.5",
     "jsonwebtoken": "^8.5.1",

package/src/volt-client.js

@@ -751,6 +751,10 @@ export class VoltClient extends EventEmitter {
     );
   }
 
+  GetSynapseDocumentState(request) {
+    return unaryCallInternal.call(this, "GetSynapseDocumentState", request);
+  }
+
   SaveSynapse(request) {
     return unaryCallInternal.call(this, "SaveSynapse", request);
   }
@@ -774,6 +778,16 @@ export class VoltClient extends EventEmitter {
     return syncDocumentCall.start(grpcClient, request);
   }
 
+  WatchSynapseDocumentState(request) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const watchDocumentStateCall = new GRPCCall(
+      this,
+      "WatchSynapseDocumentState",
+      "METHOD_TYPE_BIDI"
+    );
+  }
+
   WatchSynapsePath(request) {
     const grpcClient = this.getVoltAPIClient();
 

package/src/volt-proto-literals.js

@@ -1222,6 +1222,12 @@ service SyncAPI {
   // Watch synapse paths for changes.
   rpc WatchSynapsePath(stream WatchSynapsePathRequest) returns (stream WatchSynapsePathResponse);
 
+  // Get the state of a synapse document on this Volt. Reports whether the content this Volt holds matches the \`__hash\` advertised in the synapse metadata.
+  rpc GetSynapseDocumentState(GetSynapseDocumentStateRequest) returns (GetSynapseDocumentStateResponse);
+
+  // Watch synapse documents for state changes. The server sends the current state of every watched document before any subsequent transitions, so a watcher started after content lands does not miss it.
+  rpc WatchSynapseDocumentState(stream WatchSynapseDocumentStateRequest) returns (stream WatchSynapseDocumentStateResponse);
+
   // Write a single value to a given synapse JSON path.
   rpc WriteSynapsePath(WriteSynapsePathRequest) returns (WriteSynapsePathResponse);
 
@@ -1432,8 +1438,8 @@ message SetSynapseDocumentMetadataRequest {
   // Any additional application-specific JSON to attach to the document.
   string json = 4;
 
-  // Set to true when the document content is already present (content-first) or the document is intentionally empty, so the server bootstraps \`__hash\` immediately. Leave false (the default) when content will be written after this call.
-  bool content_ready = 6;
+  // Set to true to publish \`__hash\` immediately, because the content is already present (content-first) or the document is intentionally empty. Leave false (the default) when content will be written after this call, in which case the server publishes \`__hash\` once that content arrives. This is creator intent at create time; it says nothing about whether other Volts hold the content (see GetSynapseDocumentState).
+  bool publish_hash = 6;
 
   // For blob documents, the content hash to bind. The server verifies the blob is stored (or the hash is sha256 of empty bytes) and writes \`__hash\`. Omit for a metadata-first create. Must not be set for map/array/text documents; the server computes those hashes from Yjs content.
   string blob_hash = 7;
@@ -1506,9 +1512,6 @@ message SyncDocumentResponse {
 
 // Parameters to start watching synapse paths. Sent as the first message.
 message WatchSynapsePathStart {
-  // DEPRECATED: Use synapse_id instead.
-  string database_id = 1;
-
   // The id of the synapse that contains the document.
   string synapse_id = 4;
 
@@ -1669,16 +1672,100 @@ message RevertSyncDocumentVersionResponse {
   string version_id = 2;
 }
 
+// The state of a synapse document. \`__hash\` in the synapse metadata says what the content is; this says whether this Volt holds it yet. Metadata replicates independently of content, so a document can be ANNOUNCED here and READY on the Volt that produced it.
+enum SynapseDocumentState {
+  SYNAPSE_DOCUMENT_STATE_UNKNOWN = 0;
+
+  // No metadata entry for this document on this Volt.
+  SYNAPSE_DOCUMENT_STATE_ABSENT = 1;
+
+  // Metadata entry exists but no \`__hash\` has been published yet, so no content has been committed. See SetSynapseDocumentMetadata.publish_hash.
+  SYNAPSE_DOCUMENT_STATE_DRAFT = 2;
+
+  // \`__hash\` is published but the content this Volt holds does not match it. The content is still in flight; wait for READY before reading it.
+  SYNAPSE_DOCUMENT_STATE_ANNOUNCED = 3;
+
+  // The content this Volt holds matches \`__hash\`. The document can be read.
+  SYNAPSE_DOCUMENT_STATE_READY = 4;
+
+  // The metadata entry was removed.
+  SYNAPSE_DOCUMENT_STATE_DELETED = 5;
+}
+
+message GetSynapseDocumentStateRequest {
+  // The id of the synapse that contains the document.
+  string synapse_id = 1;
+
+  // The id of the document to query.
+  string document_id = 2;
+}
+
+message GetSynapseDocumentStateResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The state of the document.
+  SynapseDocumentState state = 2;
+
+  // The content hash advertised in the synapse metadata (\`__hash\`). Empty for ABSENT and DRAFT documents.
+  string hash = 3;
+
+  // The content hash this Volt actually holds. Empty when no content has landed here yet. Equal to \`hash\` when the state is READY.
+  string local_hash = 4;
+}
+
+// Parameters to start watching synapse document state. Sent as the first message.
+message WatchSynapseDocumentStateStart {
+  // The id of the synapse to watch.
+  string synapse_id = 1;
+
+  // The ids of the documents to watch. Leave empty to watch every document in the synapse, including documents added after the watch starts.
+  repeated string document_id = 2;
+}
+
+message WatchSynapseDocumentStateRequest {
+  oneof payload {
+    // Start watching; must be sent as the first message.
+    WatchSynapseDocumentStateStart start = 1;
+
+    // Request to stop the watch.
+    bool stop = 2;
+  }
+}
+
+message WatchSynapseDocumentStateUpdate {
+  // The id of the document whose state changed.
+  string document_id = 1;
+
+  SynapseDocumentState state = 2;
+
+  // The content hash advertised in the synapse metadata (\`__hash\`).
+  string hash = 3;
+
+  // The content hash this Volt actually holds.
+  string local_hash = 4;
+}
+
+message WatchSynapseDocumentStateResponse {
+  oneof result {
+    // Details of any error that occurred on the call.
+    tdx.volt_api.volt.v1.Status status = 1;
+
+    // A document state update.
+    WatchSynapseDocumentStateUpdate update = 2;
+  }
+}
+
 message HasSynapseBlobRequest {
   // The id of the synapse that stores the blob.
   string synapse_id = 1;
 
-  // sha256 of the raw file bytes, encoded as unpadded base64url (same family
-  // as VoltDrive content hashes).
+  // SHA-256 of the raw file bytes, encoded as unpadded base64url.
   string hash = 2;
 }
 
 message HasSynapseBlobResponse {
+  // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
 
   // True if a blob with this hash is already stored.
@@ -1686,6 +1773,7 @@ message HasSynapseBlobResponse {
 }
 
 message PutSynapseBlobStart {
+  // The id of the synapse that stores the blob.
   string synapse_id = 1;
 
   // Expected sha256 (base64url) of the concatenated payload bytes.
@@ -1716,13 +1804,20 @@ message PutSynapseBlobResponse {
 }
 
 message GetSynapseBlobRequest {
+  // The id of the synapse that stores the blob.
   string synapse_id = 1;
+
+  // SHA-256 of the raw file bytes, encoded as unpadded base64url.
   string hash = 2;
 }
 
 message GetSynapseBlobResponse {
+  // The next chunk of blob data or details of any error that occurred on the call.
   oneof payload {
+    // The next chunk of blob data.
     bytes block = 1;
+
+    // Details of any error that occurred on the call.
     tdx.volt_api.volt.v1.Status status = 2;
   }
 }
@@ -2100,6 +2195,9 @@ message VoltParameters {
 
   // Optional per-method gRPC rate limits (see GrpcRpcRateLimit). Keyed by peer identity or fingerprint.
   repeated GrpcRpcRateLimit grpc_rpc_rate_limit = 57;
+
+  // Deadline in milliseconds for outbound unary gRPC calls made by this Volt (relay, synapse, mirroring, drive and DID registry calls). If unset or zero, the built-in defaults are used.
+  uint32 grpc_unary_deadline = 58;
 }
 
 message VoltEndpoint {