View all results

Remote runtimes (Wire)

Your application embeds Ferret and registers an app::greet function. A separate client needs to run a script that calls it, using the application’s existing runtime setup:

greeting.fql
read-only
RETURN app::greet(@name)

Wire lets the client compile and execute this script against the hosted runtime. With name set to "Ada", it returns the JSON string "Hello, Ada!". The custom function is registered on the host; the client sends source and parameters.

Use Wire when another process needs your application’s functions, modules, services, or runtime configuration without rebuilding that setup locally.

How the pieces fit together

Ferret Core provides the native engine and its embedding configuration. The Universal API provides shared runtime, plan, session, and debugger contracts. Wire exposes a hosted implementation remotely; its Go client returns an api.Runtime.

This guide and its runnable example use published releases with Universal API v1.0.0-alpha.21 consumable output. A successful Run returns a one-shot handle. Collect or consume it to observe completion; close it if you abandon it. See Output for the shared contract.

Runtime construction and configuration remain the host’s responsibility. The Universal API guide explains the adapter; the example below pins a compatible published dependency set.

The current implementation uses protobuf and gRPC, with a Go server and client. This guide uses those implementations.

Run a host and client

The example contains two complete programs in a separate Go module. It requires Go 1.26.0 or later and pins these compatible versions:

Dependency Version
Ferret Core v2.0.0-alpha.62
Universal API v1.0.0-alpha.21
Wire v1.0.0-alpha.4
gRPC v1.84.0

Download the example and its dependencies:

terminal
git clone https://github.com/MontFerret/montferret.github.io.gitcd montferret.github.io/examples/wirego mod download

The module resolves published dependencies directly, with no local checkout replacement. Keep these pins together when upgrading. Both Wire peers must negotiate output framing version 1 during Connect; incompatible peers fail at startup, with no buffered-output fallback. Upgrade older hosts and clients together using the consumable output migration.

Host the configured engine

Save this program as host/main.go. The host registers a typed, one-argument function, constructs the native engine, wraps it through the official adapter, and serves it through Wire.

