@featbit/js-client-sdk 2.0.1 → 3.0.0

package/src/data-sync/PollingDataSynchronizer.ts

@@ -0,0 +1,111 @@
+import { isHttpRecoverable, PollingError } from "../errors";
+import { IDataSynchronizer } from "./IDataSynchronizer";
+import { ILogger } from "../logging/ILogger";
+import Configuration from "../Configuration";
+import { EventName, PollingErrorHandler, ProcessStreamResponse, StreamResponseEventType } from "./types";
+import Requestor from "./Requestor";
+import { httpErrorMessage } from "../utils/http";
+import { IUser } from "../options/IUser";
+
+export default class PollingDataSynchronizer implements IDataSynchronizer {
+  private stopped = false;
+
+  private logger?: ILogger;
+
+  private pollingInterval: number;
+
+  private user: IUser | undefined;
+
+  private timeoutHandle: any;
+
+  constructor(
+    config: Configuration,
+    private readonly requestor: Requestor,
+    private readonly getStoreTimestamp: () => number,
+    private readonly listeners: Map<EventName, ProcessStreamResponse>,
+    private readonly errorHandler?: PollingErrorHandler,
+  ) {
+    this.logger = config.logger;
+    this.pollingInterval = config.pollingInterval;
+    this.user = config.user;
+  }
+
+  private poll() {
+    if (this.stopped) {
+      return;
+    }
+
+    const startTime = Date.now();
+    this.logger?.debug('Polling for feature flag and segments updates');
+    this.requestor.requestData(this.getStoreTimestamp(), this.user, (err, body) => {
+      const elapsed = Date.now() - startTime;
+      const sleepFor = Math.max(this.pollingInterval - elapsed, 0);
+
+      this.logger?.debug('Elapsed: %d ms, sleeping for %d ms', elapsed, sleepFor);
+      if (err) {
+        const {status} = err;
+        if (status && !isHttpRecoverable(status)) {
+          const message = httpErrorMessage(err, 'polling request');
+          this.logger?.error(message);
+          this.errorHandler?.(new PollingError(message, status));
+          // It is not recoverable, return and do not trigger another
+          // poll.
+          return;
+        }
+        this.logger?.warn(httpErrorMessage(err, 'polling request', 'will retry'));
+      } else {
+        let featureFlags = [];
+        let userKeyId = this.user?.keyId!;
+        let processStreamResponse: ProcessStreamResponse | undefined = this.listeners.get('patch');
+
+        if (body) {
+          const message = JSON.parse(body);
+          if (message.messageType === 'data-sync') {
+            switch (message.data.eventType) {
+              case StreamResponseEventType.patch:
+                processStreamResponse = this.listeners.get('patch');
+                break;
+              case StreamResponseEventType.full:
+                processStreamResponse = this.listeners.get('put');
+                break;
+            }
+
+            ({featureFlags, userKeyId} = message.data);
+          }
+        }
+
+        const data = processStreamResponse?.deserializeData?.(featureFlags);
+        processStreamResponse?.processJson?.(userKeyId, data);
+      }
+
+      // Falling through, there was some type of error and we need to trigger
+      // a new poll.
+      this.timeoutHandle = setTimeout(() => {
+        this.poll();
+      }, sleepFor);
+    });
+  }
+
+  identify(user: IUser) {
+    this.user = {...user};
+  }
+
+  close(): void {
+    this.stop();
+  }
+
+  start(): void {
+    this.poll();
+  }
+
+  stop(): void {
+    if (this.timeoutHandle) {
+      clearTimeout(this.timeoutHandle);
+      this.timeoutHandle = undefined;
+    }
+    this.stopped = true;
+  }
+}
+
+
+

package/src/data-sync/Requestor.ts

@@ -0,0 +1,61 @@
+import { IRequestor } from "./IRequestor";
+import Configuration from "../Configuration";
+import { IInfo } from "../platform/IInfo";
+import { IRequestOptions, IRequests, IResponse } from "../platform/requests";
+import { StreamingError } from "../errors";
+import { defaultHeaders } from "../utils/http";
+
+/**
+ * @internal
+ */
+export default class Requestor implements IRequestor {
+  private readonly headers: Record<string, string>;
+
+  private readonly uri: string;
+
+  constructor(
+    sdkKey: string,
+    config: Configuration,
+    info: IInfo,
+    private readonly requests: IRequests,
+  ) {
+    this.headers = defaultHeaders(sdkKey, info);
+    this.uri = config.pollingUri;
+  }
+
+  /**
+   * Perform a request and utilize the ETag cache. The ETags are cached in the
+   * requestor instance.
+   */
+  private async request(
+    requestUrl: string,
+    options: IRequestOptions,
+  ): Promise<{
+    res: IResponse;
+    body: string;
+  }> {
+    const res = await this.requests.fetch(requestUrl, options);
+
+    const body = await res.text();
+
+    return {res, body};
+  }
+
+  async requestData(timestamp: number, payload: any, cb: (err: any, body: any) => void) {
+    const options: IRequestOptions = {
+      method: 'POST',
+      headers: this.headers,
+      body: JSON.stringify(payload)
+    };
+    try {
+      const {res, body} = await this.request(`${ this.uri }?timestamp=${ timestamp ?? 0 }`, options);
+      if (res.status !== 200 && res.status !== 304) {
+        const err = new StreamingError(`Unexpected status code: ${ res.status }`, res.status);
+        return cb(err, undefined);
+      }
+      return cb(undefined, res.status === 304 ? null : body);
+    } catch (err) {
+      return cb(err, undefined);
+    }
+  }
+}

