contexts.ts

/*
 * Copyright (c) 2021 Snowplow Analytics Ltd, 2010 Anthon Pang
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived from
 *    this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

import { PayloadBuilder, Payload, isNonEmptyJson } from './payload';
import { SelfDescribingJson } from './core';
import { CorePlugin } from './plugins';
import { LOG } from './logger';

/**
 * Argument for {@link ContextGenerator} and {@link ContextFilter} callback
 */
export interface ContextEvent {
  /** The event payload */
  event: Payload;
  /** The event type
   * @example 'page_view'
   */
  eventType: string;
  /** The event schema where one is available, or empty string
   * @example 'iglu:com.snowplowanalytics.snowplow/ad_impression/jsonschema/1-0-0'
   */
  eventSchema: string;
}

/**
 * A context generator is a user-supplied callback that is evaluated for each event
 * to allow an additional context to be dynamically attached to the event
 * @param args - - Object which contains the event information to help decide what should be included in the returned Context
 */
export type ContextGenerator = (args?: ContextEvent) => SelfDescribingJson;

/**
 * A context filter is a user-supplied callback that is evaluated for each event
 * to determine if the context associated with the filter should be attached to the event
 * @param args - - Object that contains: event, eventType, eventSchema
 */
export type ContextFilter = (args?: ContextEvent) => boolean;

/**
 * A context primitive is either a self-describing JSON or a context generator
 */
export type ContextPrimitive = SelfDescribingJson | ContextGenerator;

/**
 * A filter provider is a tuple that has two parts: a context filter and the context primitive(s)
 * If the context filter evaluates to true, the tracker will attach the context primitive(s)
 */
export type FilterProvider = [ContextFilter, Array<ContextPrimitive> | ContextPrimitive];

/**
 * A ruleset has accept or reject properties that contain rules for matching Iglu schema URIs
 */
export interface RuleSet {
  accept?: Array<string> | string;
  reject?: Array<string> | string;
}

/**
 * A ruleset provider is aa tuple that has two parts: a ruleset and the context primitive(s)
 * If the ruleset allows the current event schema URI, the tracker will attach the context primitive(s)
 */
export type RuleSetProvider = [RuleSet, Array<ContextPrimitive> | ContextPrimitive];

/**
 * Conditional context providers are two element arrays used to decide when to attach contexts, where:
 * - the first element is some conditional criterion
 * - the second element is any number of context primitives
 */
export type ConditionalContextProvider = FilterProvider | RuleSetProvider;

/**
 * A Dynamic context is an array of Self Describing JSON contexts, or an array of callbacks which return Self Describing JSON contexts
 * The array can be a mix of both contexts and callbacks which generate contexts
 */
export type DynamicContext = Array<SelfDescribingJson | ((...params: any[]) => SelfDescribingJson | null)>;

export interface GlobalContexts {
  /**
   * Returns all Context Primitives
   */
  getGlobalPrimitives(): Array<ContextPrimitive>;

  /**
   * Returns all Conditional Contexts
   */
  getConditionalProviders(): Array<ConditionalContextProvider>;

  /**
   * Adds conditional or primitive global contexts
   * @param contexts - An Array of either Conditional Contexts or Primitive Contexts
   */
  addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;

  /**
   * Removes all global contexts
   */
  clearGlobalContexts(): void;

  /**
   * Removes previously added global context, performs a deep comparison of the contexts or conditional contexts
   * @param contexts - An Array of either Condition Contexts or Primitive Contexts
   */
  removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;

  /**
   * Returns all applicable global contexts for a specified event
   * @param event - The event to check for applicable global contexts for
   */
  getApplicableContexts(event: PayloadBuilder): Array<SelfDescribingJson>;
}

/**
 * Contains helper functions to aid in the addition and removal of Global Contexts
 */
