@chainlink/external-adapter-framework 0.5.0 → 0.5.1

package/adapter/price.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriceAdapter = exports.PriceEndpoint = exports.priceEndpointInputParameters = void 0;
+const endpoint_1 = require("./endpoint");
+const index_1 = require("./index");
+/**
+ * Base input parameter config that any [[PriceEndpoint]] must extend
+ */
+exports.priceEndpointInputParameters = {
+    base: {
+        aliases: ['from', 'coin'],
+        type: 'string',
+        description: 'The symbol of symbols of the currency to query',
+        required: true,
+    },
+    quote: {
+        aliases: ['to', 'market'],
+        type: 'string',
+        description: 'The symbol of the currency to convert to',
+        required: true,
+    },
+};
+/**
+ * A PriceEndpoint is a specific type of AdapterEndpoint. Meant to comply with standard practices for
+ * Data Feeds, its InputParameters must extend the basic ones (base/quote).
+ */
+class PriceEndpoint extends endpoint_1.AdapterEndpoint {
+    constructor(params) {
+        super(params);
+    }
+}
+exports.PriceEndpoint = PriceEndpoint;
+const buildIncludesMap = (includesFile) => {
+    const includesMap = {};
+    for (const { from, to, includes } of includesFile) {
+        if (!includesMap[from]) {
+            includesMap[from] = {};
+        }
+        includesMap[from][to] = includes[0];
+    }
+    return includesMap;
+};
+/**
+ * A PriceAdapter is a specific kind of Adapter that includes at least one PriceEnpoint.
+ */
+class PriceAdapter extends index_1.Adapter {
+    constructor(params) {
+        // Doing this with types would be too complex to maintain
+        if (!params.endpoints.some((e) => e instanceof PriceEndpoint)) {
+            throw new Error(`This PriceAdapter's list of endpoints does not contain a valid PriceEndpoint`);
+        }
+        super(params);
+        if (params.includes) {
+            // Build includes map for constant lookups
+            this.includesMap = buildIncludesMap(params.includes);
+            const requestTransform = (req) => {
+                const priceRequest = req;
+                const requestData = priceRequest.requestContext.data;
+                const includesDetails = this.includesMap?.[requestData.base]?.[requestData.quote];
+                if (includesDetails) {
+                    requestData.base = includesDetails.from || requestData.base;
+                    requestData.quote = includesDetails.to || requestData.quote;
+                }
+                const inverse = includesDetails?.inverse || false;
+                priceRequest.requestContext.priceMeta = {
+                    inverse,
+                };
+            };
+            this.requestTransforms?.push(requestTransform);
+        }
+    }
+    async handleRequest(req, replySent) {
+        const response = await super.handleRequest(req, replySent);
+        if (this.includesMap && req.requestContext.priceMeta.inverse) {
+            // We need to search in the reverse order (quote -> base) because the request transform will have inverted the pair
+            const inverseResult = 1 / response.result;
+            response.result = inverseResult;
+            // Check if response data has a result within it
+            const data = response.data;
+            if (data?.result) {
+                data.result = inverseResult;
+            }
+        }
+        return response;
+    }
+}
+exports.PriceAdapter = PriceAdapter;
+//# sourceMappingURL=price.js.map

package/adapter/price.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.js","sourceRoot":"","sources":["../../../src/adapter/price.ts"],"names":[],"mappings":"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"}

package/adapter/types.d.ts

