// MathJS bundle with only numbers is ~2x smaller than the default one. import { addDependencies, andDependencies, compareTextDependencies, compileDependencies, create, divideDependencies, equalDependencies, evaluateDependencies, maxDependencies, minDependencies, multiplyDependencies, notDependencies, nullishDependencies, orDependencies, subtractDependencies, unequalDependencies, xorDependencies, } from 'mathjs'; import { ACTOR_LIMITS } from '@apify/consts'; import type { ActorRunOptions, CompilationCache, CompilationResult, MemoryEvaluationContext } from './types.js'; // In theory, users could create expressions longer than 1000 characters, // but in practice, it's unlikely anyone would need that much complexity. // Later we can increase this limit if needed. export const DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH = 1000; /** * A Set of allowed keys from ActorRunOptions that can be used in * the {{runOptions.variable}} syntax. */ const ALLOWED_RUN_OPTION_KEYS = new Set([ 'build', 'timeoutSecs', 'memoryMbytes', 'diskMbytes', 'maxItems', 'maxTotalChargeUsd', 'restartOnError', ]); /** * Create a mathjs instance with selected dependencies, then disable potentially dangerous ones. * MathJS security recommendations: https://mathjs.org/docs/expressions/security.html */ const math = create({ // expression dependencies // Required for compiling and evaluating root expressions. // We disable it below to prevent users from calling `evaluate()` inside their expressions. // For example: defaultMemoryMbytes = "evaluate('2 + 2')" compileDependencies, evaluateDependencies, // arithmetic dependencies addDependencies, subtractDependencies, multiplyDependencies, divideDependencies, // statistics dependencies maxDependencies, minDependencies, // logical dependencies andDependencies, notDependencies, orDependencies, xorDependencies, // without that dependency 'null ?? 5', won't work nullishDependencies, // comparison dependencies // equal/unequal power the `==`/`!=` operators equalDependencies, unequalDependencies, // compareText does a case-sensitive lexical comparison, returning 0 when strings are equal. // This is what makes matching string enum values reliable, e.g. // compareText(input.dataOutput, 'full detail') == 0 ? 1024 : 512 compareTextDependencies, }); const { compile } = math; // Disable potentially dangerous functions math.import( { // We disable evaluate to prevent users from calling it inside their expressions. // For example: defaultMemoryMbytes = "evaluate('2 + 2')" evaluate() { throw new Error('Function evaluate is disabled.'); }, compile() { throw new Error('Function compile is disabled.'); }, // We need to disable it, because compileDependencies imports parseDependencies. parse() { throw new Error('Function parse is disabled.'); }, }, { override: true }, ); /** * Safely retrieves a nested property from an object using a dot-notation string path. * * This is custom function designed to be injected into the math expression evaluator, * allowing expressions like `get(input, 'user.settings.memory', 512)` or `get(input, 'startUrls.length', 10)` to get array length. * Only own properties are followed, so inherited members like `toString` resolve to `defaultVal`. * * @param obj The source object to search within. * @param path A dot-separated string representing the nested path (e.g., "input.payload.size"). * @param defaultVal The value to return if the path is not found or the value is `null` or `undefined`. * @returns The retrieved value, or `defaultVal` if the path is unreachable. */ const customGetFunc = (obj: any, path: string, defaultVal?: number) => { return ( path .split('.') .reduce( (current, key) => (current != null && Object.hasOwn(current, key) ? current[key] : undefined), obj, ) ?? defaultVal ); }; /** * Rounds a number to the closest power of 2. * The result is clamped to the allowed range (ACTOR_LIMITS.MIN_RUN_MEMORY_MBYTES - ACTOR_LIMITS.MAX_RUN_MEMORY_MBYTES). * @param num The number to round. * @returns The closest power of 2 within min/max range. */ const roundToClosestPowerOf2 = (num: number): number => { if (typeof num !== 'number' || Number.isNaN(num) || !Number.isFinite(num)) { throw new Error(`Calculated memory value is not a valid number: ${num}.`); } // Handle 0 or negative values. if (num <= 0) { throw new Error(`Calculated memory value must be a positive number, greater than 0, got: ${num}.`); } const log2n = Math.log2(num); const roundedLog = Math.round(log2n); const result = 2 ** roundedLog; return Math.max(ACTOR_LIMITS.MIN_RUN_MEMORY_MBYTES, Math.min(result, ACTOR_LIMITS.MAX_RUN_MEMORY_MBYTES)); }; /** * Replaces all `{{variable}}` placeholders in an expression into direct * property access (e.g. `{{runOptions.memoryMbytes}}` → `runOptions.memoryMbytes`). * * All `input.*` values are accepted, while `runOptions.*` are validated (7 variables from ALLOWED_RUN_OPTION_KEYS). * * Note: While not really needed for Math.js, this approach allows developers * to use a consistent double-brace templating syntax `{{runOptions.timeoutSecs}}` * across the Apify platform. We also want to avoid compiling the expression with the * actual values as that would make caching less effective. * * @example * // Returns "runOptions.memoryMbytes + 1024" * preprocessDefaultMemoryExpression("{{runOptions.memoryMbytes}} + 1024"); * * @param defaultMemoryMbytes The raw string expression, e.g., "{{runOptions.memoryMbytes}} * 2". * @returns A safe, processed expression for evaluation, e.g., "runOptions.memoryMbytes * 2". */ const processTemplateVariables = (defaultMemoryMbytes: string): string => { const variableRegex = /{{\s*([a-zA-Z0-9_.]+)\s*}}/g; const processedExpression = defaultMemoryMbytes.replace(variableRegex, (_, variableName: string) => { // 1. Check if the variable is accessing input (e.g. {{input.someValue}}) // We do not validate the specific property name because `input` is dynamic. if (variableName.startsWith('input.')) { return variableName; } // 2. Check if the variable is accessing runOptions (e.g. {{runOptions.memoryMbytes}}) and validate the keys. if (variableName.startsWith('runOptions.')) { const key = variableName.slice('runOptions.'.length); if (!ALLOWED_RUN_OPTION_KEYS.has(key as keyof ActorRunOptions)) { throw new Error( `Invalid variable '{{${variableName}}}' in expression. Only the following runOptions are allowed: ${Array.from( ALLOWED_RUN_OPTION_KEYS, ) .map((k) => `runOptions.${k}`) .join(', ')}.`, ); } return variableName; } // 3. Throw error for unrecognized variables (e.g. {{someVariable}}) throw new Error(`Invalid variable '{{${variableName}}}' in expression.`); }); return processedExpression; }; /* * Retrieves a compiled expression from the cache or compiles it if not present. * * @param expression The expression string to compile. * @param cache An optional cache to store/retrieve compiled expressions. * @returns The compiled CompilationResult. */ const getCompiledExpression = async ( expression: string, cache: CompilationCache | undefined, ): Promise => { if (!cache) { return compile(expression); } let compiledExpression = await cache.get(expression); if (!compiledExpression) { compiledExpression = compile(expression); await cache.set(expression, compiledExpression!); } return compiledExpression; }; /** * Evaluates a dynamic memory expression string using the provided context. * Result is rounded to the closest power of 2 and clamped within allowed limits. * * @param defaultMemoryMbytes The string expression to evaluate (e.g., `get(input, 'urls.length', 10) * 1024` for `input = { urls: ['url1', 'url2'] }`). * @param context The `MemoryEvaluationContext` (containing `input` and `runOptions`) available to the expression. * @param options.cache Optional synchronous cache. Since compiled functions cannot be saved to a database/Redis, they are kept in local memory. * @returns The calculated memory value rounded to the closest power of 2 and clamped within allowed limits. */ export const calculateRunDynamicMemory = async ( defaultMemoryMbytes: string, context: MemoryEvaluationContext, options: { cache: CompilationCache } | undefined = undefined, ) => { if (defaultMemoryMbytes.length > DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH) { throw new Error( `The defaultMemoryMbytes expression is too long. Max length is ${DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH} characters.`, ); } // Replaces all occurrences of {{variable}} with variable // e.g., "{{runOptions.memoryMbytes}} + 1024" becomes "runOptions.memoryMbytes + 1024" const preprocessedExpression = processTemplateVariables(defaultMemoryMbytes); const preparedContext = { ...context, get: customGetFunc, }; const compiledExpression = await getCompiledExpression(preprocessedExpression, options?.cache); let finalResult: number | { entries: number[] } = compiledExpression.evaluate(preparedContext); // Mathjs wraps multi-line expressions in an object, so we need to extract the last entry. // Note: one-line expressions return a number directly. if (finalResult && typeof finalResult === 'object' && 'entries' in finalResult) { const { entries } = finalResult; finalResult = entries[entries.length - 1]; } return roundToClosestPowerOf2(finalResult); };