jqeval

Documentation

Overview

Package jqeval provides bounded evaluation of jq programs via gojq.

It is the shared core behind the smoothdb jq surfaces (POST /jq, jq-update, response transforms): compiled program cache, per-evaluation timeout, program size guard and the exactly-one-output convention.

No custom functions and no I/O builtins are registered, so programs cannot touch anything beyond the JSON input they are handed.

Index

• func Configure(c *Config)
• func Enabled() bool
• func Eval(ctx context.Context, program string, input any, args map[string]any) (any, error)
• func Marshal(v any) ([]byte, error)
• func MaxProgramBytes() int
• func MaxUpdateRows() int
• func Parse(program string, args map[string]any) error
• func Unmarshal(data []byte) (any, error)
• type Config
  • func DefaultConfig() *Config
• type Error
  • func (e Error) Error() string

Functions

func Configure

func Configure(c *Config)

Configure sets the package configuration and resets the compiled program cache. It is meant to be called once at startup, before serving requests. Zero or negative values fall back to the defaults (Enabled excepted).

func Enabled

func Enabled() bool

Enabled reports whether jq evaluation is enabled in the configuration

func Eval

func Eval(ctx context.Context, program string, input any, args map[string]any) (any, error)

Eval evaluates a jq program against a single input value, binding args as jq variables ({"step": 3} is accessible as $step). The input must be encoding/json-shaped (nil, bool, int, float64, *big.Int, string, []any, map[string]any - see Unmarshal).

The program must produce exactly one output value: zero or multiple outputs are an error (programs wanting a stream can wrap it: [.items[] | ...]). Evaluation is bounded by the configured timeout.

func Marshal

func Marshal(v any) ([]byte, error)

Marshal encodes a jq output value as JSON

func MaxProgramBytes

func MaxProgramBytes() int

MaxProgramBytes returns the maximum allowed size for a jq program. The same cap applies to the raw jq_args parameter.

func MaxUpdateRows

func MaxUpdateRows() int

MaxUpdateRows returns the maximum number of rows a single jq update can affect

func Parse

func Parse(program string, args map[string]any) error

Parse compile-checks a jq program with the given argument names, without evaluating it. Used for authoring-time validation (parse_only). Only the keys of args matter here; values may be nil.

func Unmarshal

func Unmarshal(data []byte) (any, error)

Unmarshal decodes JSON bytes into the value shape gojq expects. Integers are preserved exactly (int or *big.Int instead of float64), so that ids and counters survive a jq round trip.

Types

type Config

type Config struct {
	Enabled         bool `comment:"Enable jq evaluation: /jq route, jq= query parameter (default: false)"`
	Timeout         int  `comment:"Timeout in milliseconds for a single jq evaluation (default: 250)"`
	MaxProgramBytes int  `comment:"Maximum size in bytes for a jq program or its arguments (default: 4096)"`
	MaxUpdateRows   int  `comment:"Maximum number of rows updatable with a single jq update (default: 1000)"`
	CacheEntries    int  `comment:"Size of the compiled jq program cache (default: 256)"`
}

Config holds the jq evaluation settings. It appears as the "JQ" section in the server configuration.

func DefaultConfig

func DefaultConfig() *Config

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is the error type for all jq related failures (parse errors, evaluation errors, timeouts, guard violations)

func (Error) Error

func (e Error) Error() string