@brimble/consul 1.0.0 → 1.0.1

package/README.md

@@ -29,6 +29,7 @@ See the official [HTTP API][consul-docs-api] docs for more information.
 * [Intention](#intention)
 * [KV](#kv)
 * [Query](#query)
+* [Resolver](#resolver)
 * [Session](#session)
 * [Status](#status)
 * [Transaction](#transaction)
@@ -1486,6 +1487,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/consul.d.ts

@@ -8,6 +8,14 @@ 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";
@@ -60,6 +68,7 @@ declare class Consul {
   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 +77,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

@@ -8,6 +8,7 @@ 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;
@@ -71,6 +72,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);
   }
@@ -84,6 +89,7 @@ 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/index.d.ts

@@ -1,3 +1,18 @@
-import { Consul } from "./consul";
+import { Consul, SelectionAlgorithm } from "./consul";
+import {
+  ConsulResolverConfig,
+  ServiceInfo,
+  OptimalServiceResult,
+  ServiceMetrics,
+  Resolver,
+} from "./resolver";
 
 export = Consul;
+
+export type {
+  ConsulResolverConfig,
+  ServiceInfo,
+  OptimalServiceResult,
+  ServiceMetrics,
+};
+export { SelectionAlgorithm, Resolver };

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;

package/lib/resolver/dns.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const { log } = require("@brimble/utils");
+const { query } = require("dns-query");
+const {
+  roundRobinSrvSelection,
+  weightedSrvRecordSelection,
+} = require("./algorithms");
+const { SelectionAlgorithm } = require("./types");
+
+class DNSManager {
+  constructor(
+    redis,
+    cachePrefix,
+    cacheTTL,
+    cacheEnabled,
+    debug,
+    dnsEndpoints,
+    dnsTimeout,
+    dnsRetries,
+  ) {
+    this.redis = redis;
+    this.cachePrefix = cachePrefix;
+    this.cacheTTL = cacheTTL;
+    this.cacheEnabled = cacheEnabled;
+    this.debug = debug;
+    this.dnsEndpoints = dnsEndpoints;
+    this.dnsTimeout = dnsTimeout;
+    this.dnsRetries = dnsRetries;
+  }
+
+  getDNSCacheKey(service) {
+    return `${this.cachePrefix}:dns:${service}`;
+  }
+
+  async resolveDNS(service) {
+    const cacheKey = this.getDNSCacheKey(service);
+
+    if (this.cacheEnabled) {
+      try {
+        const cachedData = await Promise.race([
+          this.redis?.get(cacheKey),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error("Redis get timeout")), 200),
+          ),
+        ]);
+        if (cachedData) {
+          if (this.debug) {
+            log.debug(`DNS cache hit for ${service}`);
+          }
+          return JSON.parse(cachedData);
+        }
+      } catch (e) {
+        if (this.debug) log.error("Redis get error or timeout:", e);
+      }
+    }
+
+    try {
+      const result = await query(
+        {
+          question: {
+            type: "SRV",
+            name: service,
+          },
+        },
+        {
+          endpoints: this.dnsEndpoints,
+          timeout: this.dnsTimeout ?? 1500,
+          retries: this.dnsRetries ?? 2,
+        },
+      );
+
+      if (this.debug) {
+        log.debug("DNS QUERY RESULT", result);
+      }
+
+      if (!result.answers || result.answers.length === 0) {
+        if (this.debug) {
+          log.debug(`No SRV records found for ${service}`);
+        }
+        return [];
+      }
+
+      const additionalsByName = {};
+      if (result.additionals) {
+        for (const additional of result.additionals) {
+          if (additional.type === "A") {
+            additionalsByName[additional.name] = additional;
+          }
+        }
+      }
+      const records = result.answers
+        .map((answer) => {
+          const target = answer.data.target;
+          const aRecord = additionalsByName[target];
+          return {
+            name: target,
+            ip: aRecord?.data || "",
+            port: answer.data.port,
+            priority: answer.data.priority,
+            weight: answer.data.weight,
+          };
+        })
+        .filter((record) => record.ip);
+
+      if (this.cacheEnabled) {
+        try {
+          await Promise.race([
+            this.redis?.set(
+              cacheKey,
+              JSON.stringify(records),
+              "EX",
+              this.cacheTTL,
+            ),
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new Error("Redis set timeout")), 200),
+            ),
+          ]);
+        } catch (e) {
+          if (this.debug) log.error("Redis set error or timeout:", e);
+        }
+      }
+
+      return records;
+    } catch (error) {
+      if (this.debug) {
+        log.error("DNS resolution error:", error);
+      }
+      return [];
+    }
+  }
+
+  sortByPriority(records) {
+    return [...records].sort((a, b) => (a.priority || 0) - (b.priority || 0));
+  }
+
+  selectFromSrvRecords(records, algorithm, currentIndex) {
+    if (!records || records.length === 0) {
+      return { selected: null, nextIndex: currentIndex };
+    }
+
+    switch (algorithm) {
+      case SelectionAlgorithm.RoundRobin: {
+        const rrResult = roundRobinSrvSelection(records, currentIndex);
+        if (!rrResult) {
+          return { selected: null, nextIndex: currentIndex };
+        }
+        return {
+          selected: rrResult.selected,
+          nextIndex: rrResult.nextIndex,
+        };
+      }
+
+      case SelectionAlgorithm.WeightedRoundRobin: {
+        const wrResult = weightedSrvRecordSelection(records, currentIndex);
+        if (!wrResult) {
+          return { selected: null, nextIndex: currentIndex };
+        }
+        return {
+          selected: wrResult.selected,
+          nextIndex: wrResult.nextIndex,
+        };
+      }
+
+      case SelectionAlgorithm.LeastConnection: {
+        const lcResult = roundRobinSrvSelection(records, currentIndex);
+        if (!lcResult) {
+          return { selected: null, nextIndex: currentIndex };
+        }
+        return {
+          selected: lcResult.selected,
+          nextIndex: lcResult.nextIndex,
+        };
+      }
+
+      default:
+        return { selected: records[0], nextIndex: currentIndex };
+    }
+  }
+}
+
+exports.DNSManager = DNSManager;

