@chainlink/external-adapter-framework 0.0.25 → 0.0.26

package/transports/websocket.d.ts

@@ -0,0 +1,80 @@
+import WebSocket from 'ws';
+import { AdapterContext, AdapterDependencies } from '../adapter';
+import { Cache } from '../cache';
+import { AdapterConfig, SettingsMap } from '../config';
+import { BackgroundExecuteRateLimiter } from '../rate-limiting';
+import { SubscriptionSet } from '../util';
+import { AdapterRequest, ProviderResult } from '../util/request';
+import { Transport } from './';
+declare type WebSocketClass = new (url: string, protocols?: string | string[] | undefined) => WebSocket;
+export declare class WebSocketClassProvider {
+    static ctor: WebSocketClass;
+    static set(ctor: WebSocketClass): void;
+    static get(): WebSocketClass;
+}
+/**
+ * Config object that is provided to the WebSocketTransport constructor.
+ */
+export interface WebSocketTransportConfig<AdapterParams, ProviderDataMessage, CustomSettings extends SettingsMap> {
+    /** Endpoint to which to open the WS connection*/
+    url: string;
+    /** Map of handlers for different WS lifecycle events */
+    handlers: {
+        /**
+         * Handles when the WS is successfully opened
+         *
+         * @param wsConnection - the WebSocket with an established connection
+         * @returns an empty Promise, or void
+         */
+        open: (wsConnection: WebSocket, context: AdapterContext<CustomSettings>) => Promise<void> | void;
+        /**
+         * Handles when the WS receives a message
+         *
+         * @param message - the message received by the WS
+         * @param context - the background context for the Adapter
+         * @returns a list of cache entries of adapter responses to set in the cache
+         */
+        message: (message: ProviderDataMessage, context: AdapterContext<CustomSettings>) => ProviderResult<AdapterParams>[];
+    };
+    /** Map of "builders", functions that will be used to prepare specific WS messages */
+    builders: {
+        /**
+         * Builds a WS message that will be sent to subscribe to a specific feed
+         *
+         * @param params - the body of the adapter request
+         * @returns the WS message (can be any type as long as the [[WebSocket]] doesn't complain)
+         */
+        subscribeMessage: (params: AdapterParams) => unknown;
+        /**
+         * Builds a WS message that will be sent to unsubscribe to a specific feed
+         *
+         * @param params - the body of the adapter request
+         * @returns the WS message (can be any type as long as the [[WebSocket]] doesn't complain)
+         */
+        unsubscribeMessage: (params: AdapterParams) => unknown;
+    };
+}
+/**
+ * Transport implementation that takes incoming requests, adds them to an [[subscriptionSet]] and,
+ * through a WebSocket connection, subscribes to the relevant feeds to populate the cache.
+ *
+ * @typeParam AdapterParams - interface for the adapter request body
+ * @typeParam ProviderDataMessage - interface for a WS message containing processable data (i.e. not part of open/close/login/etc)
+ */
+export declare class WebSocketTransport<AdapterParams, ProviderDataMessage, CustomSettings extends SettingsMap> implements Transport<AdapterParams, null, CustomSettings> {
+    private config;
+    cache: Cache;
+    rateLimiter: BackgroundExecuteRateLimiter;
+    subscriptionSet: SubscriptionSet<AdapterParams>;
+    localSubscriptions: AdapterParams[];
+    wsConnection: WebSocket;
+    constructor(config: WebSocketTransportConfig<AdapterParams, ProviderDataMessage, CustomSettings>);
+    initialize(dependencies: AdapterDependencies): Promise<void>;
+    hasBeenSetUp(req: AdapterRequest<AdapterParams>): Promise<boolean>;
+    setup(req: AdapterRequest<AdapterParams>, config: AdapterConfig<CustomSettings>): Promise<void>;
+    serializeMessage(payload: unknown): string;
+    deserializeMessage(data: WebSocket.Data): ProviderDataMessage;
+    establishWsConnection(context: AdapterContext<CustomSettings>): Promise<unknown>;
+    backgroundExecute(context: AdapterContext<CustomSettings>): Promise<number>;
+}
+export {};

