Package engine

import "github.com/ornew/hff/engine"

Generated from this checkout's Go source. Released versions are also on pkg.go.dev.

Overview

Package engine configures HFF compilation and validates host records.

New requires an input schema and an explicitly selected capability policy, such as capabilities.Standard(). The root schema is a nonnullable struct or string-keyed map. Options apply from left to right, allowing a common WithConfig configuration to be followed by service-specific overrides. Configuration is validated and copied before New returns.

Compile checks the fixed query grammar, declared types, feature permissions, and compile limits. Its Program is independent of an execution backend. Pass it to local.Build for record matching or sql.Build for query translation; neither backend is imported or constructed by engine compilation.

Configure an Engine once at service startup and reuse it concurrently. Compile a filter once when accepting a query, then reuse the built backend artifact for multiple records or database executions. Avoid recompiling the same query for each record.

Validate checks an actual record, including required fields and numeric kinds, and returns an immutable hff.Input. Local Match validates ordinary values on each call; MatchInput can reuse a previously validated input when the Program's schema is exactly equal. Validate does not determine whether a record matches a query, and Compile does not validate any runtime record.

Compile may return multiple source-located diagnostics. Use errors.As with *hff.Diagnostics or *hff.Error rather than parsing error message text.

Index

• type Config
• type Engine
  • func New(options ...Option) (*Engine, error)
  • func (e *Engine) Capabilities() capabilities.Set
  • func (e *Engine) Compile(ctx context.Context, source string) (hff.Program, error)
  • func (e *Engine) Limits() hff.Limits
  • func (e *Engine) Methods() []hff.MethodDeclaration
  • func (e *Engine) Schema() hff.Type
  • func (e *Engine) Validate(ctx context.Context, record hff.Value) (hff.Input, error)
• type Option
  • func WithCapabilities(s capabilities.Set) Option
  • func WithConfig(config *Config) Option
  • func WithLimits(l hff.Limits) Option
  • func WithMethods(methods ...hff.MethodDeclaration) Option
  • func WithSchema(t hff.Type) Option
  • func WithUnlimitedLimits() Option

Types

type Config

Source

type Config struct {
	// Schema is the required root struct or map schema.
	Schema	hff.Type
	// Capabilities is the explicit permission set used by Compile.
	Capabilities	capabilities.Set
	// Limits selects compiler and input-validation ceilings; zero fields default.
	Limits	hff.Limits
	// UnlimitedLimits explicitly disables configured limits.
	UnlimitedLimits	bool
	// Methods declares extension signatures; implementations belong to backends.
	Methods	[]hff.MethodDeclaration
}

Config is the complete configuration accepted by WithConfig. New validates and snapshots the schema, declarations, capabilities, and limits. A valid struct or map root schema and an explicitly selected capability policy are required.

type Engine

Source

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

Engine is immutable and supports concurrent calls.

func New

Source

func New(options ...Option) (*Engine, error)

New validates options, schema, capabilities, extension declarations, and limits. The returned Engine snapshots its configuration and supports concurrent Compile and Validate calls.

Example

{
	base := &engine.Config{
		Schema:		schema.Struct(schema.Int("age")),
		Capabilities:	capabilities.Standard(),
	}

	e, err := engine.New(engine.WithConfig(base),
		engine.WithCapabilities(base.Capabilities.Without(capabilities.Regex)))
	if err != nil {
		panic(err)
	}
	fmt.Println("regex enabled:", e.Capabilities().Has(capabilities.RegexOperators))
	fmt.Println("base unchanged:", base.Capabilities.Has(capabilities.RegexOperators))

}

package main

import (
	"fmt"

	"github.com/ornew/hff/capabilities"
	"github.com/ornew/hff/engine"
	"github.com/ornew/hff/schema"
)

func main() {
	base := &engine.Config{
		Schema:		schema.Struct(schema.Int("age")),
		Capabilities:	capabilities.Standard(),
	}
	// Later options replace fields from the common configuration.
	e, err := engine.New(engine.WithConfig(base),
		engine.WithCapabilities(base.Capabilities.Without(capabilities.Regex)))
	if err != nil {
		panic(err)
	}
	fmt.Println("regex enabled:", e.Capabilities().Has(capabilities.RegexOperators))
	fmt.Println("base unchanged:", base.Capabilities.Has(capabilities.RegexOperators))
}

Output:

regex enabled: false
base unchanged: true

func (*Engine) Capabilities

Source

func (e *Engine) Capabilities() capabilities.Set

Capabilities returns the selected compilation policy.

func (*Engine) Compile

