@serve.zone/interfaces 31.6.0 → 31.7.0

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-09-17 - 31.7.0
+
+### Features
+
+- Add `setClusterNodeCorestoreEndpoint { identity; nodeId; endpoint }`, the admin path for the
+  per-node Corestore endpoint the relay dials. `IClusterNode.data.corestore { endpoint }` has been
+  the contract since 31.6.0, with no request that sets it: an administrator had no way to state
+  where a node's Corestore answers, so a relay serving that cluster had nowhere to dial. Cloudly
+  answers with the node as it now stands, validates the endpoint with `validateClusterNodeCorestore`
+  before writing, fences the node inside the writing transaction so a concurrent deletion conflicts,
+  and pushes the cluster configuration afterwards so connected relays learn the change without
+  reconnecting; `endpoint: null` clears it and states the same fact as never having set one. One
+  field with one validator, deliberately not a node-wide update whose per-field authority nobody
+  defined.
+
 ## 2026-09-17 - 31.6.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '31.6.0',
+    version: '31.7.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/requests/node.d.ts

@@ -150,6 +150,37 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
         ok: boolean;
     };
 }
+/**
+ * An administrator states where one node's Corestore control API answers.
+ *
+ * Corestore is node-local, so one relay serving a whole cluster must be told per node where to
+ * dial; the cluster-local alias every component used while Docker Swarm resolved it is exactly
+ * what stops resolving. The endpoint is control-plane state Cloudly owns and the relay reads,
+ * so an administrator sets it here rather than a relay discovering it.
+ *
+ * Cloudly validates the endpoint with `validateClusterNodeCorestore` before it writes, takes the
+ * node's own real-write fence inside the writing transaction so a concurrent deletion conflicts
+ * instead of leaving an endpoint behind for a node that is gone, and pushes the cluster
+ * configuration afterwards so every connected relay learns the change without reconnecting.
+ *
+ * `endpoint: null` clears it, which is the same fact as never having set one: the node runs no
+ * Corestore the relay may reach, and an inventory for it answers
+ * `errorCode: 'CORESTORE_ENDPOINT_UNKNOWN'` rather than guessing a hostname. The endpoint says
+ * where, never with what — no credential travels in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint> {
+    method: 'setClusterNodeCorestoreEndpoint';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        /** A canonical `http:` or `https:` origin, or `null` to state that this node has none. */
+        endpoint: string | null;
+    };
+    response: {
+        /** The node as it now stands, so a caller needs no second read to see what it set. */
+        node: IClusterNode;
+    };
+}
 export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Spark_Cloudly_SendHeartbeat> {
     method: 'sparkNodeHeartbeat';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "31.6.0",
+  "version": "31.7.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -1118,6 +1118,8 @@ answers with the block Cloudly published, and `disableClusterRelayV1` removes it
 an explicit `relay: null`. The caller names only the cluster: Cloudly derives the origin itself
 from that cluster and its own public hostname, and refuses the request when no DNS zone it
 manages matches the derived name, so a relay name that nothing can publish is never written.
+Both requests push the cluster configuration to the connected relay afterwards, so a relay learns
+the change without reconnecting.
 
 Once its socket is authenticated with `registerCloudlyClientSessionV1`, the relay sends
 `registerClusterRelayV1` carrying `IClusterRelayRegistrationV1`: the relay build, the cluster node
@@ -1828,6 +1830,17 @@ is admitted so putting TLS in front of Corestore needs no contract change. Absen
 runs no Corestore the relay may reach, which an inventory reports as
 `errorCode: 'CORESTORE_ENDPOINT_UNKNOWN'` rather than guessing a hostname.
 
+An administrator sets it with `setClusterNodeCorestoreEndpoint { identity; nodeId; endpoint }`,
+answered by Cloudly with the node as it now stands. Cloudly validates the endpoint with
+`validateClusterNodeCorestore` before it writes, takes the node's own real-write fence inside the
+writing transaction so a concurrent deletion conflicts instead of leaving an endpoint behind for a
+node that is gone, and pushes the cluster configuration afterwards so every connected relay learns
+the change without reconnecting — the same push that
+[the cluster relay block](#cluster-relay-block) uses when an operator enables or disables a relay.
+`endpoint: null` clears it, which states the same fact as never having set one. There is no
+node-wide update request: one field with one validator cannot drift into a generic node mutation
+whose per-field authority nobody defined.
+
 The endpoint says where, never with what. The bearer control token that authorizes every call is
 obtained from Cloudly through `getCorestoreControlCredentialMaterial`, sealed to the X25519
 recipient the relay enrolled with `beginSecretRecipientEnrollment` and

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '31.6.0',
+  version: '31.7.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/requests/node.ts

@@ -203,6 +203,41 @@ export interface IReq_Any_Cloudly_DeleteNodeById extends plugins.typedrequestInt
   };
 }
 
+/**
+ * An administrator states where one node's Corestore control API answers.
+ *
+ * Corestore is node-local, so one relay serving a whole cluster must be told per node where to
+ * dial; the cluster-local alias every component used while Docker Swarm resolved it is exactly
+ * what stops resolving. The endpoint is control-plane state Cloudly owns and the relay reads,
+ * so an administrator sets it here rather than a relay discovering it.
+ *
+ * Cloudly validates the endpoint with `validateClusterNodeCorestore` before it writes, takes the
+ * node's own real-write fence inside the writing transaction so a concurrent deletion conflicts
+ * instead of leaving an endpoint behind for a node that is gone, and pushes the cluster
+ * configuration afterwards so every connected relay learns the change without reconnecting.
+ *
+ * `endpoint: null` clears it, which is the same fact as never having set one: the node runs no
+ * Corestore the relay may reach, and an inventory for it answers
+ * `errorCode: 'CORESTORE_ENDPOINT_UNKNOWN'` rather than guessing a hostname. The endpoint says
+ * where, never with what — no credential travels in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint
+> {
+  method: 'setClusterNodeCorestoreEndpoint';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** A canonical `http:` or `https:` origin, or `null` to state that this node has none. */
+    endpoint: string | null;
+  };
+  response: {
+    /** The node as it now stands, so a caller needs no second read to see what it set. */
+    node: IClusterNode;
+  };
+}
+
 export interface IRequest_Spark_Cloudly_SendHeartbeat extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IRequest_Spark_Cloudly_SendHeartbeat