package/lib/resolver/health.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const { log } = require("@brimble/utils");
+
+class HealthCheckManager {
+  constructor(consul, redis, cachePrefix, cacheTTL, cacheEnabled, debug) {
+    this.consul = consul;
+    this.redis = redis;
+    this.cachePrefix = cachePrefix;
+    this.cacheTTL = cacheTTL;
+    this.cacheEnabled = cacheEnabled;
+    this.debug = debug;
+  }
+
+  getHealthCacheKey(service) {
+    return `${this.cachePrefix}:health:${service}`;
+  }
+
+  async getHealthChecks(service) {
+    const cacheKey = this.getHealthCacheKey(service);
+
+    if (this.cacheEnabled) {
+      const cachedHealth = await this.redis?.get(cacheKey);
+      if (cachedHealth) {
+        return JSON.parse(cachedHealth);
+      }
+    }
+
+    try {
+      const healthChecks = await this.consul.health.service(service);
+
+      if (this.cacheEnabled) {
+        await this.redis?.set(
+          cacheKey,
+          JSON.stringify(healthChecks),
+          "EX",
+          this.cacheTTL,
+        );
+      }
+
+      return healthChecks;
+    } catch (error) {
+      if (this.debug) {
+        log.error(`Error fetching health checks for ${service}:`, error);
+      }
+      return [];
+    }
+  }
+}
+
+exports.HealthCheckManager = HealthCheckManager;

package/lib/resolver/metrics.js

