@tdxvolt/volt-client-grpc 0.20.31 → 0.20.34

package/lib/index.cjs

@@ -1043,9 +1043,12 @@ import "tdx/volt_api/volt/v1/volt.proto";
 
 // The Drive API allows clients to create and manage Volt Drive resources.
 service DriveAPI {
-  // Create or update a drive connection resource.
-  // This is a privileged API call and requires volt:api-call / volt:save-drive-instance permission.
-  rpc SaveDriveInstance(SaveDriveInstanceRequest) returns (SaveDriveInstanceResponse);
+    // Create or update a drive connection resource.
+    // This is a privileged API call and requires volt:api-call / volt:save-drive-instance permission.
+    rpc SaveDriveInstance(SaveDriveInstanceRequest) returns (SaveDriveInstanceResponse);
+
+    // Stream the FolderSync status of the drive instances on this Volt that host \`synapse_id\`. Busy means the local ingest/materialise queue is working. If there is no instance on this Volt, the stream reports absent.
+    rpc WatchDriveInstanceStatus(stream WatchDriveInstanceStatusRequest) returns (stream WatchDriveInstanceStatusResponse);
 }
 
 message SaveDriveInstanceRequest {
@@ -1106,6 +1109,47 @@ message SaveDriveInstanceResponse {
   Resource resource = 2;
 }
 
+enum DriveInstanceState {
+  // No drive instance for this synapse is running on this Volt, so this Volt has nothing to say about its sync progress.
+  DRIVE_INSTANCE_STATE_ABSENT = 0;
+
+  // An instance is running with nothing queued.
+  DRIVE_INSTANCE_STATE_IDLE = 1;
+
+  // Files are queued, in flight, or the initial scan is running.
+  DRIVE_INSTANCE_STATE_BUSY = 2;
+}
+
+// FolderSync work on this Volt for a drive synapse.
+message DriveInstanceStatus {
+  DriveInstanceState state = 1;
+
+  // Distinct files admitted to the operation currently underway, summed over every instance on this Volt that hosts the synapse. Grows as more work is discovered and never shrinks mid-operation. Zero once the drive settles.
+  uint32 total_count = 2;
+
+  // How many of \`total_count\` have reached a terminal state.
+  uint32 completed_count = 3;
+}
+
+message WatchDriveInstanceStatusStart {
+  // The id of the drive synapse (drive database) to watch.
+  string synapse_id = 1;
+}
+
+message WatchDriveInstanceStatusRequest {
+  oneof payload {
+    WatchDriveInstanceStatusStart start = 1;
+    bool stop = 2;
+  }
+}
+
+message WatchDriveInstanceStatusResponse {
+  oneof result {
+    tdx.volt_api.volt.v1.Status status = 1;
+    DriveInstanceStatus update = 2;
+  }
+}
+
 `;
 const file = `syntax = "proto3";
 
@@ -1770,6 +1814,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 +2030,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 +2104,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 +2264,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 +2365,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 +2396,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 +2787,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 {
@@ -3184,6 +3326,14 @@ service VoltAPI {
   // This is a privileged API call and requires volt:api-call / volt:save-http-file-server permission.
   rpc SaveHttpFileServer(SaveHttpFileServerRequest) returns (SaveHttpFileServerResponse);
 
+  // Publish a local filesystem folder over HTTP, optionally via a connected relay.
+  // This is a privileged API call and requires volt:api-call / volt:publish-folder permission. Updating an existing publication additionally requires volt:resource-write on the published-folder resource.
+  // On failure any resource this call created is removed, so a publication is never left half-built. Updates to an existing publication are idempotent: retry the same request to recover from a partial failure.
+  rpc PublishFolder(PublishFolderRequest) returns (PublishFolderResponse);
+
+  // Remove a folder published by PublishFolder. Remote forwarder and OIDC resources are deleted first; the local file-server record is kept if remote cleanup fails so the operation can be retried. DeleteResource on a volt:published-folder resource performs the same remote cleanup.
+  rpc UnpublishFolder(UnpublishFolderRequest) returns (UnpublishFolderResponse);
+
   // Create or update an HTTP forwarder resource.
   // This is a privileged API call and requires volt:api-call / volt:save-http-forwarder permission.
   rpc SaveHttpForwarder(SaveHttpForwarderRequest) returns (SaveHttpForwarderResponse);
@@ -4188,7 +4338,7 @@ message SaveHttpForwarderRequest {
   // Set to indicate the resource attributes should be purged before saving the resource.
   bool purge_attributes = 4;
 
-  // The domain to forward requests to.
+  // FQDN of the public Host this forwarder matches (e.g. wiki.tdxid.com). Do not include a scheme or port. Must not be this Volt's own hostname (use \`path\` for own-host forwarding). Optional when \`path\` is set.
   string domain = 5;
 
   // The host to forward requests to.
@@ -4200,7 +4350,7 @@ message SaveHttpForwarderRequest {
   // Set to indicate that the host header should reflect the proxy domain rather than the target host.
   bool forward_host = 8;
 
-  // Optional path prefix (e.g. "/myapp") for path-based forwarding. May be used on its own (path forwarding on the Volt's own host) or together with \`domain\` (sub-domain + path, e.g. sub.acme.com/myapp). At least one of \`domain\` or \`path\` must be set.
+  // Optional path prefix (e.g. "/myapp") for path-based forwarding. May be used on its own (path forwarding on the Volt's own host) or together with \`domain\` (host + path, e.g. app.acme.com/myapp). At least one of \`domain\` or \`path\` must be set.
   string path = 9;
 
   // When a \`path\` prefix is configured, keep that prefix on the request path when forwarding. The default (false) is standard reverse-proxy behaviour: the prefix is stripped so the target receives the request at its own root (e.g. "/drive/assets/x.js" -> "/assets/x.js"), which suits plain static file servers and root-mounted backends. Set to true for targets that are themselves configured under the same sub-path and expect to receive the prefix. The \`X-Forwarded-Prefix\` header is always sent.
@@ -4209,7 +4359,7 @@ message SaveHttpForwarderRequest {
   // When true, incoming HTTP requests to this forwarder must carry a valid authenticated session (established via the OIDC sign-in flow) and pass the policy check before being proxied, except for the public-path and manifest exceptions on \`auth_public_paths\`. Unauthenticated top-level document navigations are redirected to the configured OpenID Provider; other unauthenticated requests receive 401. An authenticated session that fails the policy check receives 403. The Volt session cookie is stripped from the HTTP hop to the target. WebSocket and SSE upgrades are not gated.
   bool auth_enabled = 11;
 
-  // OpenID Provider issuer URL used for discovery (\`<issuer>/.well-known/openid-configuration\`). May be a Volt acting as an OpenID Provider, or any external OIDC provider. Required when \`auth_enabled\` is set.
+  // OpenID Provider issuer URL used for discovery (\`[issuer]/.well-known/openid-configuration\`). May be a Volt acting as an OpenID Provider, or any external OIDC provider. Required when \`auth_enabled\` is set.
   string oidc_issuer = 12;
 
   // OAuth 2.0 client identifier registered with the OpenID Provider.
@@ -4229,6 +4379,10 @@ message SaveHttpForwarderRequest {
 
   // Effective-path patterns that may be fetched without a session (GET/HEAD). A trailing \`/*\` matches descendants on segment boundaries (e.g. \`/icon/*\`). Used for PWA icons and similar public chrome; the manifest itself is allowed via \`Sec-Fetch-Dest: manifest\` and does not need to be listed.
   repeated string auth_public_paths = 18;
+
+  // The identity whose Volt hosts the target \`host\`/\`port\`, i.e. where requests matching this forwarder are tunnelled to. This allows a forwarder to be created on a public Volt (for a named host) while the target server runs on a different Volt that is relay-connected to it. When omitted, the creating identity is used.
+  // The caller must be entitled to target the identity: it must either be the caller's own identity, the Volt handling this request, or an identity that has granted the caller \`volt:resource-write\`.
+  string target_identity = 19;
 }
 
 message SaveHttpForwarderResponse {
@@ -4321,6 +4475,60 @@ message SaveHttpFileServerResponse {
   Resource resource = 2;
 }
 
+message PublishFolderRequest {
+  // Optional name, extra user kinds, and attributes copied onto the local static file server (for example drive:publication-drive).
+  // If \`id\` is set, this call updates the existing published-folder resource with that id; otherwise it creates a new published-folder resource. Updating keeps the loopback port the file server already listens on, and rotates the OIDC client id and secret when \`auth_enabled\` is set, which ends any sign-in sessions established against the previous pair.
+  Resource resource = 1;
+
+  // Local filesystem path to publish. \`~\` is expanded. Must exist and be a directory.
+  string path = 2;
+
+  // FQDN of the public Host to publish on (e.g. wiki.tdxid.com). This is also the HTTP forwarder's \`domain\`. Do not include a scheme or port. Must not be the publish Volt's own hostname. May be changed when updating, in which case the previous address is released.
+  string domain = 3;
+
+  // DID of the relay Volt that owns the public domain. When omitted, the single connected \`volt:volt-link\` with \`volt:relay-exposed\` is used. If several such relays are connected, this field is required. If none are connected, the path is published on this Volt when HTTP forwarding is enabled.
+  string relay_id = 4;
+
+  // When true, visitors must sign in via OIDC on the publish Volt and match an invitee access rule.
+  bool auth_enabled = 5;
+
+  // Emails, email wildcards (e.g. "*@example.com"), or DIDs permitted through the published host when \`auth_enabled\` is set. At least one is required in that case.
+  repeated string invitee = 6;
+
+  // When true, missing paths are rewritten to \`catch_all\` (SPA-style fallback). An empty \`catch_all\` responds with 404.
+  bool catch_all_enabled = 7;
+
+  // Catch-all path, e.g. \`/index.html\` or \`/\`. Used when \`catch_all_enabled\` is set.
+  string catch_all = 8;
+}
+
+message PublishFolderResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The local static file server that represents the publication.
+  Resource resource = 2;
+
+  // Public URL of the published folder.
+  string url = 3;
+
+  // Resource id of the HTTP forwarder on the publish Volt.
+  string forwarder_id = 4;
+
+  // Resource id of the OIDC client, when access is restricted.
+  string oidc_client_id = 5;
+}
+
+message UnpublishFolderRequest {
+  // Resource id of the local file server created by PublishFolder. The resource must have kind \`volt:published-folder\`.
+  string resource_id = 1;
+}
+
+message UnpublishFolderResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+
 message SaveHttpRestApiServerRequest {
   // Details of the resource to save.
   Resource resource = 1;
@@ -6797,6 +7005,10 @@ class VoltClient extends EventEmitter__default["default"] {
     return unaryCallInternal.call(this, "GetSessions", request);
   }
 
+  PublishFolder(request) {
+    return unaryCallInternal.call(this, "PublishFolder", request);
+  }
+
   SaveAccess(request) {
     return unaryCallInternal.call(this, "SaveAccess", request);
   }
@@ -6833,6 +7045,10 @@ class VoltClient extends EventEmitter__default["default"] {
     return unaryCallInternal.call(this, "SignVerify", request);
   }
 
+  UnpublishFolder(request) {
+    return unaryCallInternal.call(this, "UnpublishFolder", request);
+  }
+
   /**
    * VoltAPI - streaming (bidi). Use connect() for Connect stream.
    * Invoke is for relay proxying; returns a duplex stream of InvokeRequest/InvokeResponse.
@@ -7072,6 +7288,16 @@ class VoltClient extends EventEmitter__default["default"] {
     return unaryCallInternal.call(this, "SaveDriveInstance", request);
   }
 
+  WatchDriveInstanceStatus(request) {
+    const grpcClient = this.getVoltAPIClient();
+    const watchDriveInstanceStatusCall = new GRPCCall(
+      this,
+      "WatchDriveInstanceStatus",
+      "METHOD_TYPE_BIDI"
+    );
+    return watchDriveInstanceStatusCall.start(grpcClient, request);
+  }
+
   /**
    * SyncAPI
    */
@@ -7079,6 +7305,10 @@ class VoltClient extends EventEmitter__default["default"] {
     return unaryCallInternal.call(this, "CreateSynapseConnection", request);
   }
 
+  CreateSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "CreateSyncDocumentVersion", request);
+  }
+
   DeleteSynapseConnection(request) {
     return unaryCallInternal.call(this, "DeleteSynapseConnection", request);
   }
@@ -7091,6 +7321,22 @@ class VoltClient extends EventEmitter__default["default"] {
     );
   }
 
+  GetSynapseDocumentState(request) {
+    return unaryCallInternal.call(this, "GetSynapseDocumentState", request);
+  }
+
+  GetSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "GetSyncDocumentVersion", request);
+  }
+
+  ListSyncDocumentVersions(request) {
+    return unaryCallInternal.call(this, "ListSyncDocumentVersions", request);
+  }
+
+  RevertSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "RevertSyncDocumentVersion", request);
+  }
+
   SaveSynapse(request) {
     return unaryCallInternal.call(this, "SaveSynapse", request);
   }
