@brimble/consul 1.0.0 → 1.0.2

package/README.md

@@ -24,11 +24,13 @@ See the official [HTTP API][consul-docs-api] docs for more information.
   - [Connect](#catalog-connect)
   - [Node](#catalog-node)
   - [Service](#catalog-service)
+* [Config](#config)
 * [Event](#event)
 * [Health](#health)
 * [Intention](#intention)
 * [KV](#kv)
 * [Query](#query)
+* [Resolver](#resolver)
 * [Session](#session)
 * [Status](#status)
 * [Transaction](#transaction)
@@ -1066,6 +1068,101 @@ Result
 ]
 ```
 
+<a id="config"></a>
+
+### consul.config
+
+- [list](#config-list)
+- [get](#config-get)
+- [set](#config-set)
+- [destroy](#config-destroy)
+
+<a id="config-list"></a>
+
+### consul.config.list(options)
+
+Lists config entries for a given kind.
+
+Options
+
+- kind (String): config entry kind
+- dc (String, optional): datacenter
+
+Usage
+
+```javascript
+await consul.config.list("service-resolver");
+```
+
+<a id="config-get"></a>
+
+### consul.config.get(options)
+
+Gets a config entry.
+
+Options
+
+- kind (String): config entry kind
+- name (String): config entry name
+- dc (String, optional): datacenter
+
+Usage
+
+```javascript
+await consul.config.get({
+  kind: "service-resolver",
+  name: "salary-index-ng",
+});
+```
+
+<a id="config-set"></a>
+
+### consul.config.set(entry[, options])
+
+Creates or updates a config entry.
+
+Options
+
+- entry (Object): Consul config entry payload
+- token (String, optional): ACL token
+- dc (String, optional): datacenter
+
+Usage
+
+```javascript
+await consul.config.set(
+  {
+    Kind: "service-resolver",
+    Name: "salary-index-ng",
+    Redirect: {
+      Service: "6a3ea78d3d66fd3ab1dbbb12",
+    },
+  },
+  { token: process.env.CONSUL_HTTP_TOKEN },
+);
+```
+
+<a id="config-destroy"></a>
+
+### consul.config.destroy(options)
+
+Deletes a config entry. Alias: `consul.config.delete(options)`.
+
+Options
+
+- kind (String): config entry kind
+- name (String): config entry name
+- dc (String, optional): datacenter
+
+Usage
+
+```javascript
+await consul.config.destroy({
+  kind: "service-resolver",
+  name: "salary-index-ng",
+});
+```
+
 <a id="event"></a>
 
 ### consul.event
@@ -1486,6 +1583,186 @@ Usage
 await consul.intention.destroy("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
 ```
 
+<a id="resolver"></a>
+
+### consul.resolver(config)
+
+Create a DNS resolver instance for load balancing and service discovery with Consul.
+
+The resolver provides intelligent service selection using multiple algorithms, DNS resolution, health checks, and Redis-based metrics tracking.
+
+Options
+
+- redis (Redis, optional): ioredis instance for caching (required if cacheEnabled is true)
+- cacheEnabled (Boolean, default: false): enable Redis caching
+- cachePrefix (String, required): prefix for Redis cache keys
+- debug (Boolean, default: false): enable debug logging
+- weights (Object, optional): custom weights for weighted round robin algorithm
+  - health (Number, default: 0.25): weight for health score
+  - responseTime (Number, default: 0.2): weight for response time
+  - errorRate (Number, default: 0.2): weight for error rate
+  - resources (Number, default: 0.15): weight for CPU/memory usage
+  - connections (Number, default: 0.1): weight for active connections
+  - distribution (Number, default: 0.1): weight for distribution fairness
+- metrics (Object, optional): default metrics for new services
+  - responseTime (Number, default: 100): default response time in ms
+  - errorRate (Number, default: 0): default error rate percentage
+  - cpuUsage (Number, default: 50): default CPU usage percentage
+  - memoryUsage (Number, default: 50): default memory usage percentage
+  - activeConnections (Number, default: 0): default active connections
+- cacheTTL (Number, default: 60000): cache TTL in milliseconds
+- dnsEndpoints (String[], optional): custom DNS endpoints
+- dnsTimeout (Number, default: 1500): DNS query timeout in milliseconds
+- dnsRetries (Number, default: 2): number of DNS retry attempts
+
+Usage
+
+```javascript
+import Consul from "@brimble/consul";
+import Redis from "ioredis";
+
+const consul = new Consul({
+  host: "127.0.0.1",
+  port: 8500,
+});
+
+const redis = new Redis({
+  host: "localhost",
+  port: 6379,
+});
+
+const resolver = consul.resolver({
+  redis,
+  cacheEnabled: true,
+  cachePrefix: "myapp",
+  debug: false,
+});
+```
+
+<a id="resolver-select"></a>
+
+### resolver.selectOptimalService(service, algorithm)
+
+Select the optimal service instance based on the specified algorithm.
+
+Options
+
+- service (String, required): service name to resolve
+- algorithm (String, optional): selection algorithm
+  - `SelectionAlgorithm.RoundRobin` (default): round-robin selection
+  - `SelectionAlgorithm.LeastConnection`: select service with fewest connections
+  - `SelectionAlgorithm.WeightedRoundRobin`: weighted selection based on metrics
+
+Usage
+
+```javascript
+const Consul = require("@brimble/consul");
+const { SelectionAlgorithm } = Consul.Resolver;
+
+const result = await resolver.selectOptimalService(
+  "my-service",
+  SelectionAlgorithm.LeastConnection,
+);
+
+if (result.selected) {
+  console.log(`Selected: ${result.selected.ip}:${result.selected.port}`);
+}
+```
+
+Result
+
+```json
+{
+  "selected": {
+    "ip": "192.168.1.10",
+    "port": 8080
+  },
+  "services": [
+    {
+      "ip": "192.168.1.10",
+      "port": 8080
+    },
+    {
+      "ip": "192.168.1.11",
+      "port": 8080
+    }
+  ]
+}
+```
+
+<a id="resolver-increment"></a>
+
+### resolver.incrementConnections(serviceId)
+
+Increment the active connection count for a service.
+
+Options
+
+- serviceId (String, required): service ID
+
+Usage
+
+```javascript
+await resolver.incrementConnections("service-id-123");
+```
+
+<a id="resolver-decrement"></a>
+
+### resolver.decrementConnections(serviceId)
+
+Decrement the active connection count for a service.
+
+Options
+
+- serviceId (String, required): service ID
+
+Usage
+
+```javascript
+await resolver.decrementConnections("service-id-123");
+```
+
+<a id="resolver-metrics"></a>
+
+### resolver.getSelectionMetrics(serviceId)
+
+Get current metrics for a specific service.
+
+Options
+
+- serviceId (String, required): service ID
+
+Usage
+
+```javascript
+const metrics = await resolver.getSelectionMetrics("service-id-123");
+```
+
+Result
+
+```json
+{
+  "responseTime": 150,
+  "errorRate": 0.5,
+  "cpuUsage": 45,
+  "memoryUsage": 60,
+  "activeConnections": 10,
+  "lastSelectedTime": 1234567890
+}
+```
+
+<a id="resolver-refresh"></a>
+
+### resolver.refresh()
+
+Clear all stored metrics from Redis cache.
+
+Usage
+
+```javascript
+await resolver.refresh();
+```
+
 <a id="kv"></a>
 
 ### consul.kv

package/lib/config.d.ts

@@ -0,0 +1,55 @@
+import { CommonOptions, Consul } from "./consul";
+
+interface ConfigEntry {
+  Kind: string;
+  Name: string;
+  Namespace?: string;
+  Partition?: string;
+  Meta?: Record<string, string>;
+  CreateIndex?: number;
+  ModifyIndex?: number;
+  [key: string]: unknown;
+}
+
+interface ListOptions extends CommonOptions {
+  kind: string;
+}
+
+type ListResult = ConfigEntry[];
+
+interface GetOptions extends CommonOptions {
+  kind: string;
+  name: string;
+}
+
+type GetResult = ConfigEntry;
+
+type SetOptions = CommonOptions;
+
+type SetResult = boolean;
+
+interface DestroyOptions extends CommonOptions {
+  kind: string;
+  name: string;
+}
+
+type DestroyResult = boolean;
+
+declare class Config {
+  constructor(consul: Consul);
+
+  consul: Consul;
+
+  list(options: ListOptions): Promise<ListResult>;
+  list(kind: string): Promise<ListResult>;
+
+  get(options: GetOptions): Promise<GetResult>;
+
+  set(entry: ConfigEntry, options?: SetOptions): Promise<SetResult>;
+
+  destroy(options: DestroyOptions): Promise<DestroyResult>;
+
+  delete(options: DestroyOptions): Promise<DestroyResult>;
+}
+
+export { Config, ConfigEntry };

package/lib/config.js

@@ -0,0 +1,117 @@
+const errors = require("./errors");
+const utils = require("./utils");
+
+class Config {
+  constructor(consul) {
+    this.consul = consul;
+  }
+
+  /**
+   * Lists config entries for a kind
+   */
+  async list(opts) {
+    if (typeof opts === "string") {
+      opts = { kind: opts };
+    }
+
+    opts = utils.normalizeKeys(opts);
+    opts = utils.defaults(opts, this.consul._defaults);
+
+    const req = {
+      name: "config.list",
+      path: "/config/{kind}",
+      params: { kind: opts.kind },
+      query: {},
+    };
+
+    if (!opts.kind) {
+      throw this.consul._err(errors.Validation("kind required"), req);
+    }
+
+    utils.options(req, opts);
+
+    return await this.consul._get(req, utils.body);
+  }
+
+  /**
+   * Gets a config entry
+   */
+  async get(opts) {
+    opts = utils.normalizeKeys(opts);
+    opts = utils.defaults(opts, this.consul._defaults);
+
+    const req = {
+      name: "config.get",
+      path: "/config/{kind}/{name}",
+      params: { kind: opts.kind, name: opts.name },
+      query: {},
+    };
+
+    if (!opts.kind) {
+      throw this.consul._err(errors.Validation("kind required"), req);
+    }
+    if (!opts.name) {
+      throw this.consul._err(errors.Validation("name required"), req);
+    }
+
+    utils.options(req, opts);
+
+    return await this.consul._get(req, utils.body);
+  }
+
+  /**
+   * Creates or updates a config entry
+   */
+  async set(entry, opts) {
+    opts = utils.normalizeKeys(opts);
+    opts = utils.defaults(opts, this.consul._defaults);
+
+    const req = {
+      name: "config.set",
+      path: "/config",
+      query: {},
+      type: "json",
+      body: entry,
+    };
+
+    if (!entry) {
+      throw this.consul._err(errors.Validation("entry required"), req);
+    }
+
+    utils.options(req, opts);
+
+    return await this.consul._put(req, utils.body);
+  }
+
+  /**
+   * Deletes a config entry
+   */
+  async destroy(opts) {
+    opts = utils.normalizeKeys(opts);
+    opts = utils.defaults(opts, this.consul._defaults);
+
+    const req = {
+      name: "config.destroy",
+      path: "/config/{kind}/{name}",
+      params: { kind: opts.kind, name: opts.name },
+      query: {},
+    };
+
+    if (!opts.kind) {
+      throw this.consul._err(errors.Validation("kind required"), req);
+    }
+    if (!opts.name) {
+      throw this.consul._err(errors.Validation("name required"), req);
+    }
+
+    utils.options(req, opts);
+
+    return await this.consul._delete(req, utils.body);
+  }
+
+  delete() {
+    return this.destroy.apply(this, arguments);
+  }
+}
+
+exports.Config = Config;

package/lib/consul.d.ts

@@ -3,11 +3,20 @@ import { Agent as httpsAgent } from "https";
 import { Acl } from "./acl";
 import { Agent } from "./agent";
 import { Catalog } from "./catalog";
+import { Config } from "./config";
 import { Event } from "./event";
 import { Health } from "./health";
 import { Intention } from "./intention";
 import { Kv } from "./kv";
 import { Query } from "./query";
+import {
+  Resolver,
+  ConsulResolverConfig,
+  SelectionAlgorithm,
+  ServiceInfo,
+  OptimalServiceResult,
+  ServiceMetrics,
+} from "./resolver";
 import { Session } from "./session";
 import { Status } from "./status";
 import { Transaction } from "./transaction";
@@ -43,6 +52,7 @@ declare class Consul {
   acl: Acl;
   agent: Agent;
   catalog: Catalog;
+  config: Config;
   event: Event;
   health: Health;
   intention: Intention;
@@ -55,11 +65,13 @@ declare class Consul {
   static Acl: typeof Acl;
   static Agent: typeof Agent;
   static Catalog: typeof Catalog;
+  static Config: typeof Config;
   static Event: typeof Event;
   static Health: typeof Health;
   static Intention: typeof Intention;
   static Kv: typeof Kv;
   static Query: typeof Query;
+  static Resolver: typeof Resolver;
   static Session: typeof Session;
   static Status: typeof Status;
   static Transaction: typeof Transaction;
@@ -68,6 +80,17 @@ declare class Consul {
   destroy(): void;
 
   watch(options: WatchOptions): Watch;
+
+  resolver(config: ConsulResolverConfig): Resolver;
 }
 
+export {
+  SelectionAlgorithm,
+  ConsulResolverConfig,
+  ServiceInfo,
+  OptimalServiceResult,
+  ServiceMetrics,
+  Resolver,
+};
+
 export { Consul };

package/lib/consul.js

@@ -3,11 +3,13 @@ const papi = require("papi");
 const Acl = require("./acl").Acl;
 const Agent = require("./agent").Agent;
 const Catalog = require("./catalog").Catalog;
+const Config = require("./config").Config;
 const Event = require("./event").Event;
 const Health = require("./health").Health;
 const Intention = require("./intention").Intention;
 const Kv = require("./kv").Kv;
 const Query = require("./query").Query;
+const Resolver = require("./resolver").Resolver;
 const Session = require("./session").Session;
 const Status = require("./status").Status;
 const Watch = require("./watch").Watch;
@@ -51,6 +53,7 @@ class Consul extends papi.Client {
     this.acl = new Consul.Acl(this);
     this.agent = new Consul.Agent(this);
     this.catalog = new Consul.Catalog(this);
+    this.config = new Consul.Config(this);
     this.event = new Consul.Event(this);
     this.health = new Consul.Health(this);
     this.intention = new Consul.Intention(this);
@@ -71,6 +74,10 @@ class Consul extends papi.Client {
     return new Consul.Watch(this, opts);
   }
 
+  resolver(config) {
+    return new Consul.Resolver(this, config);
+  }
+
   static parseQueryMeta(res) {
     return utils.parseQueryMeta(res);
   }
@@ -79,11 +86,13 @@ class Consul extends papi.Client {
 Consul.Acl = Acl;
 Consul.Agent = Agent;
 Consul.Catalog = Catalog;
+Consul.Config = Config;
 Consul.Event = Event;
 Consul.Health = Health;
 Consul.Intention = Intention;
 Consul.Kv = Kv;
 Consul.Query = Query;
+Consul.Resolver = Resolver;
 Consul.Session = Session;
 Consul.Status = Status;
 Consul.Transaction = Transaction;

package/lib/resolver/algorithms.js

@@ -0,0 +1,127 @@
+"use strict";
+
+function roundRobinSelection(services, currentIndex) {
+  const healthyServices = services.filter((service) =>
+    service.Checks.every((check) => check.Status === "passing"),
+  );
+
+  if (healthyServices.length === 0) {
+    throw new Error("No healthy services available");
+  }
+
+  const service = healthyServices[currentIndex % healthyServices.length];
+  const nextIndex = (currentIndex + 1) % healthyServices.length;
+
+  return {
+    id: service.Service.ID,
+    service,
+    nextIndex,
+  };
+}
+
+function leastConnectionSelection(services, metrics, defaultMetrics) {
+  const healthyServices = services
+    .filter((service) =>
+      service.Checks.every((check) => check.Status === "passing"),
+    )
+    .map((service) => {
+      const serviceMetrics = metrics.get(service.Service.ID) || defaultMetrics;
+      return {
+        service,
+        connections: serviceMetrics.activeConnections || 0,
+      };
+    });
+
+  if (healthyServices.length === 0) {
+    throw new Error("No healthy services available");
+  }
+
+  const selectedService = healthyServices.reduce((min, current) =>
+    current.connections < min.connections ? current : min,
+  );
+
+  return {
+    id: selectedService.service.Service.ID,
+    service: selectedService.service,
+  };
+}
+
+function weightedRandomSelection(rankedServices) {
+  if (rankedServices.length === 0) {
+    throw new Error("No services available for selection");
+  }
+
+  const totalScore = rankedServices.reduce(
+    (sum, service) => sum + service.score,
+    0,
+  );
+
+  if (totalScore <= 0) {
+    return {
+      id: rankedServices[0].id,
+      service: rankedServices[0].service,
+    };
+  }
+
+  let random = Math.random() * totalScore;
+
+  for (const service of rankedServices) {
+    random -= service.score;
+    if (random <= 0) {
+      return {
+        id: service.id,
+        service: service.service,
+      };
+    }
+  }
+
+  return {
+    id: rankedServices[0].id,
+    service: rankedServices[0].service,
+  };
+}
+
+function roundRobinSrvSelection(records, currentIndex) {
+  if (!records || records.length === 0) {
+    return null;
+  }
+
+  const selected = records[currentIndex % records.length];
+  const nextIndex = (currentIndex + 1) % records.length;
+
+  return { selected, nextIndex };
+}
+
+function weightedSrvRecordSelection(records, currentIndex) {
+  if (!records || records.length === 0) {
+    return null;
+  }
+
+  const hasNonZeroWeights = records.some((record) => (record.weight || 0) > 0);
+
+  if (!hasNonZeroWeights) {
+    return roundRobinSrvSelection(records, currentIndex);
+  }
+
+  const totalWeight = records.reduce(
+    (sum, record) => sum + (record.weight || 1),
+    0,
+  );
+
+  let random = Math.random() * totalWeight;
+
+  for (const record of records) {
+    random -= record.weight || 1;
+    if (random <= 0) {
+      return { selected: record, nextIndex: currentIndex };
+    }
+  }
+
+  return { selected: records[0], nextIndex: currentIndex };
+}
+
+exports.roundRobinSelection = roundRobinSelection;
+exports.leastConnectionSelection = leastConnectionSelection;
+exports.weightedRandomSelection = weightedRandomSelection;
+exports.roundRobinSrvSelection = roundRobinSrvSelection;
+exports.weightedSrvRecordSelection = weightedSrvRecordSelection;