@@ -0,0 +1,199 @@
+"use strict";
+
+const { log } = require("@brimble/utils");
+
+class MetricsManager {
+  constructor(redis, cachePrefix, metrics, cacheEnabled, debug) {
+    this.redis = redis;
+    this.cachePrefix = cachePrefix;
+    this.metrics = metrics;
+    this.cacheEnabled = cacheEnabled;
+    this.debug = debug;
+  }
+
+  getConnectionKey(serviceId) {
+    return `${this.cachePrefix}:connections:${serviceId}`;
+  }
+
+  async getServicesMetrics(services) {
+    const metricsMap = new Map();
+    const pipeline = this.redis?.pipeline();
+
+    if (this.cacheEnabled) {
+      services.forEach((service) => {
+        pipeline?.get(service.Service.ID);
+        pipeline?.get(this.getConnectionKey(service.Service.ID));
+      });
+    }
+
+    try {
+      const results = await pipeline?.exec();
+      if (!results) {
+        services.forEach((service) => {
+          metricsMap.set(service.Service.ID, { ...this.metrics });
+        });
+        return metricsMap;
+      }
+
+      services.forEach((service, index) => {
+        const serviceId = service.Service.ID;
+        const metricsResult = results[index * 2];
+        const connectionsResult = results[index * 2 + 1];
+
+        let metrics;
+
+        try {
+          if (metricsResult?.[1]) {
+            metrics = JSON.parse(metricsResult[1]);
+          } else {
+            metrics = { ...this.metrics };
+          }
+
+          if (connectionsResult?.[1]) {
+            const connData = JSON.parse(connectionsResult[1]);
+            metrics.activeConnections = connData.activeConnections || 0;
+          }
+
+          metricsMap.set(serviceId, metrics);
+        } catch (error) {
+          if (this.debug) {
+            log.error(
+              `Error processing metrics for service ${serviceId}:`,
+              error,
+            );
+          }
+          metricsMap.set(serviceId, { ...this.metrics });
+        }
+      });
+    } catch (error) {
+      if (this.debug) {
+        log.error("Error executing Redis pipeline:", error);
+      }
+      services.forEach((service) => {
+        metricsMap.set(service.Service.ID, { ...this.metrics });
+      });
+    }
+
+    return metricsMap;
+  }
+
+  async incrementConnections(serviceId) {
+    try {
+      const connectionKey = this.getConnectionKey(serviceId);
+      const existingMetrics = await this.redis?.get(connectionKey);
+      let metrics;
+
+      if (existingMetrics) {
+        metrics = JSON.parse(existingMetrics);
+        metrics.activeConnections = (metrics.activeConnections || 0) + 1;
+      } else {
+        metrics = {
+          ...this.metrics,
+          activeConnections: 1,
+        };
+      }
+
+      if (this.cacheEnabled) {
+        await this.redis?.set(
+          connectionKey,
+          JSON.stringify(metrics),
+          "EX",
+          24 * 60 * 60,
+        );
+      }
+    } catch (error) {
+      if (this.debug) {
+        log.error(
+          `Failed to increment connections for service ${serviceId}:`,
+          error,
+        );
+      }
+    }
+  }
+
+  async decrementConnections(serviceId) {
+    try {
+      const connectionKey = this.getConnectionKey(serviceId);
+      const existingMetrics = await this.redis?.get(connectionKey);
+      let metrics;
+
+      if (existingMetrics) {
+        metrics = JSON.parse(existingMetrics);
+        metrics.activeConnections = Math.max(
+          0,
+          (metrics.activeConnections || 1) - 1,
+        );
+      } else {
+        metrics = {
+          ...this.metrics,
+          activeConnections: 0,
+        };
+      }
+
+      if (this.cacheEnabled) {
+        await this.redis?.set(
+          connectionKey,
+          JSON.stringify(metrics),
+          "EX",
+          24 * 60 * 60,
+        );
+      }
+    } catch (error) {
+      if (this.debug) {
+        log.error(
+          `Failed to decrement connections for service ${serviceId}:`,
+          error,
+        );
+      }
+    }
+  }
+
+  async updateSelectionMetrics(serviceId) {
+    try {
+      const connectionKey = this.getConnectionKey(serviceId);
+      const existingMetrics = await this.redis?.get(connectionKey);
+      let metrics;
+
+      if (existingMetrics) {
+        metrics = JSON.parse(existingMetrics);
+      } else {
+        metrics = { ...this.metrics };
+      }
+
+      metrics.lastSelectedTime = Date.now();
+
+      if (this.cacheEnabled) {
+        await this.redis?.set(
+          connectionKey,
+          JSON.stringify(metrics),
+          "EX",
+          24 * 60 * 60,
+        );
+      }
+    } catch (error) {
+      if (this.debug) {
+        log.error(
+          `Failed to update selection metrics for service ${serviceId}:`,
+          error,
+        );
+      }
+    }
+  }
+
+  async getSelectionMetrics(serviceId) {
+    try {
+      if (!this.cacheEnabled) {
+        return null;
+      }
+      const metrics = await this.redis?.get(this.getConnectionKey(serviceId));
+      return metrics ? JSON.parse(metrics) : null;
+    } catch (error) {
+      if (this.debug) {
+        log.error("Error getting service metrics:", error);
+      }
+      return null;
+    }
+  }
+}
+
+exports.MetricsManager = MetricsManager;

