@oneuptime/common 13.0.7 → 14.0.0

package/UI/Utils/Realtime.ts

@@ -1,4 +1,5 @@
 import { HOST, HTTP_PROTOCOL } from "../Config";
+import API from "./API/API";
 import AnalyticsBaseModel from "../../Models/AnalyticsModels/AnalyticsBaseModel/AnalyticsBaseModel";
 import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import { RealtimeRoute } from "../../ServiceRoute";
@@ -21,14 +22,55 @@ export interface ListenToModelEvent<
   modelId?: ObjectID | undefined;
 }
 
+/*
+ * One subscription a caller holds: what the server has to be asked for (again
+ * after every reconnect) and the handler listening on its room.
+ */
+interface RealtimeSubscription {
+  request: ListenToModelEventJSON;
+  roomId: string;
+  handler: (data: JSONObject) => void;
+}
+
 export default abstract class Realtime {
+  /*
+   * The least time between two refresh-and-reconnects. A reconnect with a
+   * freshly refreshed session that the server still refuses (a cookie that
+   * does not reach the socket, say) must not turn into a reconnect loop; the
+   * next refusal after this long tries again. Far shorter than the 15-minute
+   * access token, so a session that genuinely expires again is still renewed.
+   */
+  public static readonly AUTHENTICATION_RECOVERY_COOLDOWN_IN_MS: number =
+    60 * 1000;
+
   private static socket: Socket;
 
+  /*
+   * Every subscription still wanted, by identity: two callers asking for the
+   * same room are two entries, and each one's stop function removes only its
+   * own. The server forgets a socket's rooms when the connection drops, so
+   * this is what gets re-sent on every (re)connect.
+   */
+  private static subscriptions: Set<RealtimeSubscription> = new Set();
+
+  private static isRecoveringAuthentication: boolean = false;
+
+  private static lastAuthenticationRecoveryAt: number | null = null;
+
   public static init(): void {
     const socket: Socket = SocketIO(new URL(HTTP_PROTOCOL, HOST).toString(), {
       path: RealtimeRoute.toString(),
     });
 
+    // Initial connect and every reconnect: the new connection is in no rooms.
+    socket.on("connect", (): void => {
+      this.resubscribeAll();
+    });
+
+    socket.on(EventName.AuthenticationRequired, (): void => {
+      this.onAuthenticationRequired();
+    });
+
     this.socket = socket;
   }
 
@@ -55,27 +97,22 @@ export default abstract class Realtime {
       tenantId: listenToModelEvent.tenantId.toString(),
     };
 
-    this.emit(EventName.ListenToModalEvent, listenToModelEventJSON as any);
-
     const roomId: string = RealtimeUtil.getRoomId(
       listenToModelEvent.tenantId,
       listenToModelEvent.modelType.name,
       listenToModelEvent.eventType,
     );
 
-    this.socket.on(roomId, (data: JSONObject) => {
-      const id: ObjectID = ObjectID.fromString(
-        data["modelId"]?.toString() as string,
-      );
-      onEvent(id);
-    });
-
-    // Stop listening to the event.
-    const stopListening: () => void = (): void => {
-      this.socket.off(roomId);
-    };
-
-    return stopListening;
+    return this.subscribe(
+      listenToModelEventJSON,
+      roomId,
+      (data: JSONObject): void => {
+        const id: ObjectID = ObjectID.fromString(
+          data["modelId"]?.toString() as string,
+        );
+        onEvent(id);
+      },
+    );
   }
 
   public static listenToAnalyticsModelEvent<Model extends AnalyticsBaseModel>(
@@ -93,8 +130,6 @@ export default abstract class Realtime {
       tenantId: listenToModelEvent.tenantId.toString(),
     };
 
-    this.emit(EventName.ListenToModalEvent, listenToModelEventJSON as any);
-
     let roomId: string = RealtimeUtil.getRoomId(
       listenToModelEvent.tenantId,
       listenToModelEvent.modelType.name,
@@ -110,28 +145,139 @@ export default abstract class Realtime {
       );
     }
 
-    this.socket.on(roomId, (model: JSONObject) => {
-      onEvent(
-        AnalyticsBaseModel.fromJSON(
-          model,
-          listenToModelEvent.modelType,
-        ) as Model,
-      );
-    });
+    return this.subscribe(
+      listenToModelEventJSON,
+      roomId,
+      (model: JSONObject): void => {
+        onEvent(
+          AnalyticsBaseModel.fromJSON(
+            model,
+            listenToModelEvent.modelType,
+          ) as Model,
+        );
+      },
+    );
+  }
+
+  public static emit(eventName: string, data: JSONObject): void {
+    if (!this.socket) {
+      this.init();
+    }
+
+    this.socket.emit(eventName, data);
+  }
+
+  private static subscribe(
+    request: ListenToModelEventJSON,
+    roomId: string,
+    handler: (data: JSONObject) => void,
+  ): () => void {
+    const subscription: RealtimeSubscription = {
+      request: request,
+      roomId: roomId,
+      handler: handler,
+    };
+
+    this.subscriptions.add(subscription);
+
+    this.socket.on(roomId, handler);
+
+    /*
+     * Not connected yet (or between a disconnect and a reconnect): the
+     * 'connect' handler sends every registered subscription, this one
+     * included. Emitting now as well would have socket.io buffer this one and
+     * send it a second time on connect.
+     */
+    if (this.socket.connected) {
+      this.socket.emit(EventName.ListenToModalEvent, request);
+    }
 
     // Stop listening to the event.
     const stopListening: () => void = (): void => {
-      this.socket.off(roomId);
+      this.subscriptions.delete(subscription);
+
+      /*
+       * Only this subscription's handler. Removing every listener on the room
+       * would also silence any other subscription to the same room.
+       */
+      this.socket.off(roomId, handler);
     };
 
     return stopListening;
   }
 