export function globalContexts(): GlobalContexts {
  let globalPrimitives: Array<ContextPrimitive> = [];
  let conditionalProviders: Array<ConditionalContextProvider> = [];

  /**
   * Returns all applicable global contexts for a specified event
   * @param event - The event to check for applicable global contexts for
   * @returns An array of contexts
   */
  const assembleAllContexts = (event: PayloadBuilder): Array<SelfDescribingJson> => {
    const eventSchema = getUsefulSchema(event);
    const eventType = getEventType(event);
    const contexts: Array<SelfDescribingJson> = [];
    const generatedPrimitives = generatePrimitives(globalPrimitives, event, eventType, eventSchema);
    contexts.push(...generatedPrimitives);

    const generatedConditionals = generateConditionals(conditionalProviders, event, eventType, eventSchema);
    contexts.push(...generatedConditionals);

    return contexts;
  };

  return {
    getGlobalPrimitives(): Array<ContextPrimitive> {
      return globalPrimitives;
    },

    getConditionalProviders(): Array<ConditionalContextProvider> {
      return conditionalProviders;
    },

    addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void {
      const acceptedConditionalContexts: ConditionalContextProvider[] = [];
      const acceptedContextPrimitives: ContextPrimitive[] = [];
      for (const context of contexts) {
        if (isConditionalContextProvider(context)) {
          acceptedConditionalContexts.push(context);
        } else if (isContextPrimitive(context)) {
          acceptedContextPrimitives.push(context);
        }
      }
      globalPrimitives = globalPrimitives.concat(acceptedContextPrimitives);
      conditionalProviders = conditionalProviders.concat(acceptedConditionalContexts);
    },

    clearGlobalContexts(): void {
      conditionalProviders = [];
      globalPrimitives = [];
    },

    removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void {
      for (const context of contexts) {
        if (isConditionalContextProvider(context)) {
          conditionalProviders = conditionalProviders.filter(
            (item) => JSON.stringify(item) === JSON.stringify(context)
          );
        } else if (isContextPrimitive(context)) {
          globalPrimitives = globalPrimitives.filter((item) => JSON.stringify(item) === JSON.stringify(context));
        }
      }
    },

    getApplicableContexts(event: PayloadBuilder): Array<SelfDescribingJson> {
      return assembleAllContexts(event);
    },
  };
}

export interface PluginContexts {
  /**
   * Returns list of contexts from all active plugins
   */
  addPluginContexts: (additionalContexts?: SelfDescribingJson[] | null) => SelfDescribingJson[];
}

export function pluginContexts(plugins: Array<CorePlugin>): PluginContexts {
  /**
   * Add common contexts to every event
   *
   * @param array - additionalContexts List of user-defined contexts
   * @return userContexts combined with commonContexts
   */
  return {
    addPluginContexts: (additionalContexts?: SelfDescribingJson[] | null): SelfDescribingJson[] => {
      const combinedContexts: SelfDescribingJson[] = additionalContexts ?? [];

      plugins.forEach((plugin) => {
        try {
          if (plugin.contexts) {
            combinedContexts.push(...plugin.contexts());
          }
        } catch (ex) {
          LOG.error('Error adding plugin contexts', ex);
        }
      });

      return combinedContexts;
    },
  };
}

/**
 * Find dynamic context generating functions and return their results to be merged into the static contexts
 * Combine an array of unchanging contexts with the result of a context-creating function
 *
 * @param dynamicOrStaticContexts - Array of custom context Objects or custom context generating functions
 * @param Parameters - to pass to dynamic context callbacks
 * @returns An array of Self Describing JSON context
 */
export function resolveDynamicContext(
  dynamicOrStaticContexts?: DynamicContext | null,
  ...extraParams: any[]
): Array<SelfDescribingJson> {
  return (
    (dynamicOrStaticContexts
      ?.map(function (context) {
        if (typeof context === 'function') {
          try {
            return context(...extraParams);
          } catch (e) {
            //TODO: provide warning
            return undefined;
          }
        } else {
          return context;
        }
      })
      .filter(Boolean) as Array<SelfDescribingJson>) ?? []
  );
}

/**
 * Slices a schema into its composite parts. Useful for ruleset filtering.
 * @param input - A schema string
 * @returns The vendor, schema name, major, minor and patch information of a schema string
 */
export function getSchemaParts(input: string): Array<string> | undefined {
  const re = new RegExp(
    '^iglu:([a-zA-Z0-9-_.]+)/([a-zA-Z0-9-_]+)/jsonschema/([1-9][0-9]*)-(0|[1-9][0-9]*)-(0|[1-9][0-9]*)$'
  );
  const matches = re.exec(input);
  if (matches !== null) return matches.slice(1, 6);
  return undefined;
}

/**
 * Validates the vendor section of a schema string contains allowed wildcard values
 * @param parts - Array of parts from a schema string
 * @returns Whether the vendor validation parts are a valid combination
 */
export function validateVendorParts(parts: Array<string>): boolean {
  if (parts[0] === '*' || parts[1] === '*') {
    return false; // no wildcard in first or second part
  }
  if (parts.slice(2).length > 0) {
    let asterisk = false;
    for (const part of parts.slice(2)) {
      if (part === '*')
        // mark when we've found a wildcard
        asterisk = true;
      else if (asterisk)
        // invalid if alpha parts come after wildcard
        return false;
    }
    return true;
  } else if (parts.length == 2) return true;

  return false;
}