@@ -7114,6 +7360,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.34",
   "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.34",
+    "@tdxvolt/volt-utility": "^0.20.34",
     "debug": "^4.1.1",
     "ip": "^1.1.5",
     "jsonwebtoken": "^8.5.1",

package/src/volt-client.js

@@ -455,6 +455,10 @@ export class VoltClient extends EventEmitter {
     return unaryCallInternal.call(this, "GetSessions", request);
   }
 
+  PublishFolder(request) {
+    return unaryCallInternal.call(this, "PublishFolder", request);
+  }
+
   SaveAccess(request) {
     return unaryCallInternal.call(this, "SaveAccess", request);
   }
@@ -491,6 +495,10 @@ export class VoltClient extends EventEmitter {
     return unaryCallInternal.call(this, "SignVerify", request);
   }
 
+  UnpublishFolder(request) {
+    return unaryCallInternal.call(this, "UnpublishFolder", request);
+  }
+
   /**
    * VoltAPI - streaming (bidi). Use connect() for Connect stream.
    * Invoke is for relay proxying; returns a duplex stream of InvokeRequest/InvokeResponse.
@@ -732,6 +740,16 @@ export class VoltClient extends EventEmitter {
     return unaryCallInternal.call(this, "SaveDriveInstance", request);
   }
 
+  WatchDriveInstanceStatus(request) {
+    const grpcClient = this.getVoltAPIClient();
+    const watchDriveInstanceStatusCall = new GRPCCall(
+      this,
+      "WatchDriveInstanceStatus",
+      "METHOD_TYPE_BIDI"
+    );
+    return watchDriveInstanceStatusCall.start(grpcClient, request);
+  }
+
   /**
    * SyncAPI
    */
