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

> Discover Probe's expression engine and its nine built-in functions for JSON comparison, random data, time utilities, type conversion, and Base64 encoding. Explore the complete reference.

- Repository: [Tomohisa Oda/probe](https://github.com/linyows/probe)
- Tags: api-reference
- Published: 2026-03-06

---

**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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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:

```yaml

# 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:

```yaml

# 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:

```yaml

# 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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/main/funcs.go)**: Contains the underlying Go implementations for `match_json` and `diff_json` logic.
- **[`main/expr_test.go`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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.