@@ -0,0 +1,124 @@
+import type EventSource from 'eventsource';
+import Redis from 'ioredis';
+import { Cache } from '../cache';
+import { AdapterConfig, BaseAdapterConfig, SettingsMap } from '../config';
+import { AdapterRateLimitTier, BackgroundExecuteRateLimiter, RequestRateLimiter } from '../rate-limiting';
+import { Transport, TransportGenerics } from '../transports';
+import { AdapterRequest, SubscriptionSetFactory } from '../util';
+import { InputParameters } from '../validation';
+import { Adapter } from './basic';
+import { AdapterEndpoint } from './endpoint';
+export declare type CustomAdapterSettings = SettingsMap & NegatedAdapterSettings;
+declare type NegatedAdapterSettings = {
+    [K in keyof BaseAdapterConfig]?: never;
+};
+/**
+ * Dependencies that will be injected into the Adapter on startup
+ */
+export interface AdapterDependencies {
+    /** Specific instance of the Cache the adapter will use (e.g. Local, Redis, etc.) */
+    cache: Cache;
+    /** Shared instance of the request rate limiter */
+    requestRateLimiter: RequestRateLimiter;
+    /** Shared instance of the background execute rate limiter */
+    backgroundExecuteRateLimiter: BackgroundExecuteRateLimiter;
+    /** Factory to create subscription sets based on the specified cache type */
+    subscriptionSetFactory: SubscriptionSetFactory;
+    /** Redis client used for cache and subscription set */
+    redisClient: Redis;
+    /** EventSource to use for listening to server sent events.  A mock EventSource can be provided as a dependency for testing */
+    eventSource: typeof EventSource;
+}
+/**
+ * Context that will be used on background executions of a Transport.
+ * For example, the endpointName used to log statements or generate Cache keys.
+ */
+export interface AdapterContext<T extends EndpointGenerics> {
+    /** Endpoint instance within the adapter that the Transport is related to */
+    adapterEndpoint: AdapterEndpoint<T>;
+    /** Initialized config for the adapter that the Transport can access */
+    adapterConfig: AdapterConfig<T['CustomSettings']>;
+}
+/**
+ * Structure to describe rate limits specs for the Adapter
+ */
+export interface AdapterRateLimitingConfig {
+    /** Adapter rate limits, gotten from the specific tier requested */
+    tiers: Record<string, AdapterRateLimitTier>;
+}
+/**
+ * Type to perform arbitrary modifications on an adapter request
+ */
+export declare type RequestTransform = (req: AdapterRequest) => void;
+/**
+ * Map of overrides objects (symbol -\> symbol) per adapter name
+ */
+export declare type Overrides = {
+    [adapterName: string]: {
+        [symbol: string]: string;
+    };
+};
+/**
+ * Main structure of an External Adapter
+ */
+export interface AdapterParams<CustomSettings extends SettingsMap> {
+    /** Name of the adapter */
+    name: Uppercase<string>;
+    /** If present, the string that will be used for requests with no specified endpoint */
+    defaultEndpoint?: string;
+    /**
+     * List of [[AdapterEndpoint]]s in the adapter. This is purposefully typed any; it's the correct type in this case.
+     *
+     * When you try to create an adapter and you provide an endpoint, if these generics were set to "unknown" instead
+     * what would happen is that Typescript would check if the types match, and would fail to assign unknown to the
+     * specific Params or Result in the transport itself.
+     * We also can't use generics, because if we had more than one transport with different requests (very likely)
+     * then those new types wouldn't match with each other.
+     */
+    endpoints: AdapterEndpoint<any>[];
+    /** Map of overrides to the default config values for an Adapter */
+    envDefaultOverrides?: Partial<BaseAdapterConfig>;
+    /** List of custom env vars for this particular adapter (e.g. RPC_URL) */
+    customSettings?: SettingsMap;
+    /** Configuration relevant to outbound (EA --\> DP) communication rate limiting */
+    rateLimiting?: AdapterRateLimitingConfig;
+    /** Overrides for converting the 'base' parameter that are hardcoded into the adapter. */
+    overrides?: Record<string, string>;
+    /** Transforms that will apply to the request before submitting it through the adapter request flow */
+    requestTransforms?: RequestTransform[];
+    /** Bootstrap function that will run when initializing the adapter */
+    bootstrap?: (adapter: Adapter<CustomSettings>) => Promise<void>;
+}
+/**
+ * Structure to describe rate limits specs for a specific adapter endpoint
+ */
+export interface EndpointRateLimitingConfig {
+    /**
+     * How much of the total limit for the adapter will be assigned to this specific endpoint.
+     * Should be a non-zero positive number up to 100.
+     * Endpoints in the same adapter without a specific allocation will divide the remaining limits equally.
+     */
+    allocationPercentage: number;
+}
+/**
+ * Helper type structure that contains the different types passed to the generic parameters of an AdapterEndpoint
+ */
+export declare type EndpointGenerics = TransportGenerics;
+/**
+ * Structure to describe a specific endpoint in an [[Adapter]]
+ */
+export interface AdapterEndpointParams<T extends EndpointGenerics> {
+    /** Name that will be used to match input params to this endpoint (case insensitive) */
+    name: string;
+    /** List of alternative endpoint names that will resolve to this same transport (case insensitive) */
+    aliases?: string[];
+    /** Transport that will be used to handle data processing and communication for this endpoint */
+    transport: Transport<T>;
+    /** Specification of what the body of a request hitting this endpoint should look like (used for validation) */
+    inputParameters: InputParameters;
+    /** Specific details related to the rate limiting for this endpoint in particular */
+    rateLimiting?: EndpointRateLimitingConfig;
+    /** Custom function that generates cache keys */
+    cacheKeyGenerator?: (data: Record<string, unknown>) => string;
+}
+export {};