/**
 * Validates the vendor part of a schema string is valid for a rule set
 * @param input - Vendor part of a schema string
 * @returns Whether the vendor validation string is valid
 */
export function validateVendor(input: string): boolean {
  const parts = input.split('.');
  if (parts && parts.length > 1) return validateVendorParts(parts);
  return false;
}

/**
 * Checks for validity of input and returns all the sections of a schema string that are used to match rules in a ruleset
 * @param input - A Schema string
 * @returns The sections of a schema string that are used to match rules in a ruleset
 */
export function getRuleParts(input: string): Array<string> | undefined {
  const re = new RegExp(
    '^iglu:((?:(?:[a-zA-Z0-9-_]+|\\*).)+(?:[a-zA-Z0-9-_]+|\\*))/([a-zA-Z0-9-_.]+|\\*)/jsonschema/([1-9][0-9]*|\\*)-(0|[1-9][0-9]*|\\*)-(0|[1-9][0-9]*|\\*)$'
  );
  const matches = re.exec(input);
  if (matches !== null && validateVendor(matches[1])) return matches.slice(1, 6);
  return undefined;
}

/**
 * Ensures the rules specified in a schema string of a ruleset are valid
 * @param input - A Schema string
 * @returns if there rule is valid
 */
export function isValidRule(input: string): boolean {
  const ruleParts = getRuleParts(input);
  if (ruleParts) {
    const vendor = ruleParts[0];
    return ruleParts.length === 5 && validateVendor(vendor);
  }
  return false;
}

/**
 * Check if a variable is an Array containing only strings
 * @param input - The variable to validate
 * @returns True if the input is an array containing only strings
 */
export function isStringArray(input: unknown): input is Array<string> {
  return (
    Array.isArray(input) &&
    input.every((x) => {
      return typeof x === 'string';
    })
  );
}

/**
 * Validates whether a rule set is an array of valid ruleset strings
 * @param input - The Array of rule set arguments
 * @returns True is the input is an array of valid rules
 */
export function isValidRuleSetArg(input: unknown): boolean {
  if (isStringArray(input))
    return input.every((x: string) => {
      return isValidRule(x);
    });
  else if (typeof input === 'string') return isValidRule(input);
  return false;
}

/**
 * Check if a variable is a valid, non-empty Self Describing JSON
 * @param input - The variable to validate
 * @returns True if a valid Self Describing JSON
 */
export function isSelfDescribingJson(input: unknown): input is SelfDescribingJson {
  const sdj = input as SelfDescribingJson;
  if (isNonEmptyJson(sdj))
    if ('schema' in sdj && 'data' in sdj) return typeof sdj.schema === 'string' && typeof sdj.data === 'object';
  return false;
}

/**
 * Validates if the input object contains the expected properties of a ruleset
 * @param input - The object containing a rule set
 * @returns True if a valid rule set
 */
export function isRuleSet(input: unknown): input is Record<string, unknown> {
  const ruleSet = input as Record<string, unknown>;
  let ruleCount = 0;
  if (input != null && typeof input === 'object' && !Array.isArray(input)) {
    if (Object.prototype.hasOwnProperty.call(ruleSet, 'accept')) {
      if (isValidRuleSetArg(ruleSet['accept'])) {
        ruleCount += 1;
      } else {
        return false;
      }
    }
    if (Object.prototype.hasOwnProperty.call(ruleSet, 'reject')) {
      if (isValidRuleSetArg(ruleSet['reject'])) {
        ruleCount += 1;
      } else {
        return false;
      }
    }
    // if either 'reject' or 'accept' or both exists,
    // we have a valid ruleset
    return ruleCount > 0 && ruleCount <= 2;
  }
  return false;
}

/**
 * Validates if the function can be a valid context generator function
 * @param input - The function to be validated
 */
export function isContextCallbackFunction(input: unknown): boolean {
  return typeof input === 'function' && input.length <= 1;
}

/**
 * Validates if the function can be a valid context primitive function or self describing json
 * @param input - The function or orbject to be validated
 * @returns True if either a Context Generator or Self Describing JSON
 */
export function isContextPrimitive(input: unknown): input is ContextPrimitive {
  return isContextCallbackFunction(input) || isSelfDescribingJson(input);
}

/**
 * Validates if an array is a valid shape to be a Filter Provider
 * @param input - The Array of Context filter callbacks
 */