package/lib/resolver/scoring.js

@@ -0,0 +1,95 @@
+"use strict";
+
+const { DEFAULT_WEIGHTS } = require("./types");
+
+function calculateHealthScore(service) {
+  const checks = service.Checks;
+  const totalChecks = checks.length;
+  if (totalChecks === 0) return 0;
+
+  const passingChecks = checks.filter(
+    (check) => check.Status === "passing",
+  ).length;
+  return passingChecks / totalChecks;
+}
+
+function normalizeScore(value, max, inverse = false) {
+  const normalized = Math.max(0, Math.min(1, value / max));
+  return inverse ? 1 - normalized : normalized;
+}
+
+function calculateResourceScore(metrics) {
+  const cpuScore = normalizeScore(metrics.cpuUsage, 100, true);
+  const memoryScore = normalizeScore(metrics.memoryUsage, 100, true);
+  return (cpuScore + memoryScore) / 2;
+}
+
+function calculateDistributionScore(lastSelectedTime) {
+  if (!lastSelectedTime) return 1;
+
+  const timeSinceLastSelection = Date.now() - lastSelectedTime;
+
+  return Math.min(timeSinceLastSelection / (5 * 60 * 1000), 1);
+}
+
+function rankServices(services, metrics, weights = DEFAULT_WEIGHTS) {
+  return services
+    .map((service) => {
+      const serviceId = service.Service.ID;
+
+      const serviceMetrics = metrics.get(serviceId);
+
+      if (!serviceMetrics) {
+        throw new Error(`No metrics found for service ${serviceId}`);
+      }
+
+      const healthScore = calculateHealthScore(service);
+      const responseTimeScore = normalizeScore(
+        serviceMetrics.responseTime,
+        500,
+        true,
+      );
+      const errorRateScore = normalizeScore(
+        serviceMetrics.errorRate,
+        100,
+        true,
+      );
+      const resourceScore = calculateResourceScore(serviceMetrics);
+      const connectionScore = normalizeScore(
+        serviceMetrics.activeConnections,
+        1000,
+        true,
+      );
+      const distributionScore = calculateDistributionScore(
+        serviceMetrics.lastSelectedTime,
+      );
+
+      const totalScore =
+        healthScore * weights.health +
+        responseTimeScore * weights.responseTime +
+        errorRateScore * weights.errorRate +
+        resourceScore * weights.resources +
+        connectionScore * weights.connections +
+        distributionScore * weights.distribution;
+
+      return {
+        score: totalScore,
+        id: serviceId,
+        service,
+      };
+    })
+    .sort((a, b) => b.score - a.score);
+}
+
+function combineHealthAndDNSWeights(service, dnsWeight, maxDNSWeight) {
+  const healthScore = calculateHealthScore(service);
+  const normalizedDNSWeight = dnsWeight / maxDNSWeight;
+  return healthScore * 0.7 + normalizedDNSWeight * 0.3;
+}
+
+exports.calculateHealthScore = calculateHealthScore;
+exports.calculateResourceScore = calculateResourceScore;
+exports.calculateDistributionScore = calculateDistributionScore;
+exports.normalizeScore = normalizeScore;
+exports.rankServices = rankServices;
+exports.combineHealthAndDNSWeights = combineHealthAndDNSWeights;

package/lib/resolver/types.js