package/adapter/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/adapter/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapter/types.ts"],"names":[],"mappings":""}

package/background-executor.d.ts

@@ -0,0 +1,9 @@
+import { Adapter } from './adapter';
+/**
+ * Very simple background loop that will call the [[Transport.backgroundExecute]] functions in all Transports.
+ * It gets the time in ms to wait as the return value from those functions, and sleeps until next execution.
+ *
+ * @param adapter - an initialized External Adapter
+ * @param server - the http server to attach an on close listener to
+ */
+export declare function callBackgroundExecutes(adapter: Adapter, apiShutdownPromise?: Promise<void>): Promise<void>;

package/background-executor.js

@@ -0,0 +1,97 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callBackgroundExecutes = void 0;
+const metrics = __importStar(require("./metrics"));
+const util_1 = require("./util");
+const logger = (0, util_1.makeLogger)('BackgroundExecutor');
+/**
+ * Very simple background loop that will call the [[Transport.backgroundExecute]] functions in all Transports.
+ * It gets the time in ms to wait as the return value from those functions, and sleeps until next execution.
+ *
+ * @param adapter - an initialized External Adapter
+ * @param server - the http server to attach an on close listener to
+ */
+async function callBackgroundExecutes(adapter, apiShutdownPromise) {
+    // Set up variable to check later on to see if we need to stop this background "thread"
+    // If no server is provided, the listener won't be set and serverClosed will always be false
+    let serverClosed = false;
+    const timeoutsMap = {};
+    apiShutdownPromise?.then(() => {
+        serverClosed = true;
+        for (const endpointName in timeoutsMap) {
+            logger.debug(`Clearing timeout for endpoint "${endpointName}"`);
+            timeoutsMap[endpointName].unref();
+            clearTimeout(timeoutsMap[endpointName]);
+        }
+    });
+    // Checks if an individual transport has a backgroundExecute function, and executes it if it does
+    const callBackgroundExecute = (endpoint, transport) => {
+        const backgroundExecute = transport.backgroundExecute?.bind(transport);
+        if (!backgroundExecute) {
+            logger.debug(`Endpoint "${endpoint.name}" has no background execute, skipping...`);
+            return;
+        }
+        const context = {
+            adapterEndpoint: endpoint,
+            adapterConfig: adapter.config,
+        };
+        const handler = async () => {
+            if (serverClosed) {
+                logger.info('Server closed, stopping recursive backgroundExecute handler chain');
+                return;
+            }
+            // Count number of background executions per endpoint
+            metrics.bgExecuteTotal.labels({ endpoint: endpoint.name }).inc();
+            // Time the duration of the background execute process excluding sleep time
+            const metricsTimer = metrics.bgExecuteDurationSeconds
+                .labels({ endpoint: endpoint.name })
+                .startTimer();
+            logger.debug(`Calling background execute for endpoint "${endpoint.name}"`);
+            const timeToWait = await backgroundExecute(context);
+            logger.debug(`Finished background execute for endpoint "${endpoint.name}", sleeping for ${timeToWait}ms`);
+            metricsTimer();
+            timeoutsMap[endpoint.name] = setTimeout(handler, timeToWait);
+        };
+        // Start recursive async calls
+        handler();
+    };
+    for (const endpoint of adapter.endpoints) {
+        const { transport } = endpoint;
+        // Check if transport is a MetaTransport by casting and checking a known property (transports)
+        const castMeta = transport;
+        if (castMeta.transports) {
+            logger.debug(`Encountered MetaTransport ${transport.constructor.name}, calling backgroundExecute on all transports`);
+            for (const nestedTransport of Object.values(castMeta.transports)) {
+                callBackgroundExecute(endpoint, nestedTransport);
+            }
+        }
+        else {
+            callBackgroundExecute(endpoint, transport);
+        }
+    }
+}
+exports.callBackgroundExecutes = callBackgroundExecutes;
+//# sourceMappingURL=background-executor.js.map