Source

func (e *Engine) Compile(ctx context.Context, source string) (hff.Program, error)

Compile checks syntax, types, and capabilities and produces a reusable plan. It returns typed syntax, type, capability, limit, or cancellation errors. It does not construct a local evaluator or a backend query.

Example

{
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.String("name"), schema.Int("age"))),
		engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	program, err := e.Compile(context.Background(), `name="Alice" age>=18`)
	if err != nil {
		panic(err)
	}

	fmt.Println("valid plan:", program.Valid())
	fmt.Println("schema retained:", program.Schema().Equal(e.Schema()))

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff/capabilities"
	"github.com/ornew/hff/engine"
	"github.com/ornew/hff/schema"
)

func main() {
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.String("name"), schema.Int("age"))),
		engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	program, err := e.Compile(context.Background(), `name="Alice" age>=18`)
	if err != nil {
		panic(err)
	}
	// A Program is a typed plan. A backend Build decides how it will execute.
	fmt.Println("valid plan:", program.Valid())
	fmt.Println("schema retained:", program.Schema().Equal(e.Schema()))
}

Output:

valid plan: true
schema retained: true

func (*Engine) Limits

Source

func (e *Engine) Limits() hff.Limits

Limits returns resolved common compiler and input-validation limits.

func (*Engine) Methods

Source

func (e *Engine) Methods() []hff.MethodDeclaration

Methods returns a copy of the configured immutable declarations.

func (*Engine) Schema

Source

func (e *Engine) Schema() hff.Type

Schema returns the immutable root input schema.

func (*Engine) Validate

Source

func (e *Engine) Validate(ctx context.Context, record hff.Value) (hff.Input, error)

Validate validates a complete host record against this Engine's schema and input limits. It returns an immutable Input suitable for repeated matching by a backend whose Program uses the same schema contract. Invalid records, cancellation, and exceeded limits return typed errors with no partial Input.

Example

{
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.String("name"), schema.Int("age"))), engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	input, err := e.Validate(context.Background(), hff.Object(map[string]hff.Value{"name": hff.String("Alice"), "age": hff.Int(18)}))
	if err != nil {
		panic(err)
	}
	name, _ := input.Value().Lookup("name")
	text, _ := name.AsString()
	fmt.Println(text, input.Compatible(schema.Struct(schema.Int("age"), schema.String("name"))))

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/capabilities"
	"github.com/ornew/hff/engine"
	"github.com/ornew/hff/schema"
)

func main() {
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.String("name"), schema.Int("age"))), engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	input, err := e.Validate(context.Background(), hff.Object(map[string]hff.Value{"name": hff.String("Alice"), "age": hff.Int(18)}))
	if err != nil {
		panic(err)
	}
	name, _ := input.Value().Lookup("name")
	text, _ := name.AsString()
	fmt.Println(text, input.Compatible(schema.Struct(schema.Int("age"), schema.String("name"))))
}

Output:

Alice true

Example

{
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.Int("age"))),
		engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	_, err = e.Validate(context.Background(), hff.Object(nil))
	fmt.Println("missing required nonnullable age:", err != nil)

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/capabilities"
	"github.com/ornew/hff/engine"
	"github.com/ornew/hff/schema"
)

func main() {
	e, err := engine.New(engine.WithSchema(schema.Struct(schema.Int("age"))),
		engine.WithCapabilities(capabilities.Standard()))
	if err != nil {
		panic(err)
	}
	_, err = e.Validate(context.Background(), hff.Object(nil))
	fmt.Println("missing required nonnullable age:", err != nil)
}

Output:

missing required nonnullable age: true

type Option

Source

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

Option changes one Engine setting. New applies options from left to right.

func WithCapabilities

Source

func WithCapabilities(s capabilities.Set) Option

WithCapabilities sets the explicit capability policy used during compilation.

func WithConfig

Source

func WithConfig(config *Config) Option

WithConfig copies a complete configuration. Later options override fields set by this option; a nil config is a ConfigurationError.

func WithLimits

Source

func WithLimits(l hff.Limits) Option

WithLimits replaces limits and disables UnlimitedLimits.

func WithMethods

Source

func WithMethods(methods ...hff.MethodDeclaration) Option

WithMethods replaces the extension declarations in the configuration.

func WithSchema

Source

func WithSchema(t hff.Type) Option

WithSchema sets the root input schema. New requires a valid struct or map.

func WithUnlimitedLimits

Source

func WithUnlimitedLimits() Option

WithUnlimitedLimits explicitly disables limits resolved by this Engine.