@mountainpass/addressr 2.4.4 → 2.5.0

package/lib/service/address-service.js

@@ -32,6 +32,7 @@ var _streamDown = _interopRequireDefault(require("../utils/stream-down"));
 var _setLinkOptions = require("./set-link-options");
 var _rangeExpansion = require("./range-expansion");
 var _gnafPackageFetch = require("./gnaf-package-fetch");
+var _readShadow = require("../src/read-shadow");
 var _nodeCrypto = _interopRequireDefault(require("node:crypto"));
 var _glob = require("glob");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
@@ -806,7 +807,9 @@ async function loadAddressDetails(file, expectedCount, context, {
 }
 async function searchForAddress(searchString, p, pageSize = PAGE_SIZE) {
   //  const searchString = '657 The Entrance Road'; //'2/25 TOTTERDE'; // 'UNT 2, BELCONNEN';
-  const searchResp = await globalThis.esClient.search({
+  // ADR 031: hoist params so the same body object is shared by the primary
+  // and the fire-and-forget shadow mirror — no double-build cost.
+  const searchParameters = {
     index: ES_INDEX_NAME,
     body: {
       from: (p - 1 || 0) * pageSize,
@@ -871,6 +874,15 @@ async function searchForAddress(searchString, p, pageSize = PAGE_SIZE) {
         }
       }
     }
+  };
+  const searchResp = await globalThis.esClient.search(searchParameters);
+  // ADR 031 read-shadow: fire-and-forget mirror to a configurable secondary
+  // OpenSearch backend so v2 caches warm with realistic production query
+  // distribution before cutover. Returns synchronously; failures swallowed.
+  // No-op when ADDRESSR_SHADOW_HOST is unset (default).
+  (0, _readShadow.mirrorRequest)({
+    method: 'search',
+    params: searchParameters
   });
   logger('hits', JSON.stringify(searchResp.body.hits, undefined, 2));
   return searchResp;

package/lib/src/read-shadow.js

@@ -0,0 +1,192 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports._resetShadowClientForTesting = _resetShadowClientForTesting;
+exports.mirrorRequest = mirrorRequest;
+exports.validateReadShadowConfig = validateReadShadowConfig;
+var _debug = _interopRequireDefault(require("debug"));
+var _opensearch = require("@opensearch-project/opensearch");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable @eslint-community/eslint-comments/disable-enable-pair */
+/* eslint-disable security/detect-object-injection -- env var names are compile-time constants, not user input */
+
+// @jtbd JTBD-201 (Validate a New Search Backend With Realistic Production Traffic Before Cutover)
+//
+// ADR 031: Read-shadow for search-backend migrations.
+//
+// Mirrors `/addresses?q=...` and `/addresses/{id}` requests to a configurable
+// secondary OpenSearch backend in fire-and-forget mode. Goal: warm the
+// candidate cluster's filesystem and field-data caches with realistic
+// production query distribution before cutover.
+//
+// Default off: when `ADDRESSR_SHADOW_HOST` is unset, `mirrorRequest` is a
+// no-op. Self-hosted users (npm/Docker) are unaffected.
+//
+// Failure isolation: every code path through `mirrorRequest` is wrapped to
+// guarantee the primary `/addresses` response cannot be impacted. Synchronous
+// throws from client construction or method invocation are caught; async
+// rejections are swallowed via `.catch(swallowError)`; per-request
+// `AbortController` timeout (default 3000ms) bounds in-flight resources under
+// shadow target outage.
+//
+// `ADDRESSR_SHADOW_*` is the application-level shadow target (read by the
+// running addressr server). It is distinct from `TF_VAR_ELASTIC_V2_*`, which
+// is the Terraform input that populates EB env at deploy time. They may carry
+// the same values during a migration window, but their lifecycles differ
+// (shadow vars persist across migrations; V2 vars are clobbered into
+// canonical names at decommission per ADR 029 step 9).
+
+const logger = (0, _debug.default)('api');
+const error = (0, _debug.default)('error');
+error.log = console.error.bind(console);
+const HOST_VAR = 'ADDRESSR_SHADOW_HOST';
+const PORT_VAR = 'ADDRESSR_SHADOW_PORT';
+const USERNAME_VAR = 'ADDRESSR_SHADOW_USERNAME';
+const PASSWORD_VAR = 'ADDRESSR_SHADOW_PASSWORD';
+const PROTOCOL_VAR = 'ADDRESSR_SHADOW_PROTOCOL';
+const TIMEOUT_VAR = 'ADDRESSR_SHADOW_TIMEOUT_MS';
+const SUPPORTED_METHODS = new Set(['search', 'get']);
+const DEFAULT_TIMEOUT_MS = 3000;
+
+// Module-scoped lazy singleton. The shadow client is built on first call
+// and reused for the process lifetime so connection setup amortises across
+// requests (the @opensearch-project/opensearch client uses keepalive HTTP
+// agents internally).
+let cachedClient;
+let cachedClientFingerprint;
+function isNonEmpty(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+function validateReadShadowConfig(environment = process.env) {
+  const hostSet = isNonEmpty(environment[HOST_VAR]);
+  const usernameSet = isNonEmpty(environment[USERNAME_VAR]);
+  const passwordSet = isNonEmpty(environment[PASSWORD_VAR]);
+  if (!hostSet) {
+    return; // feature disabled, nothing to validate
+  }
+  if (usernameSet && !passwordSet) {
+    throw new Error(`Read-shadow misconfigured: ${USERNAME_VAR} is set but ${PASSWORD_VAR} is missing. Set both to enable basic auth, or unset both to use the shadow target without auth.`);
+  }
+  if (passwordSet && !usernameSet) {
+    throw new Error(`Read-shadow misconfigured: ${PASSWORD_VAR} is set but ${USERNAME_VAR} is missing. Set both to enable basic auth, or unset both to use the shadow target without auth.`);
+  }
+}
+function buildClientOptions(environment) {
+  const host = environment[HOST_VAR];
+  const port = environment[PORT_VAR] || '443';
+  const protocol = environment[PROTOCOL_VAR] || 'https';
+  const username = environment[USERNAME_VAR];
+  const password = environment[PASSWORD_VAR];
+  const node = isNonEmpty(username) ? `${protocol}://${username}:${password}@${host}:${port}` : `${protocol}://${host}:${port}`;
+  return {
+    node
+  };
+}
+
+// Stable fingerprint so the cache resets when env changes between calls
+// (e.g. between unit tests that snapshot/restore env). Excludes credentials.
+function clientFingerprint(environment) {
+  return [environment[HOST_VAR] || '', environment[PORT_VAR] || '', environment[PROTOCOL_VAR] || '', isNonEmpty(environment[USERNAME_VAR]) ? '+auth' : '-auth'].join('|');
+}
+function getShadowClient({
+  environment = process.env,
+  ClientClass = _opensearch.Client
+} = {}) {
+  if (!isNonEmpty(environment[HOST_VAR])) {
+    return;
+  }
+  const fingerprint = clientFingerprint(environment);
+  if (cachedClient && cachedClientFingerprint === fingerprint) {
+    return cachedClient;
+  }
+  const options = buildClientOptions(environment);
+  cachedClient = new ClientClass(options);
+  cachedClientFingerprint = fingerprint;
+  return cachedClient;
+}
+function getTimeoutMs(environment) {
+  const raw = environment[TIMEOUT_VAR];
+  if (!isNonEmpty(raw)) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+}
+function swallowError(reason) {
+  if (reason && reason.name === 'AbortError') {
+    error('read-shadow: request aborted by timeout');
+    return;
+  }
+  if (reason instanceof Error) {
+    error('read-shadow: %s', reason.message);
+    return;
+  }
+  error('read-shadow: non-error rejection %o', reason);
+}
+
+// Fire-and-forget mirror to a configurable shadow OpenSearch backend.
+// Returns synchronously; the kicked-off promise is detached.
+//
+// Programmer-error throws (unsupported method) are synchronous so callers
+// notice during dev. All operational errors (network, target down, abort,
+// synchronous client throws) are swallowed via swallowError.
+function mirrorRequest({
+  method,
+  params,
+  environment = process.env,
+  ClientClass = _opensearch.Client
+} = {}) {
+  if (!SUPPORTED_METHODS.has(method)) {
+    throw new Error(`read-shadow: unsupported method ${JSON.stringify(method)}; expected one of ${[...SUPPORTED_METHODS].join(', ')}`);
+  }
+  let client;
+  try {
+    client = getShadowClient({
+      environment,
+      ClientClass
+    });
+  } catch (constructError) {
+    swallowError(constructError);
+    return;
+  }
+  if (!client) {
+    return; // feature disabled (HOST unset)
+  }
+  const timeoutMs = getTimeoutMs(environment);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  if (typeof timer.unref === 'function') {
+    timer.unref();
+  }
+  let promise;
+  try {
+    promise = client[method](params, {
+      signal: controller.signal
+    });
+  } catch (syncError) {
+    clearTimeout(timer);
+    swallowError(syncError);
+    return;
+  }
+  if (!promise || typeof promise.then !== 'function') {
+    clearTimeout(timer);
+    return;
+  }
+  promise.then(() => {
+    clearTimeout(timer);
+    logger('read-shadow: %s ok', method);
+    return;
+  }).catch(error_ => {
+    clearTimeout(timer);
+    swallowError(error_);
+  });
+}
+
+// Internal: lets unit tests reset the singleton between cases. Not part of
+// the public contract; flagged with a leading underscore by convention.
+function _resetShadowClientForTesting() {
+  cachedClient = undefined;
+  cachedClientFingerprint = undefined;
+}

package/lib/src/waycharter-server.js

@@ -13,6 +13,7 @@ var _addressService = require("../service/address-service");
 var _version = require("../version");
 var _nodeCrypto = _interopRequireDefault(require("node:crypto"));
 var _proxyAuth = require("./proxy-auth");
+var _readShadow = require("./read-shadow");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 //import connect from 'connect';
 
@@ -659,6 +660,7 @@ let server;
 const PAGE_SIZE = process.env.PAGE_SIZE || 8;
 function startRest2Server() {
   (0, _proxyAuth.validateProxyAuthConfig)();
+  (0, _readShadow.validateReadShadowConfig)();
   app.use((_request, response, next) => {
     if (process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN !== undefined) {
       response.append('Access-Control-Allow-Origin', process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN);

package/lib/swagger.js

@@ -14,6 +14,7 @@ var _nodeHttp = require("node:http");
 var _jsYaml = require("js-yaml");
 var _nodePath = _interopRequireDefault(require("node:path"));
 var _swaggerTools = require("swagger-tools");
+var _readShadow = require("./src/read-shadow");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 //import connect from 'connect';
 
@@ -86,6 +87,8 @@ function swaggerInit() {
 }
 let server;
 function startServer() {
+  // ADR 031: fail loudly at startup if read-shadow env vars are misconfigured.
+  (0, _readShadow.validateReadShadowConfig)();
   app.use((request, response, next) => {
     if (process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN !== undefined) {
       response.append('Access-Control-Allow-Origin', process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN);

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.4.4';
+const version = exports.version = '2.5.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",