export function isFilterProvider(input: unknown): boolean {
  if (Array.isArray(input)) {
    if (input.length === 2) {
      if (Array.isArray(input[1])) {
        return isContextCallbackFunction(input[0]) && input[1].every(isContextPrimitive);
      }
      return isContextCallbackFunction(input[0]) && isContextPrimitive(input[1]);
    }
  }
  return false;
}

/**
 * Validates if an array is a valid shape to be an array of rule sets
 * @param input - The Array of Rule Sets
 */
export function isRuleSetProvider(input: unknown): boolean {
  if (Array.isArray(input) && input.length === 2) {
    if (!isRuleSet(input[0])) return false;
    if (Array.isArray(input[1])) return input[1].every(isContextPrimitive);
    return isContextPrimitive(input[1]);
  }
  return false;
}

/**
 * Checks if an input array is either a filter provider or a rule set provider
 * @param input - An array of filter providers or rule set providers
 * @returns Whether the array is a valid {@link ConditionalContextProvider}
 */
export function isConditionalContextProvider(input: unknown): input is ConditionalContextProvider {
  return isFilterProvider(input) || isRuleSetProvider(input);
}

/**
 * Checks if a given schema matches any rules within the provided rule set
 * @param ruleSet - The rule set containing rules to match schema against
 * @param schema - The schema to be matched against the rule set
 */
export function matchSchemaAgainstRuleSet(ruleSet: RuleSet, schema: string): boolean {
  let rejectCount = 0;
  let acceptCount = 0;
  const acceptRules = ruleSet['accept'];
  if (Array.isArray(acceptRules)) {
    if ((ruleSet.accept as Array<string>).some((rule) => matchSchemaAgainstRule(rule, schema))) {
      acceptCount++;
    }
  } else if (typeof acceptRules === 'string') {
    if (matchSchemaAgainstRule(acceptRules, schema)) {
      acceptCount++;
    }
  }

  const rejectRules = ruleSet['reject'];
  if (Array.isArray(rejectRules)) {
    if ((ruleSet.reject as Array<string>).some((rule) => matchSchemaAgainstRule(rule, schema))) {
      rejectCount++;
    }
  } else if (typeof rejectRules === 'string') {
    if (matchSchemaAgainstRule(rejectRules, schema)) {
      rejectCount++;
    }
  }

  if (acceptCount > 0 && rejectCount === 0) {
    return true;
  } else if (acceptCount === 0 && rejectCount > 0) {
    return false;
  }

  return false;
}

/**
 * Checks if a given schema matches a specific rule from a rule set
 * @param rule - The rule to match schema against
 * @param schema - The schema to be matched against the rule
 */
export function matchSchemaAgainstRule(rule: string, schema: string): boolean {
  if (!isValidRule(rule)) return false;
  const ruleParts = getRuleParts(rule);
  const schemaParts = getSchemaParts(schema);
  if (ruleParts && schemaParts) {
    if (!matchVendor(ruleParts[0], schemaParts[0])) return false;
    for (let i = 1; i < 5; i++) {
      if (!matchPart(ruleParts[i], schemaParts[i])) return false;
    }
    return true; // if it hasn't failed, it passes
  }
  return false;
}

function matchVendor(rule: string, vendor: string): boolean {
  // rule and vendor must have same number of elements
  const vendorParts = vendor.split('.');
  const ruleParts = rule.split('.');
  if (vendorParts && ruleParts) {
    if (vendorParts.length !== ruleParts.length) return false;
    for (let i = 0; i < ruleParts.length; i++) {
      if (!matchPart(vendorParts[i], ruleParts[i])) return false;
    }
    return true;
  }
  return false;
}

function matchPart(rule: string, schema: string): boolean {
  // parts should be the string nested between slashes in the URI: /example/
  return (rule && schema && rule === '*') || rule === schema;
}

// Returns the "useful" schema, i.e. what would someone want to use to identify events.
// For some events this is the 'e' property but for unstructured events, this is the
// 'schema' from the 'ue_px' field.
function getUsefulSchema(sb: PayloadBuilder): string {
  let eventJson = sb.getJson();
  for (const json of eventJson) {
    if (json.keyIfEncoded === 'ue_px' && typeof json.json['data'] === 'object') {
      const schema = (json.json['data'] as Record<string, unknown>)['schema'];
      if (typeof schema == 'string') {
        return schema;
      }
    }
  }
  return '';
}