package/background-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-executor.js","sourceRoot":"","sources":["../../src/background-executor.ts"],"names":[],"mappings":"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"}

package/cache/factory.d.ts

@@ -0,0 +1,6 @@
+import Redis from 'ioredis';
+import { LocalCache } from './local';
+import { RedisCache } from './redis';
+export declare class CacheFactory {
+    static buildCache(cacheType: string, redisClient?: Redis): LocalCache<unknown> | RedisCache<unknown> | undefined;
+}

package/cache/factory.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheFactory = void 0;
+const util_1 = require("../util");
+const local_1 = require("./local");
+const redis_1 = require("./redis");
+const logger = (0, util_1.makeLogger)('CacheFactory');
+class CacheFactory {
+    static buildCache(cacheType, redisClient) {
+        logger.info(`Using "${cacheType}" cache.`);
+        switch (cacheType) {
+            case 'local':
+                return new local_1.LocalCache();
+            case 'redis': {
+                if (!redisClient) {
+                    throw new Error('Redis client undefined. Cannot create Redis cache');
+                }
+                return new redis_1.RedisCache(redisClient);
+            }
+        }
+    }
+}
+exports.CacheFactory = CacheFactory;
+//# sourceMappingURL=factory.js.map

package/cache/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/cache/factory.ts"],"names":[],"mappings":";;;AACA,kCAAoC;AACpC,mCAAoC;AACpC,mCAAoC;AAEpC,MAAM,MAAM,GAAG,IAAA,iBAAU,EAAC,cAAc,CAAC,CAAA;AACzC,MAAa,YAAY;IACvB,MAAM,CAAC,UAAU,CAAC,SAAiB,EAAE,WAAmB;QACtD,MAAM,CAAC,IAAI,CAAC,UAAU,SAAS,UAAU,CAAC,CAAA;QAC1C,QAAQ,SAAS,EAAE;YACjB,KAAK,OAAO;gBACV,OAAO,IAAI,kBAAU,EAAE,CAAA;YACzB,KAAK,OAAO,CAAC,CAAC;gBACZ,IAAI,CAAC,WAAW,EAAE;oBAChB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;iBACrE;gBACD,OAAO,IAAI,kBAAU,CAAC,WAAW,CAAC,CAAA;aACnC;SACF;IACH,CAAC;CACF;AAdD,oCAcC"}

package/cache/index.d.ts

@@ -0,0 +1,87 @@
+import { AdapterEndpoint } from '../adapter';
+import { AdapterConfig, SettingsMap } from '../config';
+import { AdapterResponse, sleep } from '../util';
+export * from './factory';
+export * from './local';
+export * from './redis';
+/**
+ * An object describing an entry in the cache.
+ * @typeParam T - the type of the entry's value
+ */
+export interface CacheEntry<T> {
+    key: string;
+    value: T;
+}
+/**
+ * Generic interface for a local or remote Cache.
+ * @typeParam T - the type of the cache entries' values
+ */
+export interface Cache<T = unknown> {
+    /**
+     * Gets an item from the Cache.
+     *
+     * @param key - the key of the desired entry for which to fetch its value
+     * @returns a Promise of the entry's value, or undefined if not found / expired.
+     */
+    get: (key: string) => Promise<T | undefined>;
+    /**
+     * Sets an item in the Cache.
+     *
+     * @param key - the key of the new entry
+     * @param value - the value of the new entry
+     * @param ttl - the time in milliseconds until the entry expires
+     * @returns an empty Promise that resolves when the entry has been set
+     */
+    set: (key: string, value: T, ttl: number) => Promise<void>;
+    /**
+     * Sets a list of items in the Cache.
+     *
+     * @param entries - a list of cache entries
+     * @param ttl - the time in milliseconds until the entries expire
+     * @returns an empty Promise that resolves when all entries have been set
+     */
+    setMany: (entries: CacheEntry<T>[], ttl: number) => Promise<void>;
+    /**
+     * Deletes the specified item from the Cache
+     *
+     * @param key - the key of the entry to be deleted
+     * @returns an empty Promise that resolves when the entry has been deleted
+     */
+    delete: (key: string) => Promise<void>;
+}
+export declare const calculateCacheKey: <T extends import("../transports").TransportGenerics>({ adapterEndpoint, adapterConfig, }: {
+    adapterEndpoint: AdapterEndpoint<T>;
+    adapterConfig: AdapterConfig<T["CustomSettings"]>;
+}, data: unknown) => string;
+export declare const calculateFeedId: <T extends import("../transports").TransportGenerics>({ adapterEndpoint, adapterConfig, }: {
+    adapterEndpoint: AdapterEndpoint<T>;
+    adapterConfig: AdapterConfig<T["CustomSettings"]>;
+}, data: unknown) => string;
+/**
+ * Calculates a unique key from the provided data.
+ *
+ * @param data - the request data/body, i.e. the adapter input params
+ * @param paramNames - the keys from adapter endpoint input parameters
+ * @returns the calculated unique key
+ *
+ * @example
+ * ```
+ * calculateKey({ base: 'ETH', quote: 'BTC' }, ['base','quote'])
+ * // equals `|base:eth|quote:btc`
+ * ```
+ */
+export declare const calculateKey: <CustomSettings extends SettingsMap>(data: unknown, paramNames: string[], adapterConfig: AdapterConfig<CustomSettings>) => string;
+export declare const calculateStaleness: (expirationTimestamp: number | undefined, ttl: number) => number;
+/**
+ * Polls the provided Cache for an AdapterResponse set in the provided key. If the maximum
+ * amount of retries is exceeded, it returns undefined instead.
+ *
+ * @param cache - a Cache instance
+ * @param key - the key generated from an AdapterRequest that corresponds to the desired AdapterResponse
+ * @param retry - current retry, only for internal use
+ * @returns the AdapterResponse if found, else undefined
+ */
+export declare const pollResponseFromCache: (cache: Cache<AdapterResponse>, key: string, options: {
+    maxRetries: number;
+    sleep: number;
+}, retry?: number) => Promise<AdapterResponse | undefined>;

