@hazeljs/gateway 0.2.0-beta.41

package/dist/proxy/service-proxy.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Service Proxy
+ * Enhanced HTTP client that integrates discovery, resilience, and traffic policies.
+ * The core request engine of the gateway.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceProxy = void 0;
+const axios_1 = __importDefault(require("axios"));
+const resilience_1 = require("@hazeljs/resilience");
+class ServiceProxy {
+    constructor(discoveryClient, config) {
+        this.discoveryClient = discoveryClient;
+        this.config = config;
+        this.axiosInstance = axios_1.default.create({
+            timeout: config.timeout ?? 10000,
+        });
+        this.metrics = new resilience_1.MetricsCollector(60000);
+        // Initialize resilience components
+        if (config.retry) {
+            this.retryPolicy = new resilience_1.RetryPolicy(config.retry);
+        }
+        if (config.circuitBreaker) {
+            const breakerName = `gateway:${config.serviceName}`;
+            this.circuitBreaker = resilience_1.CircuitBreakerRegistry.getOrCreate(breakerName, config.circuitBreaker);
+        }
+        if (config.timeout) {
+            this.timeout = new resilience_1.Timeout(config.timeout);
+        }
+        if (config.rateLimit) {
+            this.rateLimiter = new resilience_1.RateLimiter(config.rateLimit);
+        }
+    }
+    /**
+     * Forward an incoming request to the target service
+     */
+    async forward(request) {
+        // Apply rate limiting — reject with 429 when limit exceeded
+        if (this.rateLimiter) {
+            if (!this.rateLimiter.tryAcquire()) {
+                const retryAfterMs = this.rateLimiter.getRetryAfterMs();
+                throw new resilience_1.RateLimitError(`Rate limit exceeded for ${this.config.serviceName}. Retry after ${retryAfterMs}ms`, retryAfterMs);
+            }
+        }
+        // Apply request transformation
+        let transformedRequest = request;
+        if (this.config.transform?.request) {
+            transformedRequest = this.config.transform.request(request);
+        }
+        // Build the execution function
+        const executeFn = async () => {
+            return this.doForward(transformedRequest);
+        };
+        // Wrap with resilience layers
+        let wrappedFn = executeFn;
+        // Retry wraps the inner call
+        if (this.retryPolicy) {
+            const retryPolicy = this.retryPolicy;
+            const innerFn = wrappedFn;
+            wrappedFn = () => retryPolicy.execute(innerFn);
+        }
+        // Circuit breaker wraps retry
+        if (this.circuitBreaker) {
+            const breaker = this.circuitBreaker;
+            const innerFn = wrappedFn;
+            wrappedFn = () => breaker.execute(innerFn);
+        }
+        // Timeout wraps circuit breaker
+        if (this.timeout) {
+            const timeout = this.timeout;
+            const innerFn = wrappedFn;
+            wrappedFn = () => timeout.execute(innerFn);
+        }
+        const startTime = Date.now();
+        try {
+            const response = await wrappedFn();
+            this.metrics.recordSuccess(Date.now() - startTime);
+            // Apply response transformation
+            if (this.config.transform?.response) {
+                return this.config.transform.response(response);
+            }
+            return response;
+        }
+        catch (error) {
+            this.metrics.recordFailure(Date.now() - startTime, String(error));
+            throw error;
+        }
+    }
+    /**
+     * Forward a request with a specific version filter
+     */
+    async forwardToVersion(request, version, additionalFilter) {
+        const filter = {
+            ...this.config.filter,
+            ...additionalFilter,
+            metadata: {
+                ...this.config.filter?.metadata,
+                ...additionalFilter?.metadata,
+                version,
+            },
+        };
+        return this.forwardWithFilter(request, filter);
+    }
+    /**
+     * Forward with a custom filter override
+     */
+    async forwardWithFilter(request, filter) {
+        const instance = await this.discoveryClient.getInstance(this.config.serviceName, this.config.loadBalancingStrategy, filter);
+        if (!instance) {
+            throw new Error(`No instances available for service: ${this.config.serviceName} with filter`);
+        }
+        return this.doForwardToInstance(request, instance);
+    }
+    /**
+     * Get the metrics collector for this proxy
+     */
+    getMetrics() {
+        return this.metrics;
+    }
+    /**
+     * Get the circuit breaker instance (if configured)
+     */
+    getCircuitBreaker() {
+        return this.circuitBreaker;
+    }
+    /**
+     * Get the service name this proxy routes to
+     */
+    getServiceName() {
+        return this.config.serviceName;
+    }
+    // ─── Internal ───
+    async doForward(request) {
+        const instance = await this.discoveryClient.getInstance(this.config.serviceName, this.config.loadBalancingStrategy, this.config.filter);
+        if (!instance) {
+            throw new Error(`No instances available for service: ${this.config.serviceName}`);
+        }
+        return this.doForwardToInstance(request, instance);
+    }
+    async doForwardToInstance(request, instance) {
+        // Build the target path
+        let targetPath = request.path;
+        if (this.config.stripPrefix && targetPath.startsWith(this.config.stripPrefix)) {
+            targetPath = targetPath.slice(this.config.stripPrefix.length) || '/';
+        }
+        if (this.config.addPrefix) {
+            targetPath = this.config.addPrefix + targetPath;
+        }
+        // Normalize: remove trailing slash so "/users/" becomes "/users".
+        // This avoids 404s when the backend registers routes without a trailing slash.
+        if (targetPath.length > 1 && targetPath.endsWith('/')) {
+            targetPath = targetPath.slice(0, -1);
+        }
+        const baseURL = `${instance.protocol || 'http'}://${instance.host}:${instance.port}`;
+        // Strip hop-by-hop headers that are specific to the client↔gateway connection.
+        // These must NOT be forwarded to the upstream service because:
+        //   - content-length: the body is re-serialized by axios, so the original
+        //     content-length would be wrong and the upstream would hang waiting for
+        //     exactly that many bytes.
+        //   - transfer-encoding: same issue — axios chooses its own encoding.
+        //   - connection / keep-alive: per-hop, not end-to-end.
+        const HOP_BY_HOP = new Set([
+            'content-length',
+            'transfer-encoding',
+            'connection',
+            'keep-alive',
+            'upgrade',
+            'expect',
+            'host',
+            'te',
+            'trailer',
+        ]);
+        const headers = {};
+        for (const [key, value] of Object.entries(request.headers)) {
+            if (value !== undefined && !HOP_BY_HOP.has(key.toLowerCase())) {
+                headers[key] = Array.isArray(value) ? value.join(', ') : value;
+            }
+        }
+        headers['host'] = `${instance.host}:${instance.port}`;
+        const axiosConfig = {
+            method: request.method,
+            url: targetPath,
+            baseURL,
+            headers,
+            data: request.body,
+            params: request.query,
+        };
+        try {
+            const response = await this.axiosInstance.request(axiosConfig);
+            return {
+                status: response.status,
+                headers: response.headers,
+                body: response.data,
+            };
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error) && error.response) {
+                return {
+                    status: error.response.status,
+                    headers: error.response.headers,
+                    body: error.response.data,
+                };
+            }
+            throw error;
+        }
+    }
+}
+exports.ServiceProxy = ServiceProxy;