package/src/data-sync/WebSocketDataSynchronizer.ts

@@ -0,0 +1,74 @@
+import { IDataSynchronizer } from "./IDataSynchronizer";
+import ClientContext from "../options/ClientContext";
+import { EventName, ProcessStreamResponse } from "./types";
+import { ILogger } from "../logging/ILogger";
+import { IWebSocketWithEvents } from "../platform/IWebSocket";
+import { IUser } from "../options/IUser";
+
+class WebSocketDataSynchronizer implements IDataSynchronizer {
+  private socket?: IWebSocketWithEvents;
+  private readonly logger?: ILogger;
+
+  private connectionAttemptStartTime?: number;
+
+  constructor(
+    sdkKey: string,
+    user: IUser,
+    clientContext: ClientContext,
+    socket: IWebSocketWithEvents,
+    private readonly getStoreTimestamp: () => number,
+    private readonly listeners: Map<EventName, ProcessStreamResponse>,
+    webSocketPingInterval: number
+  ) {
+    const {logger, streamingUri} = clientContext;
+
+    this.logger = logger;
+    this.socket = socket;
+    this.socket.config({
+      sdkKey,
+      streamingUri,
+      pingInterval: webSocketPingInterval,
+      user,
+      logger,
+      getStoreTimestamp
+    });
+
+    this.listeners.forEach(({deserializeData, processJson}, eventName) => {
+      this.socket?.addListener(eventName, (event) => {
+        this.logger?.debug(`Received ${ eventName } event`);
+
+        if (event?.data) {
+          const {featureFlags, userKeyId} = event.data;
+          const data = deserializeData(featureFlags);
+          processJson(userKeyId, data);
+        }
+      });
+    })
+  }
+
+  identify(user: IUser): void {
+    this.socket?.identify(user);
+  }
+
+  start(): void {
+    this.logConnectionStarted();
+
+    this.socket?.connect();
+  }
+
+  private logConnectionStarted() {
+    this.connectionAttemptStartTime = Date.now();
+    this.logger?.info(`Stream connection attempt StartTime ${ this.connectionAttemptStartTime }`);
+  }
+
+  close(): void {
+    this.stop();
+  }
+
+  stop(): void {
+    this.socket?.close();
+    this.socket = undefined;
+  }
+}
+
+export default WebSocketDataSynchronizer;

package/src/data-sync/index.ts

@@ -0,0 +1,9 @@
+export * from './DataSyncMode';
+export * from './IDataSynchronizer';
+export * from './IRequestor';
+export * from './NullDataSynchronizer';
+export * from './PollingDataSynchronizer';
+export * from './Requestor';
+export * from './types';
+export * from './utils';
+export * from './WebSocketDataSynchronizer';

package/src/data-sync/types.ts

@@ -0,0 +1,20 @@
+import { PollingError } from "../errors";
+import { IFlag } from "../evaluation/data/IFlag";
+
+export type PollingErrorHandler = (err: PollingError) => void;
+
+export enum StreamResponseEventType {
+  full = 'full',
+  patch = 'patch'
+}
+
+export interface IStreamResponse {
+  eventType: StreamResponseEventType,
+  featureFlags: IFlag[]
+}
+
+export type EventName = 'delete' | 'patch' | 'ping' | 'put';
+export type ProcessStreamResponse = {
+  deserializeData: (flags: IFlag[]) => any;
+  processJson: (userKeyId: string, json: any) => void;
+};

package/src/data-sync/utils.ts

