Built-in Functions Available in Probe's Expression Engine: Complete Reference

Probe's expression engine provides nine security-audited built-in functions for JSON comparison, random data generation, time utilities, type conversion, and Base64 encoding, all explicitly registered in main/expr.go.

The linyows/probe repository implements a secure expression evaluation system for workflow automation, deliberately restricting available operations to prevent arbitrary code execution. Unlike standard expr library configurations that expose dozens of potentially unsafe operations, Probe whitelists only nine specific built-in functions that are safe for untrusted workflow definitions.

Complete List of Built-in Functions in Probe

Probe registers these functions in main/expr.go (lines 51-214) inside the Expr.Options configuration block. Each function is designed for specific workflow automation tasks while maintaining strict security boundaries.

JSON Comparison Utilities

Probe provides two functions for comparing JSON-like maps, implemented in main/funcs.go and exposed through the expression engine:

• match_json(src, target): Returns true when two JSON-like maps match exactly, including nested structures. Signature: func(src map[string]any, target map[string]any) (bool, error).
• diff_json(src, target): Produces a human-readable diff string comparing two JSON-like maps. Signature: func(src map[string]any, target map[string]any) (string, error).

Random Data Generation

These utilities support test data creation and dynamic request building:

• random_int(n): Returns a random integer in the range [0, n). Signature: func(n int) (int, error).
• random_str(len): Generates a random alphanumeric string of the specified length. Signature: func(len int) (string, error).

Time and Type Conversion

Essential for timestamp handling and string-to-numeric conversions:

• unixtime(): Returns the current Unix timestamp in seconds. Signature: func() (int64, error).
• parse_float(s): Parses a string as a 64-bit floating-point number. Signature: func(s string) (float64, error).
• parse_int(s): Parses a string or numeric value as a 64-bit integer. Signature: func(s string) (int64, error).

Encoding and Decoding

Base64 operations for handling sensitive data:

• encode_base64(s): Returns the Base64-encoded representation of the input string. Signature: func(s string) (string, error).
• decode_base64(s): Decodes a Base64-encoded string back to plain text. Signature: func(s string) (string, error).

Security Design: Why Probe Limits Built-in Functions

The expression engine in main/expr.go calls ex.DisableBuiltin("all") to disable every default function provided by the underlying expr library, including common operations like len, contains, map, and filter.

This security-first approach prevents workflow authors from executing potentially unsafe operations or accessing sensitive runtime information. The repository then explicitly re-enables only the nine whitelisted functions listed above using ex.Function(...) registrations between lines 51 and 214. This design ensures that Probe expressions remain sandboxed and safe for executing untrusted workflow definitions.

Practical Usage Examples in Probe Workflows

The following examples demonstrate how to use these built-in functions within Probe's YAML workflow definitions.

Validating API Responses with JSON Matching

Use match_json to verify that an API response matches expected structure:

# In a Probe step definition

condition: "{{ match_json(response.body, {\"status\":\"ok\",\"code\":200}) }}"

Generating Dynamic Test Data

Create randomized identifiers and timestamps for unique request generation:

# Generate a 12-character random string

body: "{\"id\": \"{{ random_str(12) }}\", \"created\": {{ unixtime() }}}"

Numeric Calculations and Encoding

Convert string values to integers and encode sensitive data:

# Parse string to integer for arithmetic

headers:
  X-Offset: "{{ parse_int(response.headers['X-Total']) + 10 }}"

# Encode authentication credentials

body: "{\"token\": \"{{ encode_base64(\"user:pass\") }}\"}"

Source Code Reference

The implementation spans three key files in the main/ directory:

• main/expr.go: Defines the expression engine configuration, disables all default built-ins, and registers the nine whitelisted functions (lines 51-214).
• main/funcs.go: Contains the underlying Go implementations for match_json and diff_json logic.
• main/expr_test.go: Provides test coverage and usage examples for the custom function suite.

Summary

• Probe's expression engine exposes exactly nine built-in functions, explicitly whitelisted in main/expr.go.
• JSON utilities (match_json, diff_json) enable deep comparison of API responses.
• Randomization functions (random_int, random_str) support dynamic test data generation.
• Conversion utilities (unixtime, parse_float, parse_int) handle timestamps and type coercion.
• Base64 functions (encode_base64, decode_base64) manage encoding requirements.
• All default expr library functions are disabled via ex.DisableBuiltin("all") to ensure security.

Frequently Asked Questions

Can I add custom functions to Probe's expression engine?

To add custom functions, you would need to modify the source code in main/expr.go and add new ex.Function(...) registrations within the Expr.Options configuration block. The project does not currently support runtime plugin loading for security reasons.

Why can't I use standard len() or contains() functions in Probe expressions?

Probe explicitly disables all default built-in functions from the expr library—including len, contains, map, and filter—by calling ex.DisableBuiltin("all") in main/expr.go. This prevents potentially unsafe operations and ensures that only audited, whitelisted functions are available to workflow authors.

How does match_json handle nested JSON structures?

According to the implementation in main/funcs.go, match_json performs deep comparison of JSON-like maps, recursively checking nested objects and arrays for exact equality. It returns true only if both the structure and values match completely between the source and target maps.

Is there a performance difference between these built-in functions and standard Go operations?

The built-in functions are compiled Go functions registered with the expr engine, offering native performance characteristics. However, expressions are evaluated at runtime for each probe execution, so complex JSON comparisons using match_json on large payloads will consume more resources than simple string comparisons.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}