@serve.zone/interfaces 31.2.0 → 31.4.0

package/ts/requests/clusteringress.ts

@@ -0,0 +1,140 @@
+import * as clusterIngressInterfaces from '../data/clusteringress.js';
+import * as plugins from '../plugins.js';
+
+/**
+ * Cloudly hands a cluster's relay the table its ingress serves.
+ *
+ * Cloudly computes it: it is the only party that knows every service, every
+ * ready endpoint, the node address each published port answers on and the
+ * certificate each hostname needs. The relay caches it in memory and serves it
+ * to the ingress; it never authors one.
+ *
+ * The table carries private keys, so this request is secret-bearing: exclude it
+ * from hooks, logs and journals on both sides.
+ */
+export interface IReq_Cloudly_Relay_PushClusterRouteTable extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_PushClusterRouteTable
+> {
+  method: 'pushClusterRouteTable';
+  request: {
+    table: clusterIngressInterfaces.IClusterRouteTable;
+  };
+  response: {
+    /**
+     * The revision the relay now holds. Lower than the pushed revision means
+     * the relay already held a newer table and kept it.
+     */
+    appliedRevision: number;
+  };
+}
+
+/**
+ * The relay asks for the current table.
+ *
+ * Its own session decides which cluster it speaks for, so the request carries no
+ * cluster of its own. `null` means Cloudly has computed no table yet — a fact,
+ * not an empty table, which the relay must not serve as one.
+ */
+export interface IReq_Relay_Cloudly_GetClusterRouteTable extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_GetClusterRouteTable
+> {
+  method: 'getClusterRouteTable';
+  request: Record<string, never>;
+  response: {
+    table: clusterIngressInterfaces.IClusterRouteTable | null;
+  };
+}
+
+/**
+ * The cluster ingress announces itself, and Cloudly decides whether it is one.
+ *
+ * One body for both hops: the ingress sends it to its relay, and the relay
+ * forwards it to Cloudly untouched. The relay cannot decide this — anything that
+ * reaches its listener could ask — so the bearer Cloudly minted into the ingress
+ * workload's assignment environment is what authorizes the registration, and
+ * Cloudly derives which cluster is speaking from the identity tag on the relay's
+ * own session, never from a request field.
+ *
+ * A method, not a connection tag: what a relay knows about its ingress is what
+ * it registered through, which a server owns, rather than a label a client
+ * authored. Only an accepted registration binds the connection; every other
+ * ingress method is answered for that connection alone.
+ *
+ * `revision` is the table the relay holds, so an accepted ingress knows at once
+ * whether it has to fetch one. Cloudly answers `null`: the table is the relay's
+ * to state, not Cloudly's to echo.
+ */
+export interface IReq_Ingress_Relay_Cloudly_RegisterClusterIngress extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Ingress_Relay_Cloudly_RegisterClusterIngress
+> {
+  method: 'registerClusterIngress';
+  request: {
+    /**
+     * Sensitive ephemeral input: exclude the complete request from hooks, logs,
+     * diagnostics and durable journals on every hop. Cloudly mints it into the
+     * ingress workload's assignment environment and verifies it here.
+     */
+    bearer: string;
+    /** The ingress build that registered, for operators reading a relay's log. */
+    version: string;
+    /** The node this ingress runs on, as its assignment names it. */
+    nodeId: string;
+    /** Optional capability names; an ingress that states none states nothing. */
+    capabilities?: string[];
+  };
+  response: {
+    accepted: true;
+    revision: number | null;
+  };
+}
+
+/**
+ * The ingress fetches the table the relay holds.
+ *
+ * `knownRevision` is what the ingress already applied: the relay answers `null`
+ * when it holds nothing newer, so a reconnect costs one round trip and not a
+ * certificate transfer.
+ */
+export interface IReq_Ingress_Relay_GetClusterIngressRouteTable extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Ingress_Relay_GetClusterIngressRouteTable
+> {
+  method: 'getClusterIngressRouteTable';
+  request: {
+    knownRevision: number | null;
+  };
+  response: {
+    table: clusterIngressInterfaces.IClusterRouteTable | null;
+  };
+}
+
+/**
+ * One page of the ingress's day-bucketed counters.
+ *
+ * The same body travels Cloudly → relay and relay → ingress: the relay carries
+ * the request to the ingress that answers it and the page back, adding nothing.
+ * A reader re-reads yesterday and today on every pass, because a day only stops
+ * changing once it has closed.
+ */
+export interface IReq_Any_Ingress_GetClusterTrafficStatistics extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Ingress_GetClusterTrafficStatistics
+> {
+  method: 'getClusterTrafficStatistics';
+  request: {
+    /** Inclusive first UTC calendar day, `YYYY-MM-DD`. */
+    fromDayUtc: string;
+    /** Inclusive last UTC calendar day, `YYYY-MM-DD`. */
+    toDayUtc: string;
+    /** Opaque ingress-owned cursor. */
+    cursor?: string;
+    limit: number;
+  };
+  response: {
+    statistics: clusterIngressInterfaces.IClusterTrafficStatistics[];
+    nextCursor?: string;
+  };
+}

package/ts/requests/index.ts

@@ -7,6 +7,7 @@ import * as baseOsRequests from './baseos.js';
 import * as backupRequests from './backup.js';
 import * as certificateRequests from './certificate.js';
 import * as clusterRequests from './cluster.js';
+import * as clusterIngressRequests from './clusteringress.js';
 import * as configRequests from './config.js';
 import * as coreMailRequests from './coremail.js';
 import * as coreMailAdminRequests from './coremail.admin.js';
@@ -45,6 +46,7 @@ export {
   backupRequests as backup,
   certificateRequests as certificate,
   clusterRequests as cluster,
+  clusterIngressRequests as clusteringress,
   configRequests as config,
   coreMailRequests as coremail,
   coreMailAdminRequests as coremailAdmin,