@@ -0,0 +1,32 @@
+/********************** encode text begin *****************************/
+const alphabet: Record<string, string> = {
+  "0": "Q",
+  "1": "B",
+  "2": "W",
+  "3": "S",
+  "4": "P",
+  "5": "H",
+  "6": "D",
+  "7": "X",
+  "8": "Z",
+  "9": "U",
+}
+
+function encodeNumber(param: number, length: number): string {
+  var s = "000000000000" + param;
+  const numberWithLeadingZeros = s.slice(s.length - length);
+  return numberWithLeadingZeros.split('').map(n => alphabet[n]).join('');
+}
+
+// generate connection token
+export function generateConnectionToken(text: string): string {
+  text = text.replace(/=*$/, '');
+  const timestamp = Date.now();
+  const timestampCode = encodeNumber(timestamp, timestamp.toString().length);
+  // get random number less than the length of the text as the start point, and it must be greater or equal to 2
+  const start = Math.max(Math.floor(Math.random() * text.length), 2);
+
+  return `${ encodeNumber(start, 3) }${ encodeNumber(timestampCode.length, 2) }${ text.slice(0, start) }${ timestampCode }${ text.slice(start) }`;
+}
+
+/********************** encode text end *****************************/

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class PollingError extends Error {
+  public readonly status?: number;
+
+  constructor(message: string, status?: number) {
+    super(message);
+    this.status = status;
+    this.name = 'FbPollingError';
+  }
+}
+
+export class StreamingError extends Error {
+  public readonly code?: number;
+
+  constructor(message: string, code?: number) {
+    super(message);
+    this.code = code;
+    this.name = 'FbStreamingError';
+  }
+}
+
+export class UnexpectedResponseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FbUnexpectedResponseError';
+  }
+}
+
+
+export class ClientError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FbClientError';
+  }
+}
+
+export function isHttpRecoverable(status: number) {
+  if (status >= 400 && status < 500) {
+    return status === 400 || status === 408 || status === 429;
+  }
+  return true;
+}

package/src/evaluation/EvalResult.ts

@@ -0,0 +1,36 @@
+import { ReasonKinds } from "./ReasonKinds";
+import { IFlag } from "./data/IFlag";
+import { EvalEvent } from "../events/event";
+import { IUser } from "../options/IUser";
+
+/**
+ * A class which encapsulates the result of an evaluation. It allows for differentiating between
+ * successful and error result types.
+ *
+ * @internal
+ */
+export default class EvalResult {
+  protected constructor(
+    public kind: ReasonKinds,
+    public value: IFlag | null,
+    public reason?: string,
+  ) {
+  }
+
+  static flagNotFound(flagKey: string) {
+    return new EvalResult(ReasonKinds.FlagNotFound, null, `flag not found: ${ flagKey }`);
+  }
+
+  static matched(val: IFlag) {
+    return new EvalResult(ReasonKinds.Match, val, 'target match');
+  }
+
+  toEvalEvent(user: IUser): EvalEvent | null {
+    if (this.kind !== ReasonKinds.Match) {
+      return null;
+    }
+
+    const targetedVariation = this.value?.variations.find(v => v.value === this.value?.variation);
+    return new EvalEvent(user, this.value?.id!, targetedVariation!, this.value?.sendToExperiment!);
+  }
+}

package/src/evaluation/Evaluator.ts

@@ -0,0 +1,27 @@
+import { IFlag } from "./data/IFlag";
+import EvalResult from "./EvalResult";
+import { IStore } from "../platform/IStore";
+import DataKinds from "../store/DataKinds";
+
+/**
+ * @internal
+ */
+export default class Evaluator {
+  constructor(private store: IStore) {
+  }
+
+  /**
+   * Evaluate the given flag against the given context.
+   * @param flagKey The key of the feature flag.
+   */
+  evaluate(
+    flagKey: string,
+  ): EvalResult {
+    const flag = this.store.get(DataKinds.Flags, flagKey) as unknown as IFlag;
+    if (!flag) {
+      return EvalResult.flagNotFound(flagKey);
+    }
+
+    return EvalResult.matched(flag);
+  }
+}

package/src/evaluation/IEvalDetail.ts

@@ -0,0 +1,24 @@
+import { ReasonKinds } from "./ReasonKinds";
+
+export interface IEvalDetail<TValue> {
+  /**
+   * The unique key of the feature flag.
+   */
+  flagKey: string;
+
+  /**
+   * An enum indicating the category of the reason. See {@link ReasonKinds}
+   */
+  kind: ReasonKinds;
+
+  /**
+   * The result of the flag evaluation. This will be either one of the flag's variations or
+   * the default value that was passed to `FbClient.variationDetail`.
+   */
+  value?: TValue;
+
+  /**
+   * A string describing the main factor that influenced the flag evaluation value.
+   */
+  reason?: string;
+}

package/src/evaluation/ReasonKinds.ts

@@ -0,0 +1,10 @@
+/**
+ * Different kinds of error which may be encountered during evaluation.
+ */
+export enum ReasonKinds {
+  ClientNotReady = 'ClientNotReady',
+  Match = 'Match',
+  WrongType = 'WrongType',
+  FlagNotFound = 'FlagNotFound',
+  Error = 'Error'
+}