package/cache/index.js

@@ -0,0 +1,133 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollResponseFromCache = exports.calculateStaleness = exports.calculateKey = exports.calculateFeedId = exports.calculateCacheKey = void 0;
+const util_1 = require("../util");
+__exportStar(require("./factory"), exports);
+__exportStar(require("./local"), exports);
+__exportStar(require("./redis"), exports);
+const logger = (0, util_1.makeLogger)('Cache');
+// Uses calculateKey to generate a unique key from the endpoint name, data, and input parameters
+const calculateCacheKey = ({ adapterEndpoint, adapterConfig, }, data) => {
+    const paramNames = Object.keys(adapterEndpoint.inputParameters);
+    if (paramNames.length === 0) {
+        logger.trace(`Using default cache key ${adapterConfig.DEFAULT_CACHE_KEY}`);
+        return adapterConfig.DEFAULT_CACHE_KEY;
+    }
+    const cacheKey = `${adapterEndpoint.name}-${(0, exports.calculateKey)(data, paramNames, adapterConfig)}`;
+    logger.trace(`Generated cache key for request: "${cacheKey}"`);
+    return cacheKey;
+};
+exports.calculateCacheKey = calculateCacheKey;
+const calculateFeedId = ({ adapterEndpoint, adapterConfig, }, data) => {
+    const paramNames = Object.keys(adapterEndpoint.inputParameters);
+    if (paramNames.length === 0) {
+        logger.trace(`Cannot generate Feed ID without input parameters`);
+        return 'N/A';
+    }
+    return (0, exports.calculateKey)(data, paramNames, adapterConfig);
+};
+exports.calculateFeedId = calculateFeedId;
+/**
+ * Calculates a unique key from the provided data.
+ *
+ * @param data - the request data/body, i.e. the adapter input params
+ * @param paramNames - the keys from adapter endpoint input parameters
+ * @returns the calculated unique key
+ *
+ * @example
+ * ```
+ * calculateKey({ base: 'ETH', quote: 'BTC' }, ['base','quote'])
+ * // equals `|base:eth|quote:btc`
+ * ```
+ */
+const calculateKey = (data, paramNames, adapterConfig) => {
+    if (data && typeof data !== 'object') {
+        throw new Error('Data to calculate cache key should be an object');
+    }
+    const params = data;
+    let cacheKey = '';
+    for (const paramName of paramNames) {
+        const param = params[paramName];
+        if (param === undefined) {
+            continue;
+        }
+        cacheKey += `|${paramName}:`;
+        switch (typeof param) {
+            case 'string':
+                cacheKey += param.toLowerCase();
+                break;
+            case 'number':
+            case 'boolean':
+                cacheKey += param.toString();
+                break;
+            case 'object':
+                // Force cache keys to only use performant properties of the input params.
+                // If the object were to be used, we'd have to sort its properties.
+                logger.debug(`Property "${paramName}" in request parameters is of type object, and won't be used in the cacheKey`);
+        }
+    }
+    if (cacheKey.length > adapterConfig.MAX_COMMON_KEY_SIZE) {
+        logger.warn(`Generated cache key for adapter request is bigger than the MAX_COMMON_KEY_SIZE and will be truncated`);
+        cacheKey = cacheKey.slice(0, adapterConfig.MAX_COMMON_KEY_SIZE);
+    }
+    return cacheKey;
+};
+exports.calculateKey = calculateKey;
+// Calculate the amount of time a non-expired entry has been in the cache
+const calculateStaleness = (expirationTimestamp, ttl) => {
+    if (expirationTimestamp) {
+        const createTimestamp = expirationTimestamp - ttl;
+        return (Date.now() - createTimestamp) / 1000;
+    }
+    else {
+        // If expirationTimestamp is not available, staleness cannot be calculated
+        // Defaults to ttl for metrics purposes
+        return ttl;
+    }
+};
+exports.calculateStaleness = calculateStaleness;
+/**
+ * Polls the provided Cache for an AdapterResponse set in the provided key. If the maximum
+ * amount of retries is exceeded, it returns undefined instead.
+ *
+ * @param cache - a Cache instance
+ * @param key - the key generated from an AdapterRequest that corresponds to the desired AdapterResponse
+ * @param retry - current retry, only for internal use
+ * @returns the AdapterResponse if found, else undefined
+ */
+const pollResponseFromCache = async (cache, key, options, retry = 0) => {
+    if (retry > options.maxRetries) {
+        // Ideally this shouldn't happen often (p99 of reqs should be found in the cache)
+        logger.info('Exceeded max cache polling retries');
+        return undefined;
+    }
+    logger.trace('Getting response from cache...');
+    const response = await cache.get(key);
+    if (response) {
+        logger.trace('Got response from cache');
+        return response;
+    }
+    if (options.maxRetries === 0) {
+        logger.debug(`Response not found, retries disabled`);
+        return undefined;
+    }
+    logger.debug(`Response not found, sleeping ${options.sleep} milliseconds...`);
+    await (0, util_1.sleep)(options.sleep);
+    return (0, exports.pollResponseFromCache)(cache, key, options, retry + 1);
+};
+exports.pollResponseFromCache = pollResponseFromCache;
+//# sourceMappingURL=index.js.map