package/util/index.d.ts

@@ -0,0 +1,12 @@
+export * from './request';
+export * from './logger';
+export * from './subscription-set/subscription-set';
+/**
+ * Sleeps for the provided number of milliseconds
+ * @param ms - The number of milliseconds to sleep for
+ * @returns a Promise that resolves once the specified time passes
+ */
+export declare const sleep: (ms: number) => Promise<void>;
+export declare const isObject: (o: unknown) => boolean;
+export declare const isArray: (o: unknown) => boolean;
+export declare type PromiseOrValue<T> = Promise<T> | T;

package/util/logger.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+import pino from 'pino';
+import { AdapterRequest } from './request';
+import { FastifyReply, HookHandlerDoneFunction } from 'fastify';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export declare const asyncLocalStorage: AsyncLocalStorage<unknown>;
+export declare type Store = {
+    correlationId: string;
+};
+/**
+ * Instead of using a global logger instance, we want to force using a child logger
+ * with a specific layer set in it, so that we can filter logs by where they're output from.
+ *
+ * Details on what each log level represents:
+ * "trace": Forensic debugging of issues on a local machine.
+ * "debug": Detailed logging level to get more context from users on their environments.
+ * "info": High-level informational messages, to describe at a glance the high level state of the system.
+ * "warn": A mild error occurred that might require non-urgent action.
+ * "error": An unexpected error occurred during the regular operation of a well-maintained EA.
+ * "fatal": The EA encountered an unrecoverable problem and had to exit.
+ *
+ * Full reference this is based on can be found at
+ * https://github.com/smartcontractkit/documentation/blob/main/docs/Node%20Operators/configuration-variables.md#log_level
+ *
+ * @param layer - the layer name to include in the logs (e.g. "SomeMiddleware", "RedisCache", etc.)
+ * @returns a layer specific logger
+ */
+export declare const makeLogger: (layer: string) => pino.Logger<{
+    level: string;
+    mixin(): {};
+    transport: {
+        target: string;
+        options: {
+            levelFirst: boolean;
+            levelLabel: string;
+            ignore: string;
+            messageFormat: string;
+            translateTime: string;
+        };
+    } | undefined;
+} & pino.ChildLoggerOptions>;
+export declare const loggingContextMiddleware: (req: AdapterRequest, res: FastifyReply, done: HookHandlerDoneFunction) => void;

package/util/request.d.ts

@@ -0,0 +1,56 @@
+import { FastifyReply, FastifyRequest, HookHandlerDoneFunction } from 'fastify';
+import { Adapter } from '../adapter';
+import { AdapterError } from '../validation/error';
+declare module 'fastify' {
+    interface FastifyRequest {
+        requestContext: AdapterRequestContext;
+    }
+}
+export interface AdapterRequestBody<T = AdapterRequestData> {
+    endpoint?: string;
+    data: T;
+    id?: string;
+}
+export declare type AdapterRequestContext<T = AdapterRequestData> = {
+    id: string;
+    endpointName: string;
+    cacheKey: string;
+    data: T;
+    meta?: AdapterRequestMeta;
+};
+export declare type AdapterRouteGeneric<T = AdapterRequestData> = {
+    Body: AdapterRequestBody<T>;
+};
+export declare type AdapterRequest<T = AdapterRequestData> = FastifyRequest<AdapterRouteGeneric<T>> & {
+    requestContext: AdapterRequestContext<T>;
+};
+/**
+ * Meta info that pertains to exposing metrics
+ */
+export interface AdapterRequestMeta {
+    metrics?: AdapterMetricsMeta;
+    error?: AdapterError | Error;
+}
+/**
+ * Meta info that pertains to exposing metrics
+ */
+export interface AdapterMetricsMeta {
+    feedId?: string;
+    cacheHit?: boolean;
+}
+export declare type AdapterRequestData = Record<string, unknown> & {
+    endpoint?: string;
+};
+export interface ProviderResult<Params> {
+    params: Params;
+    value: unknown;
+}
+export declare type AdapterResponse<T = unknown> = {
+    statusCode: number;
+    data: T;
+    result: unknown;
+    maxAge?: number;
+    meta?: AdapterRequestMeta;
+};
+export declare type Middleware = ((req: AdapterRequest, reply: FastifyReply, done: HookHandlerDoneFunction) => FastifyReply | void) | ((req: AdapterRequest, reply: FastifyReply) => Promise<FastifyReply | void>);
+export declare type AdapterMiddlewareBuilder = (adapter: Adapter) => Middleware;