-  public static emit(eventName: string, data: JSONObject): void {
-    if (!this.socket) {
-      this.init();
+  private static resubscribeAll(): void {
+    // The server's join is idempotent, so identical requests go once.
+    const sentRequests: Set<string> = new Set();
+
+    for (const subscription of this.subscriptions) {
+      const requestKey: string = JSON.stringify(subscription.request);
+
+      if (sentRequests.has(requestKey)) {
+        continue;
+      }
+
+      sentRequests.add(requestKey);
+
+      this.socket.emit(EventName.ListenToModalEvent, subscription.request);
     }
+  }
 
-    this.socket.emit(eventName, data);
+  /*
+   * The server refused a subscription because this socket's handshake carries
+   * no access token, or an expired one. The cookie is read once, when the
+   * socket connects, so an HTTP request refreshing the session does nothing
+   * for the socket: refresh (or reuse a refresh another request or tab just
+   * did), then reconnect so the new handshake carries the new cookie. The
+   * reconnect's 'connect' re-sends every subscription, including the refused
+   * one.
+   *
+   * A burst of refusals (a page subscribing to several rooms at once) is one
+   * recovery: the first starts it, the rest arrive while it is in flight or
+   * inside the cool-down.
+   */
+  private static onAuthenticationRequired(): void {
+    if (this.isRecoveringAuthentication) {
+      return;
+    }
+
+    if (
+      this.lastAuthenticationRecoveryAt !== null &&
+      Date.now() - this.lastAuthenticationRecoveryAt <
+        this.AUTHENTICATION_RECOVERY_COOLDOWN_IN_MS
+    ) {
+      return;
+    }
+
+    this.isRecoveringAuthentication = true;
+    this.lastAuthenticationRecoveryAt = Date.now();
+
+    this.recoverAuthentication().catch(() => {
+      // recoverAuthentication settles every outcome itself.
+    });
+  }
+
+  private static async recoverAuthentication(): Promise<void> {
+    try {
+      /*
+       * Without a new cookie a reconnect would only be refused again. When
+       * the refresh failed because the session is over, the refresh request
+       * has already sent the user to the login page.
+       */
+      const refreshed: boolean = await API.refreshSession();
+
+      if (!refreshed) {
+        return;
+      }
+
+      this.socket.disconnect();
+      this.socket.connect();
+    } catch {
+      // A refresh that could not complete (offline, say) did not happen.
+    } finally {
+      this.isRecoveringAuthentication = false;
+      // The cool-down runs from the end of the attempt, however long it took.
+      this.lastAuthenticationRecoveryAt = Date.now();
+    }
   }
 }

package/UI/esbuild-enterprise.js

@@ -0,0 +1,263 @@
+/**
+ * Enterprise Edition resolution for the frontend builds (Dashboard and
+ * AdminDashboard).
+ *
+ * Each of those frontends imports its Enterprise UI through one bare
+ * specifier, from one file (src/Enterprise/Plugins.ts):
+ *
+ *   Dashboard       "@oneuptime/ee-dashboard"        -> ee/Dashboard/Index.tsx
+ *   AdminDashboard  "@oneuptime/ee-admin-dashboard"  -> ee/AdminDashboard/Index.tsx
+ *
+ * This module decides what that specifier means for one build and returns the
+ * esbuild aliases that make it so. The frontends pass the result to
+ * createConfig({ additionalAlias }) - nothing else about the build changes.
+ *
+ * ONEUPTIME_EDITION picks the edition:
+ *
+ *   auto (default)  Enterprise when the ee plugin file is on disk, Community
+ *                   otherwise. A plain checkout builds whatever it contains.
+ *   community       Always the Community stub, even with ee/ present.
+ *   enterprise      The ee plugin, and a hard error when it is missing. The
+ *                   Enterprise image sets this, so a broken COPY of ee/ fails
+ *                   the build instead of quietly shipping the Community UI
+ *                   under an Enterprise tag.
+ *
+ * Where ee/ is looked for, relative to the frontend directory:
+ *
+ *   <frontend>/../../../../ee   the repository: packages/App/FeatureSet/<F>
+ *   <frontend>/../../../ee      the image: /usr/src/app/FeatureSet/<F> -> /usr/src/ee
+ *
+ * ONEUPTIME_EE_DIR replaces both with one directory (fixtures, tests, odd
+ * layouts) - the same variable the server-side loader honours.
+ *
+ * "Found" means the plugin's Index.tsx FILE exists. The alias points at that
+ * file rather than its directory: esbuild resolves a directory alias to a
+ * lowercase index.* and would miss Index.tsx on a case-sensitive filesystem.
+ *
+ * Two more aliases are always returned, so ee code can reach core without
+ * relative paths and without an install of its own:
+ *
+ *   "@oneuptime/dashboard/..." (or "@oneuptime/admin-dashboard/...")
+ *                -> <frontend>/src/...
+ *   "Common/..." -> <frontend>/node_modules/Common/...
+ *
+ * Bundling therefore never depends on ee/node_modules. Both are applied in
+ * the Community build too, so core resolves identically in both editions.
+ *
+ * CommonJS, like esbuild-config.js: the frontends' esbuild.config.js files
+ * are plain node scripts.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const EDITION_ENV_VAR = "ONEUPTIME_EDITION";
+const EE_DIR_ENV_VAR = "ONEUPTIME_EE_DIR";
+
+const EDITION_AUTO = "auto";
+const EDITION_COMMUNITY = "community";
+const EDITION_ENTERPRISE = "enterprise";
+
+const VALID_EDITIONS = [EDITION_AUTO, EDITION_COMMUNITY, EDITION_ENTERPRISE];
+
+const PLUGIN_ENTRY_FILENAME = "Index.tsx";
+
+/*
+ * The Community stub, relative to the frontend directory. Every tsconfig and
+ * jest config maps the plugin specifier to this same file.
+ */
+const COMMUNITY_STUB_PATH = path.join(
+  "src",
+  "Enterprise",
+  "CommunityPlugins.ts",
+);
+
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * The edition the environment asks for: "auto", "community" or "enterprise".
+ * Unset or blank means "auto". Anything else is a typo, and a typo must not
+ * silently build the wrong edition, so it throws.
+ * @param {Object} [env] - Environment to read (defaults to process.env)
+ * @returns {string}
+ */
+function readRequestedEdition(env) {
+  const source = env || process.env;
+  const raw = source[EDITION_ENV_VAR];
+
+  if (raw === undefined || raw === null || String(raw).trim() === "") {
+    return EDITION_AUTO;
+  }
+
+  const value = String(raw).trim().toLowerCase();
+
+  if (!VALID_EDITIONS.includes(value)) {
+    throw new Error(
+      `${EDITION_ENV_VAR} must be one of ${VALID_EDITIONS.join(", ")} (got "${raw}").`,
+    );
+  }
+
+  return value;
+}
+
+/**
+ * Every path the plugin entry may live at, in the order they are tried.
+ * @param {string} frontendDir - Absolute path of the frontend package
+ * @param {string} eeSubdir - "Dashboard" or "AdminDashboard"
+ * @param {Object} [env] - Environment to read (defaults to process.env)
+ * @returns {Array<string>}
+ */
+function getEnterpriseCandidates(frontendDir, eeSubdir, env) {
+  const source = env || process.env;
+  const override = source[EE_DIR_ENV_VAR];
+
+  if (override !== undefined && override !== null && String(override).trim()) {
+    return [
+      path.resolve(String(override).trim(), eeSubdir, PLUGIN_ENTRY_FILENAME),
+    ];
+  }
+
+  return [
+    // Repository: packages/App/FeatureSet/<Frontend> -> <repo>/ee
+    path.resolve(
+      frontendDir,
+      "..",
+      "..",
+      "..",
+      "..",
+      "ee",
+      eeSubdir,
+      PLUGIN_ENTRY_FILENAME,
+    ),
+    // Image: /usr/src/app/FeatureSet/<Frontend> -> /usr/src/ee
+    path.resolve(
+      frontendDir,
+      "..",
+      "..",
+      "..",
+      "ee",
+      eeSubdir,
+      PLUGIN_ENTRY_FILENAME,
+    ),
+  ];
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`resolveEnterpriseBuild: "${name}" is required.`);
+  }
+}
+
+/**
+ * Decide the edition for one frontend build.
+ * @param {Object} options
+ * @param {string} options.frontendDir - Absolute path of the frontend package (its esbuild.config.js __dirname)
+ * @param {string} options.pluginSpecifier - e.g. "@oneuptime/ee-dashboard"
+ * @param {string} options.eeSubdir - Directory under ee/, e.g. "Dashboard"
+ * @param {string} options.internalSpecifier - e.g. "@oneuptime/dashboard"; ee code imports <frontend>/src through it
+ * @param {Object} [options.env] - Environment to read (defaults to process.env)
+ * @returns {{ edition: string, requestedEdition: string, pluginEntry: (string|null), communityStub: string, candidates: Array<string>, alias: Object }}
+ */
+function resolveEnterpriseBuild(options) {
+  const {
+    frontendDir,
+    pluginSpecifier,
+    eeSubdir,
+    internalSpecifier,
+    env = process.env,
+  } = options || {};
+
+  assertNonEmptyString(frontendDir, "frontendDir");
+  assertNonEmptyString(pluginSpecifier, "pluginSpecifier");
+  assertNonEmptyString(eeSubdir, "eeSubdir");
+  assertNonEmptyString(internalSpecifier, "internalSpecifier");
+
+  if (!path.isAbsolute(frontendDir)) {
+    throw new Error(
+      `resolveEnterpriseBuild: "frontendDir" must be absolute (got "${frontendDir}").`,
+    );
+  }
+
+  const communityStub = path.join(frontendDir, COMMUNITY_STUB_PATH);
+
+  if (!isFile(communityStub)) {
+    throw new Error(
+      `The Community plugin stub is missing: ${communityStub}. Every frontend that imports ${pluginSpecifier} needs one.`,
+    );
+  }
+
+  const requestedEdition = readRequestedEdition(env);
+  const candidates = getEnterpriseCandidates(frontendDir, eeSubdir, env);
+
+  const pluginEntry =
+    requestedEdition === EDITION_COMMUNITY
+      ? null
+      : candidates.find(isFile) || null;
+
+  if (requestedEdition === EDITION_ENTERPRISE && !pluginEntry) {
+    throw new Error(
+      `${EDITION_ENV_VAR}=${EDITION_ENTERPRISE}, but the Enterprise UI plugin for ${eeSubdir} was not found. Looked for: ${candidates.join(
+        ", ",
+      )}. Copy the ee/ directory into the build, or unset ${EDITION_ENV_VAR} to build the Community Edition.`,
+    );
+  }
+
+  return {
+    edition: pluginEntry ? EDITION_ENTERPRISE : EDITION_COMMUNITY,
+    requestedEdition,
+    pluginEntry,
+    communityStub,
+    candidates,
+    alias: {
+      [pluginSpecifier]: pluginEntry || communityStub,
+      [internalSpecifier]: path.join(frontendDir, "src"),
+      Common: path.join(frontendDir, "node_modules", "Common"),
+    },
+  };
+}
+
+/**
+ * The esbuild aliases for one frontend build - what esbuild.config.js passes
+ * to createConfig({ additionalAlias }). Same options as resolveEnterpriseBuild.
+ * @param {Object} options
+ * @returns {Object}
+ */
+function resolveEnterpriseAliases(options) {
+  return resolveEnterpriseBuild(options).alias;
+}
+
+/**
+ * One line for the build log, so a CI log shows which edition was bundled.
+ * @param {string} serviceName
+ * @param {Object} build - A resolveEnterpriseBuild() result
+ * @returns {string}
+ */
+function describeEnterpriseBuild(serviceName, build) {
+  if (build.edition === EDITION_ENTERPRISE) {
+    return `${serviceName}: building the Enterprise Edition UI from ${build.pluginEntry}`;
+  }
+
+  return `${serviceName}: building the Community Edition UI (${EDITION_ENV_VAR}=${build.requestedEdition})`;
+}
+
+module.exports = {
+  EDITION_ENV_VAR,
+  EE_DIR_ENV_VAR,
+  EDITION_AUTO,
+  EDITION_COMMUNITY,
+  EDITION_ENTERPRISE,
+  VALID_EDITIONS,
+  PLUGIN_ENTRY_FILENAME,
+  COMMUNITY_STUB_PATH,
+  readRequestedEdition,
+  getEnterpriseCandidates,
+  resolveEnterpriseBuild,
+  resolveEnterpriseAliases,
+  describeEnterpriseBuild,
+};