package/dist/routing/route-matcher.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Route Matcher
+ * Matches incoming request paths against gateway route patterns.
+ * Supports glob patterns (/**), path parameters (:param), and wildcards (*).
+ */
+export interface RouteMatch {
+    /** Whether the pattern matched */
+    matched: boolean;
+    /** Extracted path parameters */
+    params: Record<string, string>;
+    /** The remaining path after the matched prefix (for proxying) */
+    remainingPath: string;
+}
+/**
+ * Convert a route pattern to a regex for matching
+ *
+ * Patterns:
+ *   /api/users         -> exact match
+ *   /api/users/:id     -> path parameter
+ *   /api/users/*       -> single segment wildcard
+ *   /api/users/**      -> multi-segment wildcard (greedy)
+ */
+export declare function matchRoute(pattern: string, path: string): RouteMatch;
+/**
+ * Sort route patterns by specificity (most specific first)
+ * Rules:
+ *   1. Exact paths > parameterized paths > wildcards > catch-all
+ *   2. Longer paths > shorter paths
+ */
+export declare function sortRoutesBySpecificity(patterns: string[]): string[];
+//# sourceMappingURL=route-matcher.d.ts.map

package/dist/routing/route-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../../src/routing/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAoDpE;AAgBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAOpE"}

package/dist/routing/route-matcher.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Route Matcher
+ * Matches incoming request paths against gateway route patterns.
+ * Supports glob patterns (/**), path parameters (:param), and wildcards (*).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchRoute = matchRoute;
+exports.sortRoutesBySpecificity = sortRoutesBySpecificity;
+/**
+ * Convert a route pattern to a regex for matching
+ *
+ * Patterns:
+ *   /api/users         -> exact match
+ *   /api/users/:id     -> path parameter
+ *   /api/users/*       -> single segment wildcard
+ *   /api/users/**      -> multi-segment wildcard (greedy)
+ */
+function matchRoute(pattern, path) {
+    const noMatch = { matched: false, params: {}, remainingPath: '' };
+    // Normalize paths
+    const normPattern = normalizePath(pattern);
+    const normPath = normalizePath(path);
+    // Handle exact "**" at end (catch-all)
+    if (normPattern.endsWith('/**')) {
+        const prefix = normPattern.slice(0, -3); // Remove /**
+        if (normPath === prefix || normPath.startsWith(prefix + '/')) {
+            const remaining = normPath.slice(prefix.length) || '/';
+            return {
+                matched: true,
+                params: {},
+                remainingPath: remaining,
+            };
+        }
+        return noMatch;
+    }
+    // Split into segments
+    const patternSegments = normPattern.split('/').filter(Boolean);
+    const pathSegments = normPath.split('/').filter(Boolean);
+    // Different segment counts means no match (unless there's a wildcard)
+    if (patternSegments.length !== pathSegments.length) {
+        return noMatch;
+    }
+    const params = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+        const pSeg = patternSegments[i];
+        const rSeg = pathSegments[i];
+        if (pSeg.startsWith(':')) {
+            // Path parameter
+            params[pSeg.slice(1)] = rSeg;
+        }
+        else if (pSeg === '*') {
+            // Single-segment wildcard, matches anything
+            continue;
+        }
+        else if (pSeg !== rSeg) {
+            return noMatch;
+        }
+    }
+    return {
+        matched: true,
+        params,
+        remainingPath: normPath,
+    };
+}
+/**
+ * Normalize a path: ensure leading slash, remove trailing slash
+ */
+function normalizePath(path) {
+    let normalized = path;
+    if (!normalized.startsWith('/')) {
+        normalized = '/' + normalized;
+    }
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/**
+ * Sort route patterns by specificity (most specific first)
+ * Rules:
+ *   1. Exact paths > parameterized paths > wildcards > catch-all
+ *   2. Longer paths > shorter paths
+ */
+function sortRoutesBySpecificity(patterns) {
+    return [...patterns].sort((a, b) => {
+        const aScore = getSpecificityScore(a);
+        const bScore = getSpecificityScore(b);
+        if (aScore !== bScore)
+            return bScore - aScore; // Higher score = more specific
+        return b.length - a.length; // Longer = more specific
+    });
+}
+function getSpecificityScore(pattern) {
+    const segments = pattern.split('/').filter(Boolean);
+    let score = segments.length * 10; // Base score from segment count
+    for (const seg of segments) {
+        if (seg === '**') {
+            score -= 5; // Catch-all is least specific
+        }
+        else if (seg === '*') {
+            score -= 3; // Single wildcard
+        }
+        else if (seg.startsWith(':')) {
+            score -= 1; // Parameter
+        }
+        else {
+            score += 2; // Exact segment is most specific
+        }
+    }
+    return score;
+}

package/dist/routing/version-router.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Version Router
+ * Routes requests to specific service versions based on:
+ *   - Header (X-API-Version)
+ *   - URI prefix (/v2/api/...)
+ *   - Query parameter (?version=v2)
+ *   - Weighted random (percentage-based)
+ */
+import { VersionRouteConfig, VersionRouteEntry, ProxyRequest } from '../types';
+export interface VersionResolution {
+    /** The resolved version to route to */
+    version: string;
+    /** How the version was resolved */
+    resolvedBy: 'header' | 'uri' | 'query' | 'weight' | 'default';
+}
+export declare class VersionRouter {
+    private config;
+    constructor(config: VersionRouteConfig);
+    /**
+     * Resolve the target version for an incoming request
+     */
+    resolve(request: ProxyRequest): VersionResolution;
+    /**
+     * Get the version configuration for a specific version
+     */
+    getVersionEntry(version: string): VersionRouteEntry | undefined;
+    /**
+     * Get all configured versions
+     */
+    getVersions(): string[];
+    private resolveFromHeader;
+    private resolveFromUri;
+    private resolveFromQuery;
+    private resolveByWeight;
+}
+//# sourceMappingURL=version-router.d.ts.map

package/dist/routing/version-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-router.d.ts","sourceRoot":"","sources":["../../src/routing/version-router.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,UAAU,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC/D;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAqB;gBAEvB,MAAM,EAAE,kBAAkB;IAStC;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,iBAAiB;IAuCjD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI/D;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAMvB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,eAAe;CA6BxB"}

package/dist/routing/version-router.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Version Router
+ * Routes requests to specific service versions based on:
+ *   - Header (X-API-Version)
+ *   - URI prefix (/v2/api/...)
+ *   - Query parameter (?version=v2)
+ *   - Weighted random (percentage-based)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionRouter = void 0;
+class VersionRouter {
+    constructor(config) {
+        this.config = {
+            strategy: config.strategy ?? 'header',
+            header: config.header ?? 'X-API-Version',
+            queryParam: config.queryParam ?? 'version',
+            ...config,
+        };
+    }
+    /**
+     * Resolve the target version for an incoming request
+     */
+    resolve(request) {
+        // 1. Try explicit version from header
+        if (this.config.strategy === 'header' || !this.config.strategy) {
+            const headerVersion = this.resolveFromHeader(request);
+            if (headerVersion)
+                return headerVersion;
+        }
+        // 2. Try explicit version from URI
+        if (this.config.strategy === 'uri') {
+            const uriVersion = this.resolveFromUri(request);
+            if (uriVersion)
+                return uriVersion;
+        }
+        // 3. Try explicit version from query
+        if (this.config.strategy === 'query') {
+            const queryVersion = this.resolveFromQuery(request);
+            if (queryVersion)
+                return queryVersion;
+        }
+        // 4. Fall back to weighted selection
+        const weightedVersion = this.resolveByWeight();
+        if (weightedVersion)
+            return weightedVersion;
+        // 5. Fall back to default version
+        if (this.config.defaultVersion) {
+            return {
+                version: this.config.defaultVersion,
+                resolvedBy: 'default',
+            };
+        }
+        // 6. Use the first defined version
+        const firstVersion = Object.keys(this.config.routes)[0];
+        return {
+            version: firstVersion,
+            resolvedBy: 'default',
+        };
+    }
+    /**
+     * Get the version configuration for a specific version
+     */
+    getVersionEntry(version) {
+        return this.config.routes[version];
+    }
+    /**
+     * Get all configured versions
+     */
+    getVersions() {
+        return Object.keys(this.config.routes);
+    }
+    // ─── Resolution Strategies ───
+    resolveFromHeader(request) {
+        const headerName = this.config.header;
+        const headerValue = request.headers[headerName] || request.headers[headerName.toLowerCase()];
+        if (headerValue && typeof headerValue === 'string') {
+            const version = headerValue.trim();
+            const entry = this.config.routes[version];
+            if (entry && (entry.weight > 0 || entry.allowExplicit)) {
+                return { version, resolvedBy: 'header' };
+            }
+        }
+        return null;
+    }
+    resolveFromUri(request) {
+        // Extract version from URI like /v2/api/users -> v2
+        const match = request.path.match(/^\/(v\d+)(\/.*)?$/);
+        if (match) {
+            const version = match[1];
+            const entry = this.config.routes[version];
+            if (entry && (entry.weight > 0 || entry.allowExplicit)) {
+                return { version, resolvedBy: 'uri' };
+            }
+        }
+        return null;
+    }
+    resolveFromQuery(request) {
+        const paramName = this.config.queryParam;
+        const version = request.query?.[paramName];
+        if (version) {
+            const entry = this.config.routes[version];
+            if (entry && (entry.weight > 0 || entry.allowExplicit)) {
+                return { version, resolvedBy: 'query' };
+            }
+        }
+        return null;
+    }
+    resolveByWeight() {
+        // Collect versions with weight > 0
+        const weighted = [];
+        let totalWeight = 0;
+        for (const [version, entry] of Object.entries(this.config.routes)) {
+            if (entry.weight > 0) {
+                weighted.push({ version, weight: entry.weight });
+                totalWeight += entry.weight;
+            }
+        }
+        if (weighted.length === 0 || totalWeight === 0)
+            return null;
+        // Weighted random selection
+        let random = Math.random() * totalWeight;
+        for (const item of weighted) {
+            random -= item.weight;
+            if (random <= 0) {
+                return { version: item.version, resolvedBy: 'weight' };
+            }
+        }
+        // Fallback (shouldn't reach here due to float precision)
+        return {
+            version: weighted[weighted.length - 1].version,
+            resolvedBy: 'weight',
+        };
+    }
+}
+exports.VersionRouter = VersionRouter;