package/util/subscription-set/expiring-sorted-set.d.ts

@@ -0,0 +1,22 @@
+import { SubscriptionSet } from './subscription-set';
+/**
+ * An object describing an entry in the expiring sorted set.
+ * @typeParam T - the type of the entry's value
+ */
+interface ExpiringSortedSetEntry<T> {
+    value: T;
+    expirationTimestamp: number;
+}
+/**
+ * This class implements a set of unique items, each of which has an expiration timestamp.
+ * On reads, items that have expired will be deleted from the set and not returned.
+ *
+ * @typeParam T - the type of the set entries' values
+ */
+export declare class ExpiringSortedSet<T> implements SubscriptionSet<T> {
+    map: Map<string, ExpiringSortedSetEntry<T>>;
+    add(key: string, value: T, ttl: number): void;
+    get(key: string): T | undefined;
+    getAll(): T[];
+}
+export {};

package/util/subscription-set/subscription-set.d.ts

@@ -0,0 +1,18 @@
+import { PromiseOrValue } from '..';
+import { AdapterConfig } from '../../config';
+/**
+ * Set to hold items to subscribe to from a provider (regardless of protocol)
+ */
+export interface SubscriptionSet<T> {
+    /** Add a new subscription to the set */
+    add(key: string, value: T, ttl: number): PromiseOrValue<void>;
+    /** Get a specific subscription from the set */
+    get(key: string): PromiseOrValue<T | undefined>;
+    /** Get all subscriptions from the set as a list */
+    getAll(): PromiseOrValue<T[]>;
+}
+export declare class SubscriptionSetFactory {
+    private cacheType;
+    constructor(config: AdapterConfig);
+    buildSet<T>(): SubscriptionSet<T>;
+}

package/util/test-payload-loader.d.ts

@@ -0,0 +1,25 @@
+import { AdapterRequestData } from './request';
+/**
+ * The test payload read in from filesystem
+ */
+export interface Payload {
+    requests: Array<AdapterRequestData>;
+}
+/**
+ * Test payload with discriminated union so we can tell when we should just do
+ * a simple liveness check rather than a sample request
+ */
+declare type TestPayload = (Payload & {
+    isDefault: false;
+}) | {
+    isDefault: true;
+};
+/**
+ * Load in a JSON file containing a test payload for the current adapter,
+ * used in healthchecks to make sample requests
+ *
+ * @param fileName - name of file that contains the test payload data for the smoke endpoint
+ * @returns the parsed payload with individual requests
+ */
+export declare function loadTestPayload(fileName?: string): TestPayload;
+export {};

package/validation/error.d.ts

