@serve.zone/interfaces 32.26.0 → 32.27.0

package/ts/requests/node.ts

@@ -5,6 +5,7 @@ import type { IClusterNode, INodeAction, INodeMetricsSample, TNodeActionName } f
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
+import type { IPlatformDatabaseEndpoint } from '../platform/database.js';
 import type {
   INodeCredentialMetadata,
   INodeCredentialMutationPreconditions,
@@ -315,6 +316,38 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreObjectStorageEndpoint e
   };
 }
 
+/**
+ * An administrator states where a workload on one node reaches the node's Corestore database:
+ * `IClusterNode.data.corestoreDatabase`.
+ *
+ * A request of its own, separate from `setClusterNodeCorestoreEndpoint` and
+ * `setClusterNodeCorestoreObjectStorageEndpoint`: each sets one fact and never touches the others.
+ *
+ * Cloudly validates it with `validatePlatformDatabaseEndpoint` before it writes and takes the
+ * node's own real-write fence inside the writing transaction, as for the other two endpoints.
+ * `database: null` clears it, which is the same fact as never having set one: no database
+ * credential can be published for a binding on this node. A changed endpoint changes the binding
+ * request of every database binding placed on the node, so each is granted and published again,
+ * addressed to the new endpoint. The endpoint says where, never with what — no credential travels
+ * in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint
+> {
+  method: 'setClusterNodeCorestoreDatabaseEndpoint';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** The node's database endpoint, or `null` to state that it has none. */
+    database: IPlatformDatabaseEndpoint | null;
+  };
+  response: {
+    /** The node as it now stands, so a caller needs no second read to see what it set. */
+    node: IClusterNode;
+  };
+}
+
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_Cloudly_CreateNodeAction

package/ts/runtime.corestore.ts

@@ -21,6 +21,11 @@ import {
   validateObjectStorageRetentionIntent,
 } from './platform/objectstorageretention.js';
 import { validatePlatformObjectStorageBucketName } from './platform/objectstorage.js';