@@ -0,0 +1,28 @@
+"use strict";
+
+const DEFAULT_WEIGHTS = {
+  health: 0.25,
+  responseTime: 0.2,
+  errorRate: 0.2,
+  resources: 0.15,
+  connections: 0.1,
+  distribution: 0.1,
+};
+
+const DEFAULT_METRICS = {
+  responseTime: 100,
+  errorRate: 0,
+  cpuUsage: 50,
+  memoryUsage: 50,
+  activeConnections: 0,
+};
+
+const SelectionAlgorithm = {
+  RoundRobin: "round-robin",
+  LeastConnection: "least-connection",
+  WeightedRoundRobin: "weighted-round-robin",
+};
+
+exports.DEFAULT_WEIGHTS = DEFAULT_WEIGHTS;
+exports.DEFAULT_METRICS = DEFAULT_METRICS;
+exports.SelectionAlgorithm = SelectionAlgorithm;

package/lib/resolver.d.ts

@@ -0,0 +1,76 @@
+import { Agent as httpAgent } from "http";
+import { Agent as httpsAgent } from "https";
+import { Redis as IORedis } from "ioredis";
+import { Consul } from "./consul";
+
+export interface ConsulResolverConfig {
+  redis?: IORedis;
+  cacheEnabled: boolean;
+  cachePrefix: string;
+  debug?: boolean;
+  weights?: {
+    health: number;
+    responseTime: number;
+    errorRate: number;
+    resources: number;
+    connections: number;
+    distribution: number;
+  };
+  metrics?: {
+    responseTime: number;
+    errorRate: number;
+    cpuUsage: number;
+    memoryUsage: number;
+    activeConnections: number;
+  };
+  cacheTTL?: number;
+  dnsEndpoints?: string[];
+  dnsTimeout?: number;
+  dnsRetries?: number;
+}
+
+export interface ServiceInfo {
+  ip: string;
+  port: number;
+}
+
+export interface OptimalServiceResult {
+  selected: ServiceInfo | null;
+  services: ServiceInfo[];
+}
+
+export interface ServiceMetrics {
+  responseTime: number;
+  errorRate: number;
+  cpuUsage: number;
+  memoryUsage: number;
+  activeConnections: number;
+  lastSelectedTime?: number;
+}
+
+export enum SelectionAlgorithm {
+  RoundRobin = "round-robin",
+  LeastConnection = "least-connection",
+  WeightedRoundRobin = "weighted-round-robin",
+}
+
+declare class Resolver {
+  constructor(consul: Consul, config: ConsulResolverConfig);
+
+  consul: Consul;
+
+  selectOptimalService(
+    service: string,
+    algorithm?: SelectionAlgorithm,
+  ): Promise<OptimalServiceResult>;
+
+  incrementConnections(serviceId: string): Promise<void>;
+
+  decrementConnections(serviceId: string): Promise<void>;
+
+  getSelectionMetrics(serviceId: string): Promise<ServiceMetrics | null>;
+
+  refresh(): Promise<void>;
+}
+
+export { Resolver };