@@ -0,0 +1,50 @@
+import { HttpRequestType } from '../metrics/constants';
+declare type ErrorBasic = {
+    name: string;
+    message: string;
+};
+declare type ErrorFull = ErrorBasic & {
+    stack: string;
+    cause: string;
+};
+export declare type AdapterErrorResponse = {
+    jobRunID: string;
+    status: string;
+    statusCode: number;
+    providerStatusCode?: number;
+    error: ErrorBasic | ErrorFull;
+};
+export declare class AdapterError extends Error {
+    jobRunID: string;
+    status: string;
+    statusCode: number;
+    cause: unknown;
+    url?: string;
+    errorResponse: unknown;
+    feedID?: string;
+    providerStatusCode?: number;
+    metricsLabel?: HttpRequestType;
+    name: string;
+    message: string;
+    constructor({ jobRunID, status, statusCode, name, message, cause, url, errorResponse, feedID, providerStatusCode, metricsLabel, }: Partial<AdapterError>);
+    toJSONResponse(): AdapterErrorResponse;
+}
+export declare class AdapterInputError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export declare class AdapterRateLimitError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export declare class AdapterTimeoutError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export declare class AdapterDataProviderError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export declare class AdapterConnectionError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export declare class AdapterCustomError extends AdapterError {
+    constructor(input: Partial<AdapterError>);
+}
+export {};

package/validation/index.d.ts

@@ -0,0 +1,5 @@
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { AdapterMiddlewareBuilder } from '../util/request';
+export { InputParameters } from './input-params';
+export declare const validatorMiddleware: AdapterMiddlewareBuilder;
+export declare const errorCatchingMiddleware: (err: Error, req: FastifyRequest, res: FastifyReply) => void;

package/validation/input-params.d.ts

@@ -0,0 +1,15 @@
+export declare type Override = Map<string, Map<string, string>>;
+export declare type InputParameter = {
+    aliases?: string[];
+    description?: string;
+    type?: 'bigint' | 'boolean' | 'array' | 'number' | 'object' | 'string';
+    required?: boolean;
+    options?: unknown[];
+    default?: unknown;
+    dependsOn?: string[];
+    exclusive?: string[];
+};
+export declare type InputParameters = {
+    [name: string]: InputParameter | boolean | string[];
+};
+export declare const baseInputParameters: InputParameters;

package/validation/override-functions.d.ts

@@ -0,0 +1,3 @@
+import { Adapter } from '../adapter';
+import { AdapterRequest } from '../util/request';
+export declare const performSymbolOverrides: (adapter: Adapter, req: AdapterRequest) => void;

package/validation/validator.d.ts

@@ -0,0 +1,47 @@
+import { AdapterError, AdapterErrorResponse } from './error';
+import { InputParameters, Override } from './input-params';
+export declare type OverrideType = 'overrides' | 'tokenOverrides' | 'includes';
+declare type InputType = {
+    id?: string;
+    data?: any;
+};
+export interface ValidatorOptions {
+    shouldThrowError?: boolean;
+    includes?: any[];
+    overrides?: any;
+}
+export declare type IncludePair = {
+    from: string;
+    to: string;
+    adapters?: string[];
+    inverse?: boolean;
+    tokens?: boolean;
+};
+export declare type Includes = {
+    from: string;
+    to: string;
+    includes: IncludePair[];
+};
+export declare class Validator {
+    input: InputType;
+    inputConfigs: InputParameters;
+    inputOptions: Record<string, any[]>;
+    validatorOptions: ValidatorOptions;
+    validated: any;
+    error: AdapterError | undefined;
+    errored: AdapterErrorResponse | undefined;
+    constructor(input?: InputType, inputConfigs?: {}, inputOptions?: {}, validatorOptions?: ValidatorOptions);
+    validateInput(): void;
+    validateOverrides(path: 'overrides' | 'tokenOverrides', preset: Record<string, any>): void;
+    checkDuplicateInputParams(inputConfig: InputParameters): void;
+    validateIncludeOverrides(): void;
+    parseError(error: unknown): void;
+    formatOverride: (param: any) => Override;
+    formatIncludeOverrides: (param: any) => Override;
+    throwInvalid: (message: string) => void;
+    validateObjectParam(key: string, shouldThrowError?: boolean): void;
+    validateOptionalParam(param: any, key: string, options: any[]): void;
+    validateRequiredParam(param: any, key: string, options: any[]): void;
+    getUsedKey(key: string, keyArray: string[]): string | undefined;
+}
+export {};