cmab_service.ts

/**
 * Copyright 2025, Optimizely
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { LoggerFacade } from "../../../logging/logger";
import { IOptimizelyUserContext } from "../../../optimizely_user_context";
import { ProjectConfig } from "../../../project_config/project_config"
import { OptimizelyDecideOption, UserAttributes } from "../../../shared_types"
import { CacheWithRemove } from "../../../utils/cache/cache";
import { CmabClient } from "./cmab_client";
import { v4 as uuidV4 } from 'uuid';
import murmurhash from "murmurhash";
import { DecideOptionsMap } from "..";
import { SerialRunner } from "../../../utils/executor/serial_runner";
import {
  CMAB_CACHE_ATTRIBUTES_MISMATCH,
  CMAB_CACHE_HIT,
  CMAB_CACHE_MISS,
  IGNORE_CMAB_CACHE,
  INVALIDATE_CMAB_CACHE,
  RESET_CMAB_CACHE,
} from 'log_message';

export type CmabDecision = {
  variationId: string,
  cmabUuid: string,
}
 
export interface CmabService {
  /**
  * Get variation id for the user
  * @param  {IOptimizelyUserContext}          userContext
  * @param  {string}                         ruleId 
  * @param  {OptimizelyDecideOption[]}       options
  * @return {Promise<CmabDecision>}          
  */
  getDecision(
    projectConfig: ProjectConfig,
    userContext: IOptimizelyUserContext,
    ruleId: string,
    options: DecideOptionsMap,
  ): Promise<CmabDecision>
}

export type CmabCacheValue = {
  attributesHash: string,
  variationId: string,
  cmabUuid: string,
}

export type CmabServiceOptions = {
  logger?: LoggerFacade;
  cmabCache: CacheWithRemove<CmabCacheValue>;
  cmabClient: CmabClient;
}

const SERIALIZER_BUCKETS = 1000;
const LOGGER_NAME = 'CmabService';

export class DefaultCmabService implements CmabService {
  private cmabCache: CacheWithRemove<CmabCacheValue>;
  private cmabClient: CmabClient;
  private logger?: LoggerFacade;
  private serializers: SerialRunner[] = Array.from(
    { length: SERIALIZER_BUCKETS }, () => new SerialRunner()
  );

  constructor(options: CmabServiceOptions) {
    this.cmabCache = options.cmabCache;
    this.cmabClient = options.cmabClient;
    this.logger = options.logger;
    this.logger?.setName(LOGGER_NAME);
  }

  private getSerializerIndex(userId: string, experimentId: string): number {
    const key = this.getCacheKey(userId, experimentId);
    const hash = murmurhash.v3(key);
    return Math.abs(hash) % SERIALIZER_BUCKETS;
  }

  async getDecision(
    projectConfig: ProjectConfig,
    userContext: IOptimizelyUserContext,
    ruleId: string,
    options: DecideOptionsMap,
  ): Promise<CmabDecision> {
    const serializerIndex = this.getSerializerIndex(userContext.getUserId(), ruleId);
    return this.serializers[serializerIndex].run(() => 
      this.getDecisionInternal(projectConfig, userContext, ruleId, options)
    );
  }

  private async getDecisionInternal(
    projectConfig: ProjectConfig,
    userContext: IOptimizelyUserContext,
    ruleId: string,
    options: DecideOptionsMap,
  ): Promise<CmabDecision> {
    const userId = userContext.getUserId();
    const filteredAttributes = this.filterAttributes(projectConfig, userContext, ruleId);

    if (options[OptimizelyDecideOption.IGNORE_CMAB_CACHE]) {
      this.logger?.debug(IGNORE_CMAB_CACHE, userId, ruleId);
      return this.fetchDecision(ruleId, userId, filteredAttributes);
    }

    if (options[OptimizelyDecideOption.RESET_CMAB_CACHE]) {
      this.logger?.debug(RESET_CMAB_CACHE, userId, ruleId);
      this.cmabCache.reset();
    }

    const cacheKey = this.getCacheKey(userId, ruleId);

    if (options[OptimizelyDecideOption.INVALIDATE_USER_CMAB_CACHE]) {
      this.logger?.debug(INVALIDATE_CMAB_CACHE, userId, ruleId);
      this.cmabCache.remove(cacheKey);
    }

    const cachedValue = await this.cmabCache.lookup(cacheKey);

    const attributesJson = JSON.stringify(filteredAttributes, Object.keys(filteredAttributes).sort());
    const attributesHash = String(murmurhash.v3(attributesJson));

    if (cachedValue) {
      if (cachedValue.attributesHash === attributesHash) {
        this.logger?.debug(CMAB_CACHE_HIT, userId, ruleId);
        return { variationId: cachedValue.variationId, cmabUuid: cachedValue.cmabUuid };
      } else {
        this.logger?.debug(CMAB_CACHE_ATTRIBUTES_MISMATCH, userId, ruleId);
        this.cmabCache.remove(cacheKey);
      }
    } else {
      this.logger?.debug(CMAB_CACHE_MISS, userId, ruleId);
    }

    const variation = await this.fetchDecision(ruleId, userId, filteredAttributes);
    this.cmabCache.save(cacheKey, { 
      attributesHash,
      variationId: variation.variationId,
      cmabUuid: variation.cmabUuid,
    });

    return variation;
  }

  private async fetchDecision(
    ruleId: string,
    userId: string,
    attributes: UserAttributes,
  ): Promise<CmabDecision> {
    const cmabUuid = uuidV4();
    const variationId = await this.cmabClient.fetchDecision(ruleId, userId, attributes, cmabUuid);
    return { variationId, cmabUuid };
  }

  private filterAttributes(
    projectConfig: ProjectConfig,
    userContext: IOptimizelyUserContext,
    ruleId: string
  ): UserAttributes {
    const filteredAttributes: UserAttributes = {};
    const userAttributes = userContext.getAttributes();

    const experiment = projectConfig.experimentIdMap[ruleId];
    if (!experiment || !experiment.cmab) {
      return filteredAttributes;
    }

    const cmabAttributeIds = experiment.cmab.attributeIds;
    
    cmabAttributeIds.forEach((aid) => {
      const attribute = projectConfig.attributeIdMap[aid];
      
      if (userAttributes.hasOwnProperty(attribute.key)) {
        filteredAttributes[attribute.key] = userAttributes[attribute.key];
      }
    });

    return filteredAttributes;
  }

  private getCacheKey(userId: string, ruleId: string): string {
    const len = userId.length;
    return `${len}-${userId}-${ruleId}`;
  }
}