function getEventType(payloadBuilder: PayloadBuilder): string {
  const eventType = payloadBuilder.getPayload()['e'];
  return typeof eventType === 'string' ? eventType : '';
}

function buildGenerator(
  generator: ContextGenerator,
  event: PayloadBuilder,
  eventType: string,
  eventSchema: string
): SelfDescribingJson | Array<SelfDescribingJson> | undefined {
  let contextGeneratorResult: SelfDescribingJson | Array<SelfDescribingJson> | undefined = undefined;
  try {
    // try to evaluate context generator
    const args = {
      event: event.getPayload(),
      eventType: eventType,
      eventSchema: eventSchema,
    };
    contextGeneratorResult = generator(args);
    // determine if the produced result is a valid SDJ
    if (Array.isArray(contextGeneratorResult) && contextGeneratorResult.every(isSelfDescribingJson)) {
      return contextGeneratorResult;
    } else if (isSelfDescribingJson(contextGeneratorResult)) {
      return contextGeneratorResult;
    } else {
      return undefined;
    }
  } catch (error) {
    contextGeneratorResult = undefined;
  }
  return contextGeneratorResult;
}

function normalizeToArray<T>(input: Array<T> | T): Array<T> {
  if (Array.isArray(input)) {
    return input;
  }
  return Array.of(input);
}

function generatePrimitives(
  contextPrimitives: Array<ContextPrimitive> | ContextPrimitive,
  event: PayloadBuilder,
  eventType: string,
  eventSchema: string
): Array<SelfDescribingJson> {
  const normalizedInputs: Array<ContextPrimitive> = normalizeToArray(contextPrimitives);
  const partialEvaluate = (primitive: ContextPrimitive) => {
    const result = evaluatePrimitive(primitive, event, eventType, eventSchema);
    if (result && result.length !== 0) {
      return result;
    }
    return undefined;
  };
  const generatedContexts = normalizedInputs.map(partialEvaluate);
  return ([] as Array<SelfDescribingJson>).concat(
    ...(generatedContexts.filter((c) => c != null && c.filter(Boolean)) as Array<Array<SelfDescribingJson>>)
  );
}

function evaluatePrimitive(
  contextPrimitive: ContextPrimitive,
  event: PayloadBuilder,
  eventType: string,
  eventSchema: string
): Array<SelfDescribingJson> | undefined {
  if (isSelfDescribingJson(contextPrimitive)) {
    return [contextPrimitive as SelfDescribingJson];
  } else if (isContextCallbackFunction(contextPrimitive)) {
    const generatorOutput = buildGenerator(contextPrimitive as ContextGenerator, event, eventType, eventSchema);
    if (isSelfDescribingJson(generatorOutput)) {
      return [generatorOutput as SelfDescribingJson];
    } else if (Array.isArray(generatorOutput)) {
      return generatorOutput;
    }
  }
  return undefined;
}

function evaluateProvider(
  provider: ConditionalContextProvider,
  event: PayloadBuilder,
  eventType: string,
  eventSchema: string
): Array<SelfDescribingJson> {
  if (isFilterProvider(provider)) {
    const filter: ContextFilter = (provider as FilterProvider)[0];
    let filterResult = false;
    try {
      const args = {
        event: event.getPayload(),
        eventType: eventType,
        eventSchema: eventSchema,
      };
      filterResult = filter(args);
    } catch (error) {
      filterResult = false;
    }
    if (filterResult === true) {
      return generatePrimitives((provider as FilterProvider)[1], event, eventType, eventSchema);
    }
  } else if (isRuleSetProvider(provider)) {
    if (matchSchemaAgainstRuleSet((provider as RuleSetProvider)[0], eventSchema)) {
      return generatePrimitives((provider as RuleSetProvider)[1], event, eventType, eventSchema);
    }
  }
  return [];
}

function generateConditionals(
  providers: Array<ConditionalContextProvider> | ConditionalContextProvider,
  event: PayloadBuilder,
  eventType: string,
  eventSchema: string
): Array<SelfDescribingJson> {
  const normalizedInput: Array<ConditionalContextProvider> = normalizeToArray(providers);
  const partialEvaluate = (provider: ConditionalContextProvider) => {
    const result = evaluateProvider(provider, event, eventType, eventSchema);
    if (result && result.length !== 0) {
      return result;
    }
    return undefined;
  };
  const generatedContexts = normalizedInput.map(partialEvaluate);
  return ([] as Array<SelfDescribingJson>).concat(
    ...(generatedContexts.filter((c) => c != null && c.filter(Boolean)) as Array<Array<SelfDescribingJson>>)
  );
}