host/main.go
read-only
package main import ( "context" "errors" "flag" "fmt" "log" "net" "os" "os/signal" "syscall" "time" "github.com/MontFerret/ferret/v2" "github.com/MontFerret/ferret/v2/pkg/runtime" "github.com/MontFerret/ferret/v2/uapi" "github.com/MontFerret/wire/server" ) func main() { address := flag.String("listen", "127.0.0.1:50051", "local development endpoint") flag.Parse() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() if err := run(ctx, *address); err != nil { log.Print(err) os.Exit(1) } } func run(ctx context.Context, address string) (resultErr error) { native, err := ferret.New(ferret.WithFunctionsRegistrar(func(ns runtime.Namespace) { ns.Namespace("app").Function().A1().Add("greet", func(ctx context.Context, arg runtime.Value) (runtime.Value, error) { if err := ctx.Err(); err != nil { return nil, err } name, err := runtime.CastArg[runtime.String](arg, 0) if err != nil { return nil, err } return runtime.NewString("Hello, " + string(name) + "!"), nil }) })) if err != nil { return err } defer func() { resultErr = errors.Join(resultErr, native.Close()) }() // Wrap and Wire borrow this engine; the host remains its owner. hosted := uapi.Wrap(native, "v2.0.0-alpha.62") wireServer, err := server.New(hosted) if err != nil { return err } // Plaintext transport is for local development only. listener, err := net.Listen("tcp", address) if err != nil { return err } defer func() { if err := listener.Close(); !errors.Is(err, net.ErrClosed) { resultErr = errors.Join(resultErr, err) } }() served := make(chan error, 1) go func() { served <- wireServer.Serve(context.Background(), listener) }() serveReturned := false defer func() { shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() shutdownErr := wireServer.Shutdown(shutdownCtx) resultErr = errors.Join(resultErr, shutdownErr) if errors.Is(shutdownErr, context.DeadlineExceeded) || errors.Is(shutdownErr, context.Canceled) { // A timeout bounds waiting, not hosted cleanup. Keep the engine alive // until the retained shutdown lifecycle actually settles. resultErr = errors.Join(resultErr, wireServer.Shutdown(context.Background())) } if !serveReturned { select { case err := <-served: resultErr = errors.Join(resultErr, err) case <-shutdownCtx.Done(): resultErr = errors.Join(resultErr, shutdownCtx.Err()) } } }() if _, err := fmt.Printf("Listening on %s\n", listener.Addr()); err != nil { return err } select { case resultErr = <-served: serveReturned = true case <-ctx.Done(): // Shutdown settles Wire-owned work before the host closes its engine. } return resultErr }

uapi.Wrap borrows the engine. The supplied version identifies Ferret Core, independently of the host application and Wire. The host remains responsible for shutting down Wire and closing the engine.

Start the host in the example directory:

terminal
go run ./host

It prints:

Listening on 127.0.0.1:50051

This example uses local-development-only plaintext transport on loopback. Loopback binding limits network exposure; it does not authenticate clients. Configure deployment security before exposing an endpoint beyond this example.

Execute from another process

Save this program as client/main.go. It uses client.New(ctx, target, client.WithInsecure()) to create and own its channel, then follows the normal Universal API flow: Compile → NewSession → Run → Collect. The output is settled before the session, plan, and remote runtime are closed.

client/main.go
read-only
package main import ( "context" "errors" "flag" "fmt" "log" "os" "os/signal" "syscall" "time" "github.com/MontFerret/api" "github.com/MontFerret/wire/client" ) func main() { address := flag.String("address", "127.0.0.1:50051", "host endpoint") name := flag.String("name", "Ada", "greeting parameter") timeout := flag.Duration("timeout", 10*time.Second, "maximum query duration") flag.Parse() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() ctx, cancel := context.WithTimeout(ctx, *timeout) defer cancel() if err := run(ctx, *address, *name); err != nil { log.Print(err) os.Exit(1) } } func run(ctx context.Context, address, name string) (resultErr error) { // Plaintext transport is for local development only. remote, err := client.New(ctx, address, client.WithInsecure()) if err != nil { return err } defer func() { resultErr = errors.Join(resultErr, remote.Close()) }() plan, err := remote.Compile(ctx, api.NewSource("greeting.fql", "RETURN app::greet(@name)")) if err != nil { return err } defer func() { resultErr = errors.Join(resultErr, plan.Close()) }() session, err := plan.NewSession(ctx, api.WithParam("name", name), api.WithOutputContentType("application/json"), ) if err != nil { return err } defer func() { resultErr = errors.Join(resultErr, session.Close()) }() output, err := session.Run(ctx) if err != nil { return err } defer func() { resultErr = errors.Join(resultErr, output.Close()) }() // Collect observes completion and may preserve content alongside an error. content, err := output.Collect(ctx) if content != nil { _, writeErr := fmt.Printf("Content-Type: %s\n%s\n", content.Metadata.ContentType, content.Data) err = errors.Join(err, writeErr) } return err }

In another terminal, from the same example directory, run:

terminal
go run ./client

The output is:

Content-Type: application/json
"Hello, Ada!"

The client has no native engine or function registration. app::greet runs on the host with the supplied parameter. To change it, run go run ./client -name Grace.

Both programs handle Ctrl+C and termination signals. The client bounds its operations with a ten-second context; use -timeout to change that bound. Cancellation ends work but does not replace explicit resource cleanup. Execution and cleanup errors are reported with a nonzero exit status, and available output is inspected independently of an error.

Stop the host with Ctrl+C. It first waits with a fresh five-second shutdown context. If that wait expires, it retains the timeout error and waits for cleanup to settle before closing the native engine and reporting the result. Uncooperative hosted cleanup can therefore keep the process alive beyond five seconds. For a different local port, start go run ./host -listen 127.0.0.1:50052 and use go run ./client -address 127.0.0.1:50052. The -listen, -address, -name, and -timeout flags belong to these example programs.

Choose startup and shutdown ownership

server.New(hosted, options...) configures Wire without listening or taking ownership of the supplied api.Runtime. A server accepts one serving lifetime. Both startup paths use the same transport credentials, interceptors, limits, and shutdown lifecycle.

For a known TCP address, Server.Run blocks through serving and managed shutdown. This compiled example uses the host’s existing runtime:

managed/loopback.go
read-only
package managed import ( "context" "errors" "time" "github.com/MontFerret/api" "github.com/MontFerret/wire/server" ) // ServeLoopback borrows the host's configured runtime. The host closes it only // after this function returns, including when the managed wait times out. func ServeLoopback(ctx context.Context, hosted api.Runtime) (err error) { srv, err := server.New(hosted) if err != nil { return err } defer func() { // A timed-out Run can leave hosted cleanup in progress. err = errors.Join(err, srv.Shutdown(context.Background())) }() // Plaintext loopback is an explicit local-development policy. return srv.Run(ctx, "127.0.0.1:50051", server.WithShutdownTimeout(30*time.Second)) }

Canceling or reaching the deadline of the serving context triggers shutdown. Run computes a separate cleanup deadline: 30 seconds by default, or a positive server.WithShutdownTimeout(duration) override. The budget starts when shutdown begins. A deadline supplied to Shutdown can shorten the effective deadline; later calls cannot extend it. Shutdown(context.Background()) cannot disable an accepted managed budget.

At the effective deadline, Wire forces transport shutdown independently of blocked hosted cleanup. Run returns an error matching context.DeadlineExceeded, joined with known independent failures. This does not mean hosted cleanup has finished. A subsequent Shutdown waits on the retained lifecycle and returns its actual settlement result without repeating cleanup. The example waits for that settlement before its caller may close the borrowed runtime. Successful cancellation or explicit shutdown returns nil only after serving and cleanup both settle successfully.

Use Serve(ctx, listener) for a caller-created listener, including Unix sockets or custom transports. The greeting host uses it to print the actual address when -listen 127.0.0.1:0 chooses an ephemeral port. Once accepted, gRPC closes the listener when serving returns; rejected startup leaves it untouched. Serve has no managed default timeout. Its caller coordinates shutdown and awaits Shutdown before releasing the runtime.

Connect with the CLI

Ferret CLI v2.0.0-alpha.48 can execute source, open a REPL, debug a local FQL file, and report this host’s version. This example uses the consumable-output framing required by that CLI release. See the CLI Wire guide for the current compatibility requirements and separate CLI development host.

These commands use this example’s app::greet function, not the CLI development host’s DEMO::IDENTITY:

terminal
ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:50051 --eval 'RETURN app::greet(@name)' --param name=Adaferret repl --runtime wire --runtime-endpoint tcp://127.0.0.1:50051ferret version --runtime wire --runtime-endpoint tcp://127.0.0.1:50051

The CLI uses the host’s functions, modules, policies, and filesystem configuration. For an interactive walkthrough using this host’s greeting function, see Debug on a Wire host. Compiled artifacts require the builtin CLI runtime. The CLI Wire guide covers its loopback-only endpoint syntax, timeout, compatibility, diagnostics, and ownership.

What crosses the remote boundary

Registered functions and modules, host services, and runtime configuration stay on the host. Wire does not construct that runtime or transfer its configuration to the client.

Portable interfaces do not make every Go value transportable. Wire parameters support null, booleans, signed integers, unsigned integers that fit in int64, finite floats, strings, bytes, []any, and map[string]any. Arbitrary Go functions, native host objects, datetime, duration, and regexp values cannot be sent as parameters. See the client’s parameter rules for conversion details and limits.

The host selects an available encoder, and Wire preserves its bytes without decoding them. output.Metadata() describes the complete representation and remains readable after closure. output.Collect(ctx) returns detached *api.Content: inspect content.Metadata.ContentType and content.Data. Nil content means absent output; a non-nil content value may contain zero bytes. Returning encoded data does not transfer a live host object or its capabilities.

Consume output and observe completion

A Run error is an admission or preparation failure and returns no usable handle. After successful preparation, execution, encoding, delivery, and output-owned cleanup failures are reported by Collect or Consume. Collection may return received content alongside an error; inspect both. Keep the invocation context alive until output is settled. A consumption context may shorten that lifetime, but cannot extend it.

Use Collect for small results you need to retain. To forward bytes without materializing the entire response, use this compiled example:

streaming/query.go
read-only
package streaming import ( "context" "errors" "io" "github.com/MontFerret/api" ) // WriteQuery borrows remote and destination. The invocation context stays live // through consumption; output cleanup finishes before the function returns. func WriteQuery(ctx context.Context, remote api.Runtime, source api.Source, destination io.Writer, options ...api.SessionOption) (err error) { output, err := remote.Run(ctx, source, options...) if err != nil { return err } defer func() { err = errors.Join(err, output.Close()) }() return output.Consume(ctx, func(ctx context.Context, chunk []byte) error { if err := ctx.Err(); err != nil { return err } n, err := destination.Write(chunk) if err == nil && n != len(chunk) { err = io.ErrShortWrite } return err }) }

Consume supplies borrowed chunks synchronously with backpressure. Chunk boundaries may split encoded values or UTF-8 characters; copy bytes you retain after the callback. The writer must return promptly and honor any cancellation policy it needs. Callbacks must not call Close on their own output because closure waits for the callback. For side-effect-only queries, consume with a callback that discards bytes so terminal failures are still observed.

After consumption starts, both terminal operations finalize output-owned resources, including on failure. Close abandons unread output without draining it and does not certify successful execution. Close each output before reusing its durable session, and retain cleanup errors.

Wire’s default inbound and outbound limits are 4 MiB per gRPC message, including framing. Large results are split across messages; Wire imposes no aggregate output-size cap. Collect materializes received bytes, and debugger output is materialized on both sides. Hosts and consumers must budget for total result sizes. Chunked delivery does not imply that the hosted engine evaluates or encodes queries incrementally.

Wire or Worker?

Use Worker when you want to deploy the HTTP execution service with its supported runtime configuration and service controls.

Use Wire when your application already owns a configured runtime and needs to expose compilation, execution, and debugging through the Universal API. Wire is an integration library and protocol around that runtime. Your application owns the endpoint and deployment concerns.

Debug a hosted script

Wire supports the Universal API debugging path: compile with remote.CompileDebug, then create a debugger with plan.NewDebugSession. The returned debugger session supports entry stops, breakpoints, stepping, inspection, and evaluation through the hosted implementation. Close the debugger and plan when finished.

See the Wire client debugger documentation and Universal API guide for the Wire and Native adapter contracts. The CLI connects directly. Editors that support external debugging use ferretd to launch against a named Wire runtime.

Own resources and secure the endpoint

The host owns its runtime and endpoint. Wire borrows the runtime and never closes it. Settle every output and close every plan, normal session, and debug session you create. Ordinary parent closure does not replace closing caller-owned descendants; the examples preserve cleanup errors with errors.Join.

client.New(ctx, target, options...) creates and owns a gRPC channel. Its default is TLS with system trust and normal server identity verification. client.WithInsecure() explicitly selects plaintext for this loopback demo. There is no plaintext fallback if TLS fails. Constructor cancellation controls startup only; after construction, use each operation’s context to cancel work.

Closing the remote runtime gates new root operations. Existing plans and admitted work may retain the logical connection, so the owned channel closes only after its last descendant and in-flight work finish. Settle outputs, then close sessions, plans, and the remote runtime. With client.From(ctx, conn), Wire always borrows the caller’s transport, including on failed startup: the caller closes that channel after logical resources settle.

Wire v1.0.0-alpha.5 adds the optional client.ConnectionLifetime interface to runtimes returned by both client.New and client.From. To detect a lost host, wait for ConnectionDone() to close, then read ConnectionError(). It returns nil for locally initiated teardown, client.ErrClosed for unexpected EOF, or the decoded cause for another stream failure. A retained plan can keep this signal open after Runtime.Close(). The signal marks the end of the logical connection’s reader, before final cleanup. Check errors from closing the resources you own. Wire alpha.5 client contract

Configure TLS, mTLS, or host-supplied token middleware using the Wire security examples. Server options and Run options collect validation failures before construction or listening; the security guide shows errors.As inspection and collection diagnostics. Loopback alone is not authentication or isolation between local users. Authorization and runtime capabilities remain the host’s responsibility.

Wire is pre-stable. Pin a compatible set of Core, Universal API, and Wire versions, and verify changes before upgrading. The ferret.wire.v1 protobuf package name does not guarantee a stable public release.

Next steps