+import type { IPlatformDatabaseEndpoint } from './platform/database.js';
+import {
+  formatPlatformDatabaseEndpointHost,
+  validatePlatformDatabaseEndpoint,
+} from './platform/database.js';
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
@@ -415,6 +420,14 @@ interface ICorestoreCredentialBindingRequestBase {
 export type TCorestoreCredentialBindingRequest =
   | ICorestoreCredentialBindingRequestBase & {
       capability: 'database';
+      /**
+       * Where a workload reaches the database: the `corestoreDatabase` of the node the binding is
+       * placed on. Corestore addresses the binding's connection values to it, and it is part of
+       * the request digest, so a changed endpoint is a changed request that is granted and
+       * published again. A request without it names no address a workload can reach; whether one
+       * is admitted is the provider's decision, never a default this contract supplies.
+       */
+      endpoint?: IPlatformDatabaseEndpoint;
     }
   | ICorestoreCredentialBindingRequestBase & {
       capability: 'objectstorage';
@@ -441,7 +454,7 @@ export const validateCorestoreCredentialBindingRequest = (
     'environment',
   ];
   if (requestArg.capability === 'database') {
-    if (!hasExactKeys(requestArg, baseKeys)) {
+    if (!hasExactKeys(requestArg, baseKeys, ['endpoint'])) {
       return ['corestore database credential binding request must use its exact schema'];
     }
   } else if (requestArg.capability === 'objectstorage') {
@@ -462,6 +475,12 @@ export const validateCorestoreCredentialBindingRequest = (
     || requestArg.environment !== corestoreCredentialEnvironment) {
     errors.push('corestore credential binding request constants must be canonical');
   }
+  if (requestArg.capability === 'database' && requestArg.endpoint !== undefined) {
+    errors.push(...validatePlatformDatabaseEndpoint(
+      requestArg.endpoint,
+      'corestore database credential binding request endpoint',
+    ));
+  }
   if (requestArg.capability === 'objectstorage') {
     errors.push(...validatePlatformObjectStorageBucketName(
       requestArg.bucketName,
@@ -489,6 +508,9 @@ export const createCorestoreCredentialBindingRequestDigestInput = (
     providerConfigId: requestArg.providerConfigId,
     managementScope: requestArg.managementScope,
     environment: requestArg.environment,
+    ...(requestArg.capability === 'database' && requestArg.endpoint
+      ? { endpoint: { host: requestArg.endpoint.host, port: requestArg.endpoint.port } }
+      : {}),
     ...(requestArg.capability === 'objectstorage'
       ? {
           bucketName: requestArg.bucketName,
@@ -727,6 +749,91 @@ export const validateCorestoreDatabaseCredentialMaterial = (
   return errors;
 };
 
+/** What a database binding's connection values are made of, besides where the database is. */
+export interface ICorestoreDatabaseCredentialIdentity {
+  databaseName: string;
+  username: string;
+  password: string;
+}
+
+/**
+ * The connection URI of one database binding, addressed to `endpointArg`:
+ * `mongodb://<username>:<password>@<host>:<port>/<databaseName>?authSource=<databaseName>&directConnection=true`,
+ * the username, password and database name URI-component encoded, an IPv6 host in brackets.
+ * This is the one form Corestore writes and Cloudly checks, so the two can never disagree.
+ */
+export const createCorestoreDatabaseUri = (
+  endpointArg: IPlatformDatabaseEndpoint,
+  identityArg: ICorestoreDatabaseCredentialIdentity,
+): string => {
+  const endpointErrors = validatePlatformDatabaseEndpoint(endpointArg);
+  if (endpointErrors.length > 0) throw new Error(endpointErrors[0]);
+  const query = new URLSearchParams({
+    authSource: identityArg.databaseName,
+    directConnection: 'true',
+  });
+  return `mongodb://${encodeURIComponent(identityArg.username)}:`
+    + `${encodeURIComponent(identityArg.password)}@`
+    + `${formatPlatformDatabaseEndpointHost(endpointArg.host)}:${endpointArg.port}`
+    + `/${encodeURIComponent(identityArg.databaseName)}?${query.toString()}`;
+};
+
+/**
+ * The eleven connection values of one database binding, addressed to `endpointArg`: the three URI
+ * aliases from `createCorestoreDatabaseUri()`, `MONGODB_HOST` the endpoint host without brackets,
+ * `MONGODB_PORT` its port in decimal, and the database, username and password under both alias
+ * families. Throws the first reason the result would not be valid material; nothing is defaulted.
+ */
+export const createCorestoreDatabaseCredentialValues = (
+  endpointArg: IPlatformDatabaseEndpoint,
+  identityArg: ICorestoreDatabaseCredentialIdentity,
+): TCorestoreDatabaseCredentialValues => {
+  const uri = createCorestoreDatabaseUri(endpointArg, identityArg);
+  const values: TCorestoreDatabaseCredentialValues = {
+    MONGODB_URI: uri,
+    MONGODB_URL: uri,
+    MONGO_URL: uri,
+    MONGODB_HOST: endpointArg.host,
+    MONGODB_PORT: String(endpointArg.port),
+    MONGODB_DATABASE: identityArg.databaseName,
+    MONGO_DBNAME: identityArg.databaseName,
+    MONGODB_USERNAME: identityArg.username,
+    MONGO_DBUSER: identityArg.username,
+    MONGODB_PASSWORD: identityArg.password,
+    MONGO_DBPASS: identityArg.password,
+  };
+  const errors = validateCorestoreDatabaseCredentialMaterial({ capability: 'database', values });
+  if (errors.length > 0) throw new Error(errors[0]);
+  return values;
+};
+
+/**
+ * Validates database material and that it is addressed to `endpointArg`: every value is the one
+ * `createCorestoreDatabaseCredentialValues()` derives from the endpoint and the material's own
+ * database name, username and password. Material a provider addressed to any other host or port —
+ * its own public host above all — is refused by name.
+ */
+export const validateCorestoreDatabaseCredentialMaterialEndpoint = (
+  materialArg: unknown,
+  endpointArg: IPlatformDatabaseEndpoint,
+): string[] => {
+  const errors = validateCorestoreDatabaseCredentialMaterial(materialArg);
+  if (errors.length > 0) return errors;
+  const endpointErrors = validatePlatformDatabaseEndpoint(endpointArg);
+  if (endpointErrors.length > 0) return endpointErrors;
+  const values = (materialArg as ICorestoreDatabaseCredentialPlaintextMaterial).values;
+  const expected = createCorestoreDatabaseCredentialValues(endpointArg, {
+    databaseName: values.MONGODB_DATABASE,
+    username: values.MONGODB_USERNAME,
+    password: values.MONGODB_PASSWORD,
+  });
+  const mismatched = corestoreDatabaseCredentialKeys
+    .filter((keyArg) => values[keyArg] !== expected[keyArg]);
+  return mismatched.length > 0
+    ? [`corestore database credential ${mismatched.join(', ')} must be addressed to the binding endpoint`]
+    : [];
+};
+
 export const validateCorestoreObjectStorageCredentialMaterial = async (
   materialArg: unknown,
   retentionExpectationArg?: IObjectStorageRetentionEvidenceExpectation,