package/src/evaluation/data/IFlag.ts

@@ -0,0 +1,29 @@
+export type FlagValue = any;
+
+export enum VariationDataType {
+  string = 'string',
+  boolean = 'boolean',
+  number = 'number',
+  json = 'json',
+  empty = ''
+}
+
+export interface IVariation {
+  id: number,
+  value: FlagValue
+}
+
+export interface IFlagBase {
+  id: string, // the key
+  variation: FlagValue,
+  variationType: VariationDataType,
+  sendToExperiment?: boolean,
+  timestamp?: number,
+  variationOptions?: IVariation[],
+}
+
+export interface IFlag extends IFlagBase {
+  key: string, // the same value to id
+  variations: IVariation[],// the same value to variationOptions
+  version: number
+}

package/src/evaluation/data/index.ts

@@ -0,0 +1 @@
+export * from './IFlag';

package/src/evaluation/index.ts

@@ -0,0 +1,5 @@
+export * from './data';
+export * from './EvalResult';
+export * from './Evaluator';
+export * from './IEvalDetail';
+export * from './ReasonKinds';

package/src/events/DefaultEventProcessor.ts

@@ -0,0 +1,84 @@
+import { IEventProcessor } from "./IEventProcessor";
+import { EventDispatcher } from "./EventDispatcher";
+import ClientContext from "../options/ClientContext";
+import { FlushEvent, IEvent, ShutdownEvent } from "./event";
+import { isNullOrUndefined } from "../utils/isNullOrUndefined";
+import { IEventQueue } from "./IEventQueue";
+import { DefaultEventQueue } from "./DefaultEventQueue";
+import { ILogger } from "../logging/ILogger";
+
+export class DefaultEventProcessor implements IEventProcessor {
+  private readonly logger: ILogger;
+  private readonly flushInterval: number;
+  private readonly eventDispatcher: EventDispatcher;
+  private readonly eventQueue: IEventQueue;
+  private closed: boolean = false;
+
+  constructor(clientContext: ClientContext) {
+    const {logger, flushInterval, maxEventsInQueue} = clientContext;
+    this.logger = logger!;
+    this.flushInterval = flushInterval;
+    this.eventQueue = new DefaultEventQueue(maxEventsInQueue, this.logger);
+    this.eventDispatcher = new EventDispatcher(clientContext, this.eventQueue);
+
+    this.flushLoop();
+  }
+
+  private flushLoop() {
+    if (this.closed) {
+      return;
+    }
+
+    setTimeout(async () => {
+      try {
+        await this.flush();
+      } catch (err) {
+        this.logger.error('Unexpected error while flushing events in event processor.', err);
+      }
+
+      this.flushLoop();
+    }, this.flushInterval);
+  }
+
+  flush(): Promise<any> {
+    const flushEvent = new FlushEvent();
+    this.record(flushEvent);
+    return flushEvent.waitForCompletion();
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+
+    // send a shutdown event to dispatcher
+    const shutdown = new ShutdownEvent();
+    this.record(shutdown);
+
+    try {
+      await shutdown.waitForCompletion();
+    } catch (err) {
+      this.logger.error('Event processor shutdown but not complete.');
+    }
+
+    // mark the event queue as complete for adding
+    this.eventQueue.close();
+    this.closed = true;
+  }
+
+  record(event: IEvent | null): boolean {
+    if (isNullOrUndefined(event)) {
+      return false;
+    }
+
+    if (!this.eventQueue.addEvent(event!)) {
+      if (event instanceof FlushEvent) {
+        event.complete();
+      }
+
+      return false;
+    }
+
+    return true;
+  }
+}

package/src/events/DefaultEventQueue.ts

@@ -0,0 +1,50 @@
+import { IEventQueue } from "./IEventQueue";
+import { IEvent } from "./event";
+import { ILogger } from "../logging/ILogger";
+
+export class DefaultEventQueue implements IEventQueue {
+  private events: IEvent[];
+  private closed: boolean = false;
+
+  constructor(private readonly capacity: number, private readonly logger: ILogger) {
+    this.events = [];
+  }
+
+  addEvent(event: IEvent): boolean {
+    if (this.closed) {
+      return false;
+    }
+
+    if (this.events.length >= this.capacity) {
+      this.logger.warn("Events are being produced faster than they can be processed. We shouldn't see this.");
+      return false;
+    }
+
+    this.events.push(event);
+    return true;
+  }
+
+  clear(): void {
+    this.events = [];
+  }
+
+  shift(): IEvent | undefined {
+    return this.events.shift();
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  get eventsSnapshot(): IEvent[] {
+    return [...this.events];
+  }
+
+  get length(): number {
+    return this.events.length;
+  }
+
+  get isEmpty(): boolean {
+    return this.length === 0;
+  }
+}