Host Values

Host values let an embedding application expose Go-managed resources and objects to FQL scripts. This page covers how to implement them in Go. For the FQL perspective — what host values look like inside a script and which operations they support — see Host Values and Capability Types.

When to implement a host value

• Resource handle — the Go object owns an external resource (database connection, file handle, HTTP client) whose lifecycle outlives a single function call.
• Lazy value — the value materializes data only when accessed, avoiding upfront cost (cursor, paginated result set).
• Domain object — the value has rich behavior (property access, iteration, dispatch) that cannot be expressed as a plain array or object.
• External client — the value wraps a Go client library and exposes its operations through FQL capabilities (query, dispatch, subscribe).
• Controlled capabilities — you want to expose only certain operations (read-only properties, no iteration) rather than giving scripts full access to the underlying data.

Choosing the right mechanism

When in doubt, walk through these questions:

The Value interface

Every host value must satisfy runtime.Value:

• String() — text representation used by to_string() and encoding fallbacks.
• Hash() — identity hash used by the VM for deduplication and map keys. Use fnv.New64a from the standard library.
• Copy() — shallow copy. For host values that wrap a pointer, returning the same pointer is usually correct.

Optionally implement Typed so the runtime can report your type in error messages and enable generic argument casting with CastArg:

Create a type with runtime.NewTypeFor:

Minimal implementation

The smallest possible host value — a struct that wraps a string:

Register a function that returns it:

Adding capabilities

A host value without capability interfaces is opaque — scripts can hold it and pass it around, but cannot access properties, iterate over it, or query it. Implement capability interfaces to enable FQL operations on the value.

Property and index access

Adding property access to the Label type:

Iteration and measurement

Iterator.Next must return io.EOF when the sequence is exhausted. If the iterator holds resources (an open cursor, for example), implement io.Closer on it as well.

Bulk snapshots for spread

Array spread accepts values that implement runtime.List, and object spread accepts values that implement runtime.Map. Ferret can enumerate those interfaces directly, so host values do not need another capability for correctness.

Remote or paginated collections can optionally provide a native bulk representation:

When a valid List or Map implements the matching snapshot interface, spread calls Snapshot once and copies from the returned native Array or Object. A successful call must return a non-nil value. If it returns an error, spread propagates that error without retrying through element-by-element or property-by-property enumeration.

The snapshot interfaces are optional optimizations. Implementing ListSnapshotter without runtime.List, or MapSnapshotter without runtime.Map, does not make a value spreadable.

Snapshot is a bulk read of the collection’s current contents. It does not promise transactional or atomic point-in-time consistency for a remote source unless the host implementation provides that guarantee. It also does not transfer ownership and is separate from vm.Materialize, which performs terminal conversion of a VM result with explicit lifecycle semantics.

Query, dispatch, and observe

The Queryable interface has four methods: Query, QueryOne, QueryCount, and QueryExists. If your implementation only needs the list-returning Query, delegate the other three to the built-in helpers:

The Query struct carries the expression, dialect, parameters, and options from the FQL statement:

Comparison and other capabilities

Equatable and Comparable are independent. Equal must be reflexive, symmetric, and transitive within the value’s compatible comparison domain, and must return false without an error for an incompatible value. Compare must provide a reflexive, antisymmetric, and transitive order within that domain and return an error compatible with runtime.ErrInvalidOperation for an incompatible value. If both interfaces are implemented, Equal must return true exactly when Compare returns runtime.Equal.

Semantically equal values must return the same Hash(). A hash is only a candidate selector; Ferret verifies Equal before grouping or deduplicating host values.

Both methods receive the execution context unchanged and may return operational errors. Any negative or positive Ordering is normalized to runtime.Less or runtime.Greater by runtime dispatch.

Unwrappable is useful when other Go code (custom functions, modules) needs to access the underlying Go object. The runtime.UnwrapAs generic helper simplifies extraction:

Returning host values from functions

A common pattern is a namespaced function that opens a resource and returns it as a host value. The following example implements a minimal in-memory store that supports query ... in:

Passing host values as parameters

Instead of creating a host value inside a function, you can pass one directly as a parameter with WithRuntimeParam or WithSessionRuntimeParam:

This is useful when the host application controls the resource lifecycle and wants to share a single instance across multiple query executions. The engine-level parameter is available to every session without re-creation.

For per-session values, use WithSessionRuntimeParam:

Cleanup and finalization

The runtime automatically tracks values that implement io.Closer:

1. During execution, any io.Closer value encountered in the result is added to a tracked closer set.
2. After encoding the output, the runtime calls Close() on every tracked closer.
3. Errors from Close() are propagated to the caller of Session.Run.

This means a host value returned by a function inside a script is encoded first, then closed. The host receives the encoded output; the value is already closed by the time Run returns.

For values referenced multiple times, implement the Resource interface to prevent double-closing:

ResourceID must return a stable, unique identifier for the resource. The runtime uses it to deduplicate closers — two references to the same resource result in a single Close call.

Values stored in engine-level parameters are not tracked by the result’s closer set. The host owns their lifecycle and must close them explicitly when the engine shuts down.

Context and cancellation

The VM observes query cancellation at structural execution boundaries, such as loop backedges, calls, debugger observations, and top-level completion. Native arithmetic, comparison, property access, and collection work between those boundaries is atomic from the VM’s perspective.

Context-aware host functions and capabilities receive the original execution context. An implementation that waits, performs network or database I/O, advances a remote iterator, or otherwise retains control must observe that context itself:

Return cancellation with %w when adding context. Errors compatible with context.Canceled or context.DeadlineExceeded terminate execution directly and cannot be caught by on error, retry recovery, or another protected FQL operation.

io.Closer has no context parameter. Its Close call is treated as one atomic operation.

Error behavior

When a capability method returns a non-cancellation error, the VM raises an FQL runtime error at the point of the operation. The error message includes the value’s type and the Go error text. FQL scripts can recover from eligible errors with on error .... Cancellation and deadline errors always propagate to the embedding caller. See Error Handling.

When the script attempts an operation that requires a capability the value does not implement (for example, for x in val on a non-Iterable value), the VM raises a type error listing the expected capability.

Use the runtime error helpers to return well-formatted errors from your capability methods:

The Proxy shortcut

For cases where a Go type already implements some capability interfaces, sdk.Proxy[T] avoids the boilerplate of implementing Value manually. The proxy wraps any Go value and delegates capability calls via type assertion:

If *MyDB implements Queryable, calls to proxy.Query delegate to myDB.Query. If it does not implement Iterable, proxy.Iterate returns a typed error. The proxy also handles Value methods (String, Hash, Copy), Typed, Unwrappable, json.Marshaler, and equality delegation automatically.

For Go maps and slices, use the specialized variants:

ProxyMap automatically implements KeyReadable, KeyWritable, and Iterable for map[string]V types. ProxySlice implements IndexReadable, IndexWritable, and Sortable.

Next steps