fusionnats

package
v0.1.0-alpha.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package fusionnats is the NATS implementation of fusion.RetrievalClient (ADR-062): it maps the engine's resolve and expand calls onto graph-query's public verbs, so the fusion engine can run against a live graph.

It is a subpackage of pkg/fusion so that fusion itself imports no NATS client and stays testable without a live graph. This package is where the engine meets the wire: it takes a classified requester (*natsclient.Client is one) and the request and reply types declared in graph, and returns fusion's types.

Each method uses one graph-query verb, whose subject is read from graph.QueryVerbs() when the client is built:

Resolve (symbol)  byName
Resolve (prefix)  prefix
Resolve (nl)      semantic
Entity            entity
Entities          batch
Neighbors         relationships
Names             byName (the matched names, for did_you_mean)

A reply is decoded as its verb's table row declares: an enveloped row's reply is a graph.QueryResponse and is refused when it names no producer; a bare row's reply is the row's type. Nothing decides a reply's shape from its content.

Every call uses RequestClassified, so a handler's refusal arrives as a *errs.ClassifiedError with its class and code (ADR-060). Entity reads the code entity_not_found as absence, (nil, nil); every other error is returned, so the engine never reads a backend fault as a missing entity.

The client starts nothing and reads no readiness status: a read whose index is not ready is refused with code index_not_ready, which the engine reads from the reply (ADR-109 D1, D3).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

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

Client is the NATS implementation of fusion.RetrievalClient. It holds no goroutine, watch or lock, so every method is safe to call from any goroutine. Build it with New.

func New

func New(nats requester, timeout time.Duration) (*Client, error)

New builds a retrieval client over nats, sending each request with timeout. It refuses a nil requester and a negative timeout; a zero timeout is passed to the requester, which applies its default (natsclient's DefaultRequestTimeout). A typed-nil pointer is not detected.

func (*Client) Entities

func (c *Client) Entities(ctx context.Context, ids []string) (fusion.Hydration, error)

Entities reads the entities ids names through batch, then reconciles the reply with the request: every distinct requested ID is accounted for once, in Entities in request order or in Unhydrated with a reason. Zero IDs send no request. A non-nil error is a backend failure, which the engine tells apart from an entity that is simply absent.

The batch's responder answers cache hits first, and the engine ranks by position, so request order is restored here, where it is still known; and an ID the reply lists nowhere is unhydrated unknown, never not_found (reconcileHydration).

The batch's responder refuses the whole batch with code graph_state_reset_required when one stored entity is poisoned, naming it only in text (pin ADR-079 D3). On that refusal the IDs are read one at a time (entitiesAlone), so a poisoned seed is listed unhydrated error rather than failing every answer it ranks in (ADR-109 D1). A refusal from the client's own check of a reply carries the same code; it is returned and never starts that read. A nil context is refused, even for zero IDs.

func (*Client) Entity

func (c *Client) Entity(ctx context.Context, id string) (*fusion.Entity, error)

Entity returns the entity id, or (nil, nil) when the read finds none. The entity verb refuses a missing entity with code entity_not_found; that one code is read as absence, and every other error is returned, so the engine never reads a backend fault as a not-found. A stored value the stored-value rule refuses, the wrong entity included, is returned as that refusal.

func (*Client) Names

func (c *Client) Names(ctx context.Context, query string, limit int) ([]string, error)

Names suggests display names near query for a miss's did_you_mean, through byName. Entities may share a name, so names are deduplicated in rank order and capped at limit.

func (*Client) Neighbors

func (c *Client) Neighbors(ctx context.Context, id string, predicates []string, dir fusion.Direction) ([]fusion.Edge, error)

Neighbors returns the edges of id in dir along predicates through relationships. The verb answers every edge in the direction, so this keeps only the requested predicates; no predicates means every edge.

func (*Client) Resolve

Resolve maps a query to seeds by mode, most relevant first. An unknown mode is an error, never a default (ResolveMode is an open string enum).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL