fa-consul 1.0.1

package/src/consul-client/index.ts

@@ -0,0 +1,31 @@
+import { AgentAPI } from './endpoints/agent';
+import { CatalogAPI } from './endpoints/catalog';
+import { HealthAPI } from './endpoints/health';
+import { ConsulHttpClient } from './http-client';
+import { ConsulClientOptions, OnRequestHook, OnResponseHook } from './types';
+
+export class ConsulClient {
+  private readonly httpClient: ConsulHttpClient;
+
+  public readonly agent: AgentAPI;
+  public readonly health: HealthAPI;
+  public readonly catalog: CatalogAPI;
+
+  constructor (options: ConsulClientOptions) {
+    this.httpClient = new ConsulHttpClient(options);
+    this.agent = new AgentAPI(this.httpClient);
+    this.health = new HealthAPI(this.httpClient);
+    this.catalog = new CatalogAPI(this.httpClient);
+  }
+
+  onRequest (hook: OnRequestHook): void {
+    this.httpClient.onRequest(hook);
+  }
+
+  onResponse (hook: OnResponseHook): void {
+    this.httpClient.onResponse(hook);
+  }
+}
+
+export * from './types';
+export { ConsulHttpClient } from './http-client';

package/src/consul-client/types.ts

@@ -0,0 +1,134 @@
+// ================== Connection Options ==================
+export interface ConsulClientOptions {
+  host: string;
+  port: string | number;
+  secure?: boolean | undefined;
+  token?: string | undefined;
+  dc?: string | undefined;
+  timeout?: number | undefined;
+  defaults?: { token?: string | undefined } | undefined;
+}
+
+// ================== Register Service ==================
+export interface RegisterCheck {
+  name?: string;
+  http?: string;
+  tcp?: string;
+  script?: string;
+  shell?: string;
+  dockercontainerid?: string;
+  interval?: string;
+  timeout?: string;
+  ttl?: string;
+  notes?: string;
+  status?: string;
+  deregistercriticalserviceafter?: string;
+}
+
+export interface RegisterServiceOptions {
+  id?: string;
+  name: string;
+  tags?: string[];
+  address?: string;
+  port?: number;
+  meta?: Record<string, string>;
+  check?: RegisterCheck;
+  checks?: RegisterCheck[];
+  connect?: Record<string, unknown>;
+  proxy?: Record<string, unknown>;
+  taggedAddresses?: Record<string, unknown>;
+  weights?: { passing?: number; warning?: number };
+  enableTagOverride?: boolean;
+}
+
+// ================== Service Info ==================
+export interface ServiceInfo {
+  ID: string;
+  Service: string;
+  Tags?: string[];
+  Meta?: Record<string, string | null>;
+  Port: number;
+  Address: string;
+  Weights?: { Passing: number; Warning: number };
+  EnableTagOverride?: boolean;
+  Datacenter?: string;
+  Proxy?: Record<string, unknown>;
+  Connect?: Record<string, unknown>;
+  CreateIndex?: number;
+  ModifyIndex?: number;
+}
+
+// ================== Health Service ==================
+export interface NodeInfo {
+  ID: string;
+  Node?: string;
+  Address: string;
+  Datacenter?: string;
+  TaggedAddresses?: Record<string, string>;
+  Meta?: Record<string, string>;
+  CreateIndex?: number;
+  ModifyIndex?: number;
+}
+
+export interface HealthCheck {
+  Node: string;
+  CheckID: string;
+  Name: string;
+  Status: 'passing' | 'warning' | 'critical';
+  Notes?: string;
+  Output?: string;
+  ServiceID?: string;
+  ServiceName?: string;
+  ServiceTags?: string[];
+  Type?: string;
+  Definition?: Record<string, unknown>;
+  CreateIndex?: number;
+  ModifyIndex?: number;
+}
+
+export interface HealthServiceInfo {
+  Node?: NodeInfo;
+  Service?: ServiceInfo;
+  Checks?: HealthCheck[];
+}
+
+// ================== Agent Members ==================
+export interface AgentMember {
+  Name: string;
+  Addr: string;
+  Port: number;
+  Tags?: Record<string, string>;
+  Status: number;
+  ProtocolMin: number;
+  ProtocolMax: number;
+  ProtocolCur: number;
+  DelegateMin: number;
+  DelegateMax: number;
+  DelegateCur: number;
+}
+
+// ================== Request/Response Hooks ==================
+export interface RequestInfo {
+  id: number;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string | undefined;
+  timestamp: number;
+  // Properties for compatibility with existing debug utilities
+  path: string;
+  hostname: string;
+  port: string | number;
+  protocol: string;
+  query?: Record<string, string | boolean | undefined> | undefined;
+}
+
+export interface ResponseInfo {
+  requestId: number;
+  statusCode: number;
+  body?: unknown;
+  timestamp: number;
+}
+
+export type OnRequestHook = (request: RequestInfo) => void;
+export type OnResponseHook = (request: RequestInfo, response: ResponseInfo) => void;

package/src/cyclic-register.ts

@@ -0,0 +1,94 @@
+/* eslint-disable no-console */
+// noinspection JSUnusedGlobalSymbols
+
+import { DEBUG, FORCE_EVERY_REGISTER_ATTEMPT, PREFIX } from './constants';
+import { ICLOptions, IConsulAPI, ICyclicStartArgs, IRegisterConfig, IRegisterCyclic } from './interfaces';
+import { cyan, green, magenta, reset } from './lib/color';
+import loggerStub from './lib/logger-stub';
+import { toMills } from './lib/utils';
+
+const prefix = 'CONSUL-REG:';
+const prefixG = `${green}${prefix}${reset}`;
+
+const DEFAULT_INTERVAL = 60_000;
+
+const isDebugReg = /\baf-consul:(reg|\*)/i.test(DEBUG) || /\baf-consul:\*/i.test(DEBUG);
+const debug = (msg: string) => {
+  if (isDebugReg) {
+    console.log(`${magenta}${PREFIX}${reset}: ${msg}`);
+  }
+};
+
+export const getRegisterCyclic = (
+  opts: ICLOptions,
+  consulApi: IConsulAPI,
+  registerConfig: IRegisterConfig,
+): IRegisterCyclic => ({
+  isStarted: false,
+  skipNextRegisterAttemptUntil: 0,
+  healthCheckIntervalMillis: 0,
+  registerIntervalMillis: 0,
+  options: opts,
+  _timerId: setTimeout(() => null, 0),
+  _logger: loggerStub,
+
+  async start (cyclicStartArgs?: ICyclicStartArgs): Promise<-1 | 0 | 1> {
+    const {
+      cLOptions,
+      registerInterval,
+      registerType = 'if-not-registered',
+      deleteOtherInstance = false,
+      noAlreadyRegisteredMessage = false,
+    } = cyclicStartArgs || {};
+
+    if (!cLOptions && !this.options) {
+      return -1;
+    }
+    if (this.isStarted) {
+      return 0;
+    }
+    const options = (cLOptions || this.options) as ICLOptions;
+    this.healthCheckIntervalMillis = toMills(options.config.consul.check?.interval);
+    this.registerIntervalMillis = registerInterval || (this.healthCheckIntervalMillis * 1.5) || DEFAULT_INTERVAL;
+
+    this._logger = options.logger || loggerStub;
+
+    options.em?.on('health-check', () => {
+      this.skipNextRegisterAttemptUntil = Date.now() + (this.healthCheckIntervalMillis * 1.5);
+    });
+
+    const doLoop = async () => {
+      if (FORCE_EVERY_REGISTER_ATTEMPT || this.skipNextRegisterAttemptUntil < Date.now()) {
+        try {
+          if (this.isStarted) {
+            debug(`${prefixG} Service ${cyan}${registerConfig.id}${reset} registration check...`);
+          }
+          await consulApi.registerService(registerConfig, {
+            registerType: (FORCE_EVERY_REGISTER_ATTEMPT || !this.isStarted) ? 'force' : (registerType || 'if-not-registered'),
+            deleteOtherInstance,
+            noAlreadyRegisteredMessage,
+          });
+        } catch (err: Error | any) {
+          err.message = `${prefix} ERROR: ${err.message}`;
+          this._logger.error(err);
+        }
+        this.skipNextRegisterAttemptUntil = 0;
+      } else {
+        debug(`${prefixG} Skip registration check after health check`);
+      }
+      clearTimeout(this._timerId);
+      this._timerId = setTimeout(doLoop, this.registerIntervalMillis);
+    };
+    doLoop().then((r) => r);
+    this.isStarted = true;
+    const { host, port, defaults } = consulApi.agentOptions.reg;
+    this._logger.info(`Cyclic Register of service ${cyan}${registerConfig.id}${reset} started. Agent: ${
+      cyan}${host}:${port}${reset}, token: ${cyan}${defaults?.token?.substring(0, 4)}***${reset}`);
+    return 1;
+  },
+  stop () {
+    clearTimeout(this._timerId);
+    this.isStarted = false;
+    this._logger.info(`Cyclic Register of service ${cyan}${registerConfig.id}${reset} stopped`);
+  },
+});

package/src/get-api.ts

@@ -0,0 +1,62 @@
+/* eslint-disable no-console */
+// noinspection JSUnusedGlobalSymbols
+
+import { CONSUL_DEBUG_ON, MAX_API_CACHED, PREFIX } from './constants';
+import { getRegisterCyclic } from './cyclic-register';
+import { getRegisterConfig } from './get-register-config';
+import { IAFConsulAPI, ICache, ICLOptions, IConsulAgentOptions, IConsulAPI, TRegisterType } from './interfaces';
+import { magenta, reset, yellow } from './lib/color';
+import { getConfigHash } from './lib/hash';
+import { minimizeCache } from './lib/utils';
+import { getConsulApiCached } from './prepare-consul-api';
+
+export { accessPointsUpdater } from './access-points/access-points-updater';
+
+const defaultGetConsulUIAddress = (serviceId: string): string => {
+  const { NODE_ENV, CONSUL_UI_HOST, CONSUL_DC_PROD, CONSUL_DC_DEV } = process.env;
+  const p = NODE_ENV === 'production';
+  return `https://${CONSUL_UI_HOST || ''}/ui/dc-${p ? (CONSUL_DC_PROD || 'prd') : (CONSUL_DC_DEV || 'dev')}/services/${serviceId}/instances`;
+};
+
+const debug = (msg: string) => {
+  if (CONSUL_DEBUG_ON) {
+    console.log(`${magenta}${PREFIX}${reset}: ${msg}`);
+  }
+};
+
+// cached
+
+export const apiCache: ICache<IAFConsulAPI> = {};
+
+export const getAPI = async (options: ICLOptions): Promise<IAFConsulAPI> => {
+  const hash = getConfigHash(options);
+  if (!apiCache[hash]) {
+    const api: IConsulAPI = await getConsulApiCached(options) as IAFConsulAPI;
+    const registerConfig = await getRegisterConfig(options);
+    const serviceId = registerConfig.id;
+    minimizeCache(apiCache, MAX_API_CACHED);
+
+    const consulUI = (options.getConsulUIAddress || defaultGetConsulUIAddress)(serviceId);
+    debug(`${yellow} REGISTER CONFIG:\n${JSON.stringify(registerConfig, undefined, 2)}\n${reset}`);
+    debug(`Consul UI: ${consulUI}`);
+
+    const value = {
+      registerConfig,
+      serviceId,
+      register: {
+        once: async (registerType: TRegisterType = 'if-not-registered') => api.registerService(registerConfig, { registerType }),
+        cyclic: getRegisterCyclic(options, api, registerConfig),
+      },
+      deregister: (svcId?: string, agentOptions?: IConsulAgentOptions) => api.deregisterIfNeed(svcId || serviceId, agentOptions),
+      consulUI,
+    } as IAFConsulAPI;
+
+    Object.entries(api).forEach(([k, v]) => {
+      // @ts-ignore
+      value[k] = typeof v === 'function' ? v.bind(api) : v;
+    });
+
+    apiCache[hash] = { created: Date.now(), value };
+  }
+  return apiCache[hash].value;
+};

package/src/get-register-config.ts

@@ -0,0 +1,102 @@
+import { PREFIX } from './constants';
+import { ICLOptions, IRegisterConfig } from './interfaces';
+import { getFQDNCached } from './lib/fqdn';
+import { getPackageJson, parseMeta, parseTags, removeAroundQuotas } from './lib/utils';
+
+export const getServiceID = (name: string, instance: string, envCode: string = '') => {
+  const p = (process.env.NODE_CONSUL_ENV || process.env.NODE_ENV) === 'production';
+  return `${p ? 'prd' : 'dev'}-${envCode}-${name}-${instance}`.toLowerCase();
+};
+
+export const getRegisterConfig = async (options: ICLOptions): Promise<IRegisterConfig> => {
+  const { config, envCode = '' } = options;
+  const { webServer } = config;
+  const consulServiceConfig = config?.consul?.service ?? {};
+  const { id, host } = consulServiceConfig;
+  let { name, instance, version, description, tags, meta, port } = consulServiceConfig;
+  name = removeAroundQuotas(name);
+  instance = removeAroundQuotas(instance);
+  version = removeAroundQuotas(version);
+  description = removeAroundQuotas(description);
+  tags = parseTags(tags);
+  tags = [name, version, ...(tags)];
+  if (envCode) {
+    tags.push(envCode);
+  }
+  port = Number(port) || Number(webServer.port);
+  if (!port) {
+    throw new Error(`${PREFIX}: Port is empty!`);
+  }
+
+  const serviceId = id || process.env.CONSUL_SERVICE_ID || getServiceID(name, instance, envCode);
+
+  const address = host || (await getFQDNCached());
+  if (!address) {
+    throw new Error(`${PREFIX}: Address is empty!`);
+  }
+
+  meta = parseMeta(meta, { serviceId, name, instance, address, port });
+  const metaObj: Record<string, string> = {
+    host: address,
+    port: String(port),
+    NODE_ENV: process.env.NODE_ENV || '',
+  };
+  if (name) {
+    metaObj.name = name;
+  }
+  if (version) {
+    metaObj.version = version;
+  }
+  if (description) {
+    metaObj.description = description;
+  }
+  if (instance) {
+    metaObj.instance = instance;
+  }
+
+  let packageJson = getPackageJson();
+  if (packageJson) {
+    metaObj.pj_name = packageJson.name;
+    metaObj.pj_version = packageJson.version;
+  }
+  if (metaObj.pj_name !== 'fa-consul') {
+    packageJson = getPackageJson('/node_modules/fa-consul');
+    if (packageJson) {
+      metaObj.af_consul_version = packageJson.version;
+    }
+  }
+  const registerConfig: IRegisterConfig = {
+    id: serviceId,
+    name: serviceId,
+    port,
+    address,
+    tags,
+    // @ts-ignore
+    meta: <Record<string, string>>{ ...metaObj, ...meta },
+  };
+  const check = { ...(config.consul?.check || {}) };
+  [['name', `Service '${name}-${instance}'`], ['timeout', '5s'], ['deregistercriticalserviceafter', '3m']]
+    .forEach(([n, v]) => {
+      // @ts-ignore
+      if (!check[n]) {
+        // @ts-ignore
+        check[n] = v;
+      }
+    });
+  if (!(check.http || check.tcp || check.script || check.shell)) {
+    check.http = `http://${address}:${port}/health`;
+  }
+  if ((check.http || check.script) && !check.interval) {
+    check.interval = '10s';
+  }
+  registerConfig.check = check;
+
+  if (!config.service) {
+    config.service = {};
+  }
+  config.service.id = serviceId;
+  config.service.address = address;
+  config.service.fromService = `${serviceId} / ${address}`;
+
+  return registerConfig;
+};

package/src/index.ts

@@ -0,0 +1,58 @@
+export { AccessPoints } from './access-points/access-points';
+export { accessPointsUpdater } from './access-points/access-points-updater';
+export { getAPI } from './get-api';
+export { getRegisterConfig, getServiceID } from './get-register-config';
+export { getConsulApiCached, prepareConsulAPI } from './prepare-consul-api';
+export { getFQDN, getFQDNCached } from './lib/fqdn';
+export { substitutePercentBracket } from './lib/utils';
+export { checkAccessPointAvailability, isHttpAvailable } from './access-points/access-points-utils';
+export type {
+  IAFConfig,
+  ICache,
+  ICLOptions,
+  IConsulAgentConfig,
+  IConsulAgentOptions,
+  IConsulAPI,
+  ICyclicStartArgs,
+  IRegisterConfig,
+  IRegisterCyclic,
+  IAccessPoint,
+  IAccessPoints,
+  IAPIArgs,
+  IAFConsulAPI,
+  IAFConsulConfig,
+  IConsulServiceInfo,
+  IFullConsulAgentConfig,
+  IFullConsulAgentOptions,
+  IConsulNodeInfo,
+  IMeta,
+  IRegisterCheck,
+  IConsulHealthServiceInfo,
+  ISocketInfo,
+  ILogger,
+  IRegisterOptions,
+  TRegisterResult,
+  TCommonFnResult,
+  TRegisterType,
+  TLoggerMethod,
+  Maybe,
+  Nullable,
+  TBooleanLike,
+} from './interfaces';
+
+// Export new consul-client types for advanced usage
+export { ConsulClient, ConsulHttpClient } from './consul-client';
+export type {
+  ConsulClientOptions,
+  RegisterCheck,
+  RegisterServiceOptions,
+  ServiceInfo,
+  NodeInfo,
+  HealthCheck,
+  HealthServiceInfo,
+  AgentMember,
+  RequestInfo,
+  ResponseInfo,
+  OnRequestHook,
+  OnResponseHook,
+} from './consul-client';