package/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAEA,kCAA4D;AAE5D,4CAAyB;AACzB,0CAAuB;AACvB,0CAAuB;AAEvB,MAAM,MAAM,GAAG,IAAA,iBAAU,EAAC,OAAO,CAAC,CAAA;AAoDlC,gGAAgG;AACzF,MAAM,iBAAiB,GAAG,CAC/B,EACE,eAAe,EACf,aAAa,GAId,EACD,IAAa,EACL,EAAE;IACV,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,CAAA;IAC/D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;QAC3B,MAAM,CAAC,KAAK,CAAC,2BAA2B,aAAa,CAAC,iBAAiB,EAAE,CAAC,CAAA;QAC1E,OAAO,aAAa,CAAC,iBAAiB,CAAA;KACvC;IACD,MAAM,QAAQ,GAAG,GAAG,eAAe,CAAC,IAAI,IAAI,IAAA,oBAAY,EAAC,IAAI,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,CAAA;IAC3F,MAAM,CAAC,KAAK,CAAC,qCAAqC,QAAQ,GAAG,CAAC,CAAA;IAC9D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAlBY,QAAA,iBAAiB,qBAkB7B;AAEM,MAAM,eAAe,GAAG,CAC7B,EACE,eAAe,EACf,aAAa,GAId,EACD,IAAa,EACL,EAAE;IACV,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,CAAA;IAC/D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;QAC3B,MAAM,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAA;QAChE,OAAO,KAAK,CAAA;KACb;IACD,OAAO,IAAA,oBAAY,EAAC,IAAI,EAAE,UAAU,EAAE,aAAa,CAAC,CAAA;AACtD,CAAC,CAAA;AAhBY,QAAA,eAAe,mBAgB3B;AAED;;;;;;;;;;;;GAYG;AACI,MAAM,YAAY,GAAG,CAC1B,IAAa,EACb,UAAoB,EACpB,aAA4C,EACpC,EAAE;IACV,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE;QACpC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;KACnE;IAED,MAAM,MAAM,GAAG,IAA+B,CAAA;IAE9C,IAAI,QAAQ,GAAG,EAAE,CAAA;IACjB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE;YACvB,SAAQ;SACT;QAED,QAAQ,IAAI,IAAI,SAAS,GAAG,CAAA;QAC5B,QAAQ,OAAO,KAAK,EAAE;YACpB,KAAK,QAAQ;gBACX,QAAQ,IAAI,KAAK,CAAC,WAAW,EAAE,CAAA;gBAC/B,MAAK;YACP,KAAK,QAAQ,CAAC;YACd,KAAK,SAAS;gBACZ,QAAQ,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAA;gBAC5B,MAAK;YACP,KAAK,QAAQ;gBACX,0EAA0E;gBAC1E,mEAAmE;gBACnE,MAAM,CAAC,KAAK,CACV,aAAa,SAAS,8EAA8E,CACrG,CAAA;SACJ;KACF;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,aAAa,CAAC,mBAAmB,EAAE;QACvD,MAAM,CAAC,IAAI,CACT,sGAAsG,CACvG,CAAA;QACD,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAA;KAChE;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AA5CY,QAAA,YAAY,gBA4CxB;AAED,yEAAyE;AAClE,MAAM,kBAAkB,GAAG,CAChC,mBAAuC,EACvC,GAAW,EACH,EAAE;IACV,IAAI,mBAAmB,EAAE;QACvB,MAAM,eAAe,GAAG,mBAAmB,GAAG,GAAG,CAAA;QACjD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC,GAAG,IAAI,CAAA;KAC7C;SAAM;QACL,0EAA0E;QAC1E,uCAAuC;QACvC,OAAO,GAAG,CAAA;KACX;AACH,CAAC,CAAA;AAZY,QAAA,kBAAkB,sBAY9B;AAED;;;;;;;;GAQG;AACI,MAAM,qBAAqB,GAAG,KAAK,EACxC,KAA6B,EAC7B,GAAW,EACX,OAGC,EACD,KAAK,GAAG,CAAC,EAC6B,EAAE;IACxC,IAAI,KAAK,GAAG,OAAO,CAAC,UAAU,EAAE;QAC9B,iFAAiF;QACjF,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAA;QACjD,OAAO,SAAS,CAAA;KACjB;IAED,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAA;IAC9C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,QAAQ,EAAE;QACZ,MAAM,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAA;QACvC,OAAO,QAAQ,CAAA;KAChB;IAED,IAAI,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE;QAC5B,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAA;QACpD,OAAO,SAAS,CAAA;KACjB;IAED,MAAM,CAAC,KAAK,CAAC,gCAAgC,OAAO,CAAC,KAAK,kBAAkB,CAAC,CAAA;IAC7E,MAAM,IAAA,YAAK,EAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAE1B,OAAO,IAAA,6BAAqB,EAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;AAC9D,CAAC,CAAA;AA/BY,QAAA,qBAAqB,yBA+BjC"}

package/cache/local.d.ts

@@ -0,0 +1,23 @@
+import { Cache, CacheEntry } from './index';
+/**
+ * Type for a value stored in a LocalCache entry.
+ *
+ * @typeParam T - the type for the entry's value
+ */
+export interface LocalCacheEntry<T> {
+    expirationTimestamp: number;
+    value: T;
+}
+/**
+ * Local implementation of a Cache. It uses a simple js Object, storing entries with both
+ * a value and an expiration timestamp. Expired entries are deleted on reads (i.e. no background gc/upkeep).
+ *
+ * @typeParam T - the type for the entries' values
+ */
+export declare class LocalCache<T = unknown> implements Cache<T> {
+    store: Record<string, LocalCacheEntry<T>>;
+    get(key: string): Promise<T | undefined>;
+    delete(key: string): Promise<void>;
+    set(key: string, value: T, ttl: number): Promise<void>;
+    setMany(entries: CacheEntry<T>[], ttl: number): Promise<void>;
+}