@@ -739,6 +757,10 @@ export class VoltClient extends EventEmitter {
     return unaryCallInternal.call(this, "CreateSynapseConnection", request);
   }
 
+  CreateSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "CreateSyncDocumentVersion", request);
+  }
+
   DeleteSynapseConnection(request) {
     return unaryCallInternal.call(this, "DeleteSynapseConnection", request);
   }
@@ -751,6 +773,22 @@ export class VoltClient extends EventEmitter {
     );
   }
 
+  GetSynapseDocumentState(request) {
+    return unaryCallInternal.call(this, "GetSynapseDocumentState", request);
+  }
+
+  GetSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "GetSyncDocumentVersion", request);
+  }
+
+  ListSyncDocumentVersions(request) {
+    return unaryCallInternal.call(this, "ListSyncDocumentVersions", request);
+  }
+
+  RevertSyncDocumentVersion(request) {
+    return unaryCallInternal.call(this, "RevertSyncDocumentVersion", request);
+  }
+
   SaveSynapse(request) {
     return unaryCallInternal.call(this, "SaveSynapse", request);
   }
@@ -774,6 +812,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

@@ -495,9 +495,12 @@ import "tdx/volt_api/volt/v1/volt.proto";
 
 // The Drive API allows clients to create and manage Volt Drive resources.
 service DriveAPI {
-  // Create or update a drive connection resource.
-  // This is a privileged API call and requires volt:api-call / volt:save-drive-instance permission.
-  rpc SaveDriveInstance(SaveDriveInstanceRequest) returns (SaveDriveInstanceResponse);
+    // Create or update a drive connection resource.
+    // This is a privileged API call and requires volt:api-call / volt:save-drive-instance permission.
+    rpc SaveDriveInstance(SaveDriveInstanceRequest) returns (SaveDriveInstanceResponse);
+
+    // Stream the FolderSync status of the drive instances on this Volt that host \`synapse_id\`. Busy means the local ingest/materialise queue is working. If there is no instance on this Volt, the stream reports absent.
+    rpc WatchDriveInstanceStatus(stream WatchDriveInstanceStatusRequest) returns (stream WatchDriveInstanceStatusResponse);
 }
 
 message SaveDriveInstanceRequest {
@@ -558,6 +561,47 @@ message SaveDriveInstanceResponse {
   Resource resource = 2;
 }
 
+enum DriveInstanceState {
+  // No drive instance for this synapse is running on this Volt, so this Volt has nothing to say about its sync progress.
+  DRIVE_INSTANCE_STATE_ABSENT = 0;
+
+  // An instance is running with nothing queued.
+  DRIVE_INSTANCE_STATE_IDLE = 1;
+
+  // Files are queued, in flight, or the initial scan is running.
+  DRIVE_INSTANCE_STATE_BUSY = 2;
+}
+
+// FolderSync work on this Volt for a drive synapse.
+message DriveInstanceStatus {
+  DriveInstanceState state = 1;
+
+  // Distinct files admitted to the operation currently underway, summed over every instance on this Volt that hosts the synapse. Grows as more work is discovered and never shrinks mid-operation. Zero once the drive settles.
+  uint32 total_count = 2;
+
+  // How many of \`total_count\` have reached a terminal state.
+  uint32 completed_count = 3;
+}
+
+message WatchDriveInstanceStatusStart {
+  // The id of the drive synapse (drive database) to watch.
+  string synapse_id = 1;
+}
+
+message WatchDriveInstanceStatusRequest {
+  oneof payload {
+    WatchDriveInstanceStatusStart start = 1;
+    bool stop = 2;
+  }
+}
+
+message WatchDriveInstanceStatusResponse {
+  oneof result {
+    tdx.volt_api.volt.v1.Status status = 1;
+    DriveInstanceStatus update = 2;
+  }
+}
+
 `;
 export const file = `syntax = "proto3";
 
@@ -1222,6 +1266,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 +1482,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 +1556,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 +1716,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 +1817,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 +1848,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 +2239,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 {
@@ -2636,6 +2778,14 @@ service VoltAPI {
   // This is a privileged API call and requires volt:api-call / volt:save-http-file-server permission.
   rpc SaveHttpFileServer(SaveHttpFileServerRequest) returns (SaveHttpFileServerResponse);
 
+  // Publish a local filesystem folder over HTTP, optionally via a connected relay.
+  // This is a privileged API call and requires volt:api-call / volt:publish-folder permission. Updating an existing publication additionally requires volt:resource-write on the published-folder resource.
+  // On failure any resource this call created is removed, so a publication is never left half-built. Updates to an existing publication are idempotent: retry the same request to recover from a partial failure.
+  rpc PublishFolder(PublishFolderRequest) returns (PublishFolderResponse);
+
+  // Remove a folder published by PublishFolder. Remote forwarder and OIDC resources are deleted first; the local file-server record is kept if remote cleanup fails so the operation can be retried. DeleteResource on a volt:published-folder resource performs the same remote cleanup.
+  rpc UnpublishFolder(UnpublishFolderRequest) returns (UnpublishFolderResponse);
+
   // Create or update an HTTP forwarder resource.
   // This is a privileged API call and requires volt:api-call / volt:save-http-forwarder permission.
   rpc SaveHttpForwarder(SaveHttpForwarderRequest) returns (SaveHttpForwarderResponse);
@@ -3640,7 +3790,7 @@ message SaveHttpForwarderRequest {
   // Set to indicate the resource attributes should be purged before saving the resource.
   bool purge_attributes = 4;
 
-  // The domain to forward requests to.
+  // FQDN of the public Host this forwarder matches (e.g. wiki.tdxid.com). Do not include a scheme or port. Must not be this Volt's own hostname (use \`path\` for own-host forwarding). Optional when \`path\` is set.
   string domain = 5;
 
   // The host to forward requests to.
@@ -3652,7 +3802,7 @@ message SaveHttpForwarderRequest {
   // Set to indicate that the host header should reflect the proxy domain rather than the target host.
   bool forward_host = 8;
 
-  // Optional path prefix (e.g. "/myapp") for path-based forwarding. May be used on its own (path forwarding on the Volt's own host) or together with \`domain\` (sub-domain + path, e.g. sub.acme.com/myapp). At least one of \`domain\` or \`path\` must be set.
+  // Optional path prefix (e.g. "/myapp") for path-based forwarding. May be used on its own (path forwarding on the Volt's own host) or together with \`domain\` (host + path, e.g. app.acme.com/myapp). At least one of \`domain\` or \`path\` must be set.
   string path = 9;
 
   // When a \`path\` prefix is configured, keep that prefix on the request path when forwarding. The default (false) is standard reverse-proxy behaviour: the prefix is stripped so the target receives the request at its own root (e.g. "/drive/assets/x.js" -> "/assets/x.js"), which suits plain static file servers and root-mounted backends. Set to true for targets that are themselves configured under the same sub-path and expect to receive the prefix. The \`X-Forwarded-Prefix\` header is always sent.
@@ -3661,7 +3811,7 @@ message SaveHttpForwarderRequest {
   // When true, incoming HTTP requests to this forwarder must carry a valid authenticated session (established via the OIDC sign-in flow) and pass the policy check before being proxied, except for the public-path and manifest exceptions on \`auth_public_paths\`. Unauthenticated top-level document navigations are redirected to the configured OpenID Provider; other unauthenticated requests receive 401. An authenticated session that fails the policy check receives 403. The Volt session cookie is stripped from the HTTP hop to the target. WebSocket and SSE upgrades are not gated.
   bool auth_enabled = 11;
 
-  // OpenID Provider issuer URL used for discovery (\`<issuer>/.well-known/openid-configuration\`). May be a Volt acting as an OpenID Provider, or any external OIDC provider. Required when \`auth_enabled\` is set.
+  // OpenID Provider issuer URL used for discovery (\`[issuer]/.well-known/openid-configuration\`). May be a Volt acting as an OpenID Provider, or any external OIDC provider. Required when \`auth_enabled\` is set.
   string oidc_issuer = 12;
 
   // OAuth 2.0 client identifier registered with the OpenID Provider.
@@ -3681,6 +3831,10 @@ message SaveHttpForwarderRequest {
 
   // Effective-path patterns that may be fetched without a session (GET/HEAD). A trailing \`/*\` matches descendants on segment boundaries (e.g. \`/icon/*\`). Used for PWA icons and similar public chrome; the manifest itself is allowed via \`Sec-Fetch-Dest: manifest\` and does not need to be listed.
   repeated string auth_public_paths = 18;
+
+  // The identity whose Volt hosts the target \`host\`/\`port\`, i.e. where requests matching this forwarder are tunnelled to. This allows a forwarder to be created on a public Volt (for a named host) while the target server runs on a different Volt that is relay-connected to it. When omitted, the creating identity is used.
+  // The caller must be entitled to target the identity: it must either be the caller's own identity, the Volt handling this request, or an identity that has granted the caller \`volt:resource-write\`.
+  string target_identity = 19;
 }
 
 message SaveHttpForwarderResponse {
@@ -3773,6 +3927,60 @@ message SaveHttpFileServerResponse {
   Resource resource = 2;
 }
 
+message PublishFolderRequest {
+  // Optional name, extra user kinds, and attributes copied onto the local static file server (for example drive:publication-drive).
+  // If \`id\` is set, this call updates the existing published-folder resource with that id; otherwise it creates a new published-folder resource. Updating keeps the loopback port the file server already listens on, and rotates the OIDC client id and secret when \`auth_enabled\` is set, which ends any sign-in sessions established against the previous pair.
+  Resource resource = 1;
+
+  // Local filesystem path to publish. \`~\` is expanded. Must exist and be a directory.
+  string path = 2;
+
+  // FQDN of the public Host to publish on (e.g. wiki.tdxid.com). This is also the HTTP forwarder's \`domain\`. Do not include a scheme or port. Must not be the publish Volt's own hostname. May be changed when updating, in which case the previous address is released.
+  string domain = 3;
+
+  // DID of the relay Volt that owns the public domain. When omitted, the single connected \`volt:volt-link\` with \`volt:relay-exposed\` is used. If several such relays are connected, this field is required. If none are connected, the path is published on this Volt when HTTP forwarding is enabled.
+  string relay_id = 4;
+
+  // When true, visitors must sign in via OIDC on the publish Volt and match an invitee access rule.
+  bool auth_enabled = 5;
+
+  // Emails, email wildcards (e.g. "*@example.com"), or DIDs permitted through the published host when \`auth_enabled\` is set. At least one is required in that case.
+  repeated string invitee = 6;
+
+  // When true, missing paths are rewritten to \`catch_all\` (SPA-style fallback). An empty \`catch_all\` responds with 404.
+  bool catch_all_enabled = 7;
+
+  // Catch-all path, e.g. \`/index.html\` or \`/\`. Used when \`catch_all_enabled\` is set.
+  string catch_all = 8;
+}
+
+message PublishFolderResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The local static file server that represents the publication.
+  Resource resource = 2;
+
+  // Public URL of the published folder.
+  string url = 3;
+
+  // Resource id of the HTTP forwarder on the publish Volt.
+  string forwarder_id = 4;
+
+  // Resource id of the OIDC client, when access is restricted.
+  string oidc_client_id = 5;
+}
+
+message UnpublishFolderRequest {
+  // Resource id of the local file server created by PublishFolder. The resource must have kind \`volt:published-folder\`.
+  string resource_id = 1;
+}
+
+message UnpublishFolderResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+
 message SaveHttpRestApiServerRequest {
   // Details of the resource to save.
   Resource resource = 1;