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 ¶
- type Client
- func (c *Client) Entities(ctx context.Context, ids []string) (fusion.Hydration, error)
- func (c *Client) Entity(ctx context.Context, id string) (*fusion.Entity, error)
- func (c *Client) Names(ctx context.Context, query string, limit int) ([]string, error)
- func (c *Client) Neighbors(ctx context.Context, id string, predicates []string, dir fusion.Direction) ([]fusion.Edge, error)
- func (c *Client) Resolve(ctx context.Context, q fusion.ResolveQuery) (fusion.Resolution, error)
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
func (c *Client) Resolve(ctx context.Context, q fusion.ResolveQuery) (fusion.Resolution, error)
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).