package/Utils/API.ts

@@ -247,34 +247,43 @@ export default class API {
     return false;
   }
 
+  /*
+   * The class this instance was built from, so `new BaseAPI(...).get()` gets
+   * BaseAPI's session refresh, error handling and headers rather than the
+   * base class's no-op versions.
+   */
+  private getStaticClient(): typeof API {
+    return this.constructor as typeof API;
+  }
+
   public async get<
     T extends JSONObject | JSONArray | BaseModel | Array<BaseModel>,
   >(options: APIRequestOptions): Promise<HTTPResponse<T> | HTTPErrorResponse> {
-    return await API.get<T>(options);
+    return await this.getStaticClient().get<T>(options);
   }
 
   public async delete<
     T extends JSONObject | JSONArray | BaseModel | Array<BaseModel>,
   >(options: APIRequestOptions): Promise<HTTPResponse<T> | HTTPErrorResponse> {
-    return await API.delete<T>(options);
+    return await this.getStaticClient().delete<T>(options);
   }
 
   public async head<
     T extends JSONObject | JSONArray | BaseModel | Array<BaseModel>,
   >(options: APIRequestOptions): Promise<HTTPResponse<T> | HTTPErrorResponse> {
-    return await API.head<T>(options);
+    return await this.getStaticClient().head<T>(options);
   }
 
   public async put<
     T extends JSONObject | JSONArray | BaseModel | Array<BaseModel>,
   >(options: APIRequestOptions): Promise<HTTPResponse<T> | HTTPErrorResponse> {
-    return await API.put<T>(options);
+    return await this.getStaticClient().put<T>(options);
   }
 
   public async patch<
     T extends JSONObject | JSONArray | BaseModel | Array<BaseModel>,
   >(options: APIRequestOptions): Promise<HTTPResponse<T> | HTTPErrorResponse> {
-    return await API.patch<T>(options);
+    return await this.getStaticClient().patch<T>(options);
   }
 
   public static handleError(

package/Utils/EnterpriseLicense/EnterpriseLicenseUsage.ts

@@ -1,3 +1,4 @@
+import { ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS } from "../../Types/EnterpriseLicense/EnterpriseLicensePeriods";
 import EnterpriseLicenseUserCountSource from "../../Types/EnterpriseLicense/EnterpriseLicenseUserCountSource";
 
 /*
@@ -49,9 +50,13 @@ export default class EnterpriseLicenseUsageUtil {
   /*
    * Expired licenses keep getting a daily "expired" email for this many
    * days after expiry, then go quiet — an abandoned license should not be
-   * emailed forever.
+   * emailed forever. It has to outlast the grace period by a clear margin:
+   * the email that says single sign-on, SCIM provisioning and audit logging
+   * have now stopped is only worth sending after they have, which is when
+   * the grace period ends.
    */
-  public static readonly expiredNotificationCutoffDays: number = 30;
+  public static readonly expiredNotificationCutoffDays: number =
+    ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS + 14;
 
   /*
    * License keys are shown/emailed masked — enough to identify the key

package/Utils/HostAddressUtil.ts

@@ -0,0 +1,94 @@
+import IP from "../Types/IP/IP";
+
+/*
+ * The two things every caller that holds a host string needs to get right
+ * when that host might be an IPv6 literal, in one place.
+ *
+ * Both are pure text problems that only exist for IPv6, which is exactly why
+ * they kept being got wrong one call site at a time:
+ *
+ *   1. BRACKETS ARE URL SYNTAX, NOT PART OF THE ADDRESS. "[2001:db8::1]" is
+ *      how RFC 3986 writes an IPv6 host inside a URL authority, and that is
+ *      the form URL.fromString and Hostname.fromAuthority hand back. Node
+ *      does NOT strip them: net.connect({host: "[::1]"}) and
+ *      https.get({host: "[::1]"}) both go to the resolver and come back
+ *      ENOTFOUND, and `ping [::1]` fails the same way. An IPv4 host never
+ *      carries brackets, so every one of those call sites worked until
+ *      somebody pointed it at IPv6.
+ *
+ *   2. "host:port" IS AMBIGUOUS FOR IPv6, AND NOT IN A WAY THAT LOOKS WRONG.
+ *      "192.0.2.1:179" cannot be mistaken for an address. Appending ":179" to
+ *      "2001:518:2800:9::2" produces "2001:518:2800:9::2:179", which node's
+ *      net.isIP() reports as a PERFECTLY VALID IPv6 address - a different
+ *      host from the one that was meant. So the unbracketed spelling does not
+ *      merely read oddly, it silently renames the target.
+ */
+export default class HostAddressUtil {
+  /*
+   * True when the value is an IPv6 literal, written bare ("2001:db8::1") or
+   * bracketed ("[2001:db8::1]"). Anything else - a DNS name, an IPv4 literal,
+   * an authority with a port - is false.
+   */
+  public static isIPv6(host: string): boolean {
+    const bare: string = HostAddressUtil.stripBrackets(host);
+
+    if (!bare) {
+      return false;
+    }
+
+    return IP.isIP(bare) && new IP(bare).isIPv6();
+  }
+
+  /*
+   * The address to hand to a socket, a resolver or the ping binary: the same
+   * host with any IPv6 URL brackets removed.
+   *
+   * Brackets are only removed when what is inside them really is an IPv6
+   * address. "[not-an-address]" is returned untouched so it fails validation
+   * downstream as the nonsense it is, rather than being quietly laundered
+   * into a bare hostname.
+   */
+  public static stripBrackets(host: string): string {
+    const trimmed: string = (host || "").trim();
+
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+      return trimmed;
+    }
+
+    const inner: string = trimmed.substring(1, trimmed.length - 1);
+
+    if (!inner || !IP.isIP(inner) || !new IP(inner).isIPv6()) {
+      return trimmed;
+    }
+
+    return inner;
+  }
+
+  /*
+   * The authority form: an IPv6 host is bracketed so the ":" before the port
+   * cannot be read as another group of the address. Already-bracketed input
+   * is not bracketed twice.
+   *
+   * A missing/empty port returns the host on its own, bare. That is
+   * deliberate: a port-less destination is stored and pinged as the address
+   * itself, and wrapping it in brackets there would change what is written to
+   * the database and shown to the user for no benefit - the ambiguity this
+   * guards against only exists once a ":port" is appended.
+   */
+  public static formatHostAndPort(data: {
+    host: string;
+    port?: string | number | undefined;
+  }): string {
+    const bare: string = HostAddressUtil.stripBrackets(data.host);
+    const port: string =
+      data.port === undefined || data.port === null ? "" : String(data.port);
+
+    if (!port) {
+      return bare;
+    }
+
+    return HostAddressUtil.isIPv6(bare)
+      ? `[${bare}]:${port}`
+      : `${bare}:${port}`;
+  }
+}