package/lib/resolver.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const { log } = require("@brimble/utils");
+const {
+  leastConnectionSelection,
+  roundRobinSelection,
+  weightedRandomSelection,
+} = require("./resolver/algorithms");
+const { DNSManager } = require("./resolver/dns");
+const { HealthCheckManager } = require("./resolver/health");
+const { MetricsManager } = require("./resolver/metrics");
+const {
+  combineHealthAndDNSWeights,
+  rankServices,
+} = require("./resolver/scoring");
+const {
+  DEFAULT_METRICS,
+  DEFAULT_WEIGHTS,
+  SelectionAlgorithm,
+} = require("./resolver/types");
+
+class Resolver {
+  constructor(consul, config) {
+    this.consul = consul;
+    this.currentIndex = 0;
+    this.debug = config.debug || false;
+    this.cachePrefix = config.cachePrefix;
+    this.cacheEnabled = config.cacheEnabled;
+    this.weights = config.weights || DEFAULT_WEIGHTS;
+    this.metrics = config.metrics || DEFAULT_METRICS;
+    this.redis = config.redis;
+
+    this.cacheTTL = Math.floor((config.cacheTTL || 60 * 1000) / 1000);
+
+    if (this.cacheEnabled && config.redis) {
+      this.redis = config.redis;
+      this.cacheEnabled = true;
+    }
+
+    this.metricsManager = new MetricsManager(
+      this.redis,
+      this.cachePrefix,
+      this.metrics,
+      this.cacheEnabled,
+      this.debug,
+    );
+
+    this.dnsManager = new DNSManager(
+      this.redis,
+      this.cachePrefix,
+      this.cacheTTL,
+      this.cacheEnabled,
+      this.debug,
+      config.dnsEndpoints,
+      config.dnsTimeout,
+      config.dnsRetries,
+    );
+
+    this.healthCheckManager = new HealthCheckManager(
+      this.consul,
+      this.redis,
+      this.cachePrefix,
+      this.cacheTTL,
+      this.cacheEnabled,
+      this.debug,
+    );
+  }
+
+  /**
+   * Select the optimal service based on the specified algorithm
+   */
+  async selectOptimalService(
+    service,
+    algorithm = SelectionAlgorithm.RoundRobin,
+  ) {
+    try {
+      const [healthChecks, dnsRecords] = await Promise.all([
+        this.healthCheckManager.getHealthChecks(service),
+        this.dnsManager.resolveDNS(service),
+      ]);
+
+      if (
+        (!healthChecks || healthChecks.length === 0) &&
+        dnsRecords.length === 0
+      ) {
+        return { selected: null, services: [] };
+      }
+
+      const sortedByPriority = this.dnsManager.sortByPriority(dnsRecords);
+
+      const lowestPriorityValue = sortedByPriority[0]?.priority;
+      const highestPriorityRecords = sortedByPriority.filter(
+        (record) => record.priority === lowestPriorityValue,
+      );
+
+      if (!healthChecks || healthChecks.length === 0) {
+        const { selected, nextIndex } = this.dnsManager.selectFromSrvRecords(
+          highestPriorityRecords,
+          algorithm,
+          this.currentIndex,
+        );
+        this.currentIndex = nextIndex;
+
+        if (!selected) {
+          return { selected: null, services: [] };
+        }
+
+        await this.metricsManager.updateSelectionMetrics(selected.name);
+
+        return {
+          selected: {
+            ip: selected.ip,
+            port: selected.port,
+          },
+          services: sortedByPriority.map((record) => ({
+            ip: record.ip,
+            port: record.port,
+          })),
+        };
+      }
+
+      const dnsWeights = new Map(
+        dnsRecords.map((record) => [
+          record.ip,
+          {
+            weight: record.weight,
+            port: record.port,
+            priority: record.priority,
+          },
+        ]),
+      );
+
+      const matchedHealthChecks = healthChecks.filter((check) =>
+        dnsWeights.has(check.Service.Address),
+      );
+
+      if (matchedHealthChecks.length === 0) {
+        if (this.debug) {
+          log.debug(
+            "No matching services found between DNS and Consul health checks",
+          );
+        }
+        const { selected, nextIndex } = this.dnsManager.selectFromSrvRecords(
+          highestPriorityRecords,
+          algorithm,
+          this.currentIndex,
+        );
+        this.currentIndex = nextIndex;
+
+        if (!selected) {
+          return { selected: null, services: [] };
+        }
+
+        await this.metricsManager.updateSelectionMetrics(selected.name);
+
+        return {
+          selected: {
+            ip: selected.ip,
+            port: selected.port,
+          },
+          services: sortedByPriority.map((record) => ({
+            ip: record.ip,
+            port: record.port,
+          })),
+        };
+      }
+
+      const highPriorityIPs = new Set(
+        highestPriorityRecords.map((record) => record.ip),
+      );
+      const highPriorityHealthChecks = matchedHealthChecks.filter((check) =>
+        highPriorityIPs.has(check.Service.Address),
+      );
+
+      const targetHealthChecks =
+        highPriorityHealthChecks.length > 0
+          ? highPriorityHealthChecks
+          : matchedHealthChecks;
+
+      const maxDNSWeight = Math.max(...dnsRecords.map((r) => r.weight || 1));
+
+      const enhancedHealthChecks = targetHealthChecks.map((check) => ({
+        ...check,
+        dnsWeight: combineHealthAndDNSWeights(
+          check,
+          dnsWeights.get(check.Service.Address)?.weight || 0,
+          maxDNSWeight,
+        ),
+      }));
+
+      const metrics =
+        await this.metricsManager.getServicesMetrics(targetHealthChecks);
+      let selectedService;
+
+      switch (algorithm) {
+        case SelectionAlgorithm.RoundRobin: {
+          const rrResult = roundRobinSelection(
+            enhancedHealthChecks,
+            this.currentIndex,
+          );
+          this.currentIndex = rrResult.nextIndex;
+          selectedService = { id: rrResult.id, service: rrResult.service };
+          break;
+        }
+        case SelectionAlgorithm.LeastConnection:
+          selectedService = leastConnectionSelection(
+            enhancedHealthChecks,
+            metrics,
+            this.metrics,
+          );
+          break;
+        case SelectionAlgorithm.WeightedRoundRobin: {
+          const rankedServices = rankServices(
+            enhancedHealthChecks,
+            metrics,
+            this.weights,
+          );
+          rankedServices.forEach((ranked) => {
+            const dnsInfo = dnsWeights.get(ranked.service.Service.Address);
+            if (dnsInfo) {
+              ranked.score *= 1 + dnsInfo.weight / maxDNSWeight;
+            }
+          });
+          selectedService = weightedRandomSelection(rankedServices);
+          break;
+        }
+      }
+
+      await this.metricsManager.updateSelectionMetrics(selectedService.id);
+
+      const selectedDNSInfo = dnsWeights.get(
+        selectedService.service.Service.Address,
+      );
+
+      return {
+        selected: {
+          ip: selectedService.service.Service.Address,
+          port: selectedDNSInfo?.port || selectedService.service.Service.Port,
+        },
+        services: matchedHealthChecks.map((check) => {
+          const dnsInfo = dnsWeights.get(check.Service.Address);
+          return {
+            ip: check.Service.Address,
+            port: dnsInfo?.port || check.Service.Port,
+          };
+        }),
+      };
+    } catch (error) {
+      if (this.debug) {
+        log.error("Error selecting optimal service:", error);
+      }
+      return { selected: null, services: [] };
+    }
+  }
+
+  async incrementConnections(serviceId) {
+    return this.metricsManager.incrementConnections(serviceId);
+  }
+
+  async decrementConnections(serviceId) {
+    return this.metricsManager.decrementConnections(serviceId);
+  }
+
+  async getSelectionMetrics(serviceId) {
+    return this.metricsManager.getSelectionMetrics(serviceId);
+  }
+
+  async refresh() {
+    try {
+      if (!this.cacheEnabled) {
+        if (this.debug) {
+          log.debug("Cache is disabled, no need to refresh");
+        }
+        return;
+      }
+      const pattern = `${this.cachePrefix}:*`;
+      const keys = await this.redis?.keys(pattern);
+
+      if (keys && keys.length > 0) {
+        await this.redis?.del(...keys);
+      }
+    } catch (error) {
+      console.log("Error refreshing Redis caches:", error);
+      throw new Error(`Failed to refresh caches: ${error.message}`);
+    }
+  }
+}
+
+exports.Resolver = Resolver;
+exports.SelectionAlgorithm = SelectionAlgorithm;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimble/consul",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Consul client",
   "main": "./lib",
   "types": "./lib/index.d.ts",
@@ -8,12 +8,17 @@
     "./lib"
   ],
   "dependencies": {
+    "@brimble/utils": "^1.5.59",
+    "dns-query": "^0.11.2",
+    "ioredis": "^5.3.2",
+    "lru-cache": "^11.1.0",
     "papi": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.7.6",
     "async": "^3.2.0",
     "debug": "^4.3.1",
+    "ioredis-mock": "^8.9.0",
     "jshint": "^2.5.5",
     "mocha": "^10.7.3",
     "nock": "^13.0.7",