lookup

Documentation

Overview

Package lookup asks an overlay host a BRC-24 question and returns its output-list answer. The question itself (which service, what query) is the caller's.

It is plain net/http over hostset on purpose. go-sdk ships a lookup.LookupResolver, and it is not used here because, unconfigured, it runs SLAP discovery against hard-coded public trackers; a client that dialed the public internet to find a host the domain already named would break BRC-180's "contact no host the user did not name". The host to ask is the one the caller names, from a manifest or its own configuration, and the only open question is which of its addresses answers, which is hostset's job.

The answer shape is the one the TypeScript overlay host actually emits, pinned by a captured fixture rather than by the SDK's types: it encodes beef as a JSON array of numbers, where the SDK's OutputListItem expects base64. Output accepts both.

Index

• Constants
• Variables
• type Answer
• type HostAnswer
  • func Query(ctx context.Context, hs *hostset.Client, base string, q Question) ([]HostAnswer, error)
• type Output
  • func (o *Output) UnmarshalJSON(b []byte) error
• type Question

Constants

const TypeOutputList = "output-list"

TypeOutputList is the one answer type Query accepts.

Variables

var ErrNotOutputList = errors.New("lookup: answer is not an output-list")

ErrNotOutputList refuses an answer of any other type.

Types

type Answer

type Answer struct {
	Type    string   `json:"type"`
	Outputs []Output `json:"outputs"`
}

Answer is a BRC-24 lookup answer.

type HostAnswer

type HostAnswer struct {
	Host   hostset.Host
	Answer Answer
}

HostAnswer is one host's answer, kept with the host so the caller can name the replica that disagreed.

func Query

func Query(ctx context.Context, hs *hostset.Client, base string, q Question) ([]HostAnswer, error)

Query POSTs q to <base>/lookup on the hosts hs selects and decodes each answer. Every host that answered must have answered 200 with an output-list; one that answered anything else is an error naming it, not a skipped host, because hostset has already decided that host was up and the caller must not quietly lose an opinion it asked for.

A nil hs asks the addresses the base URL's name resolves to, first success wins.

type Output

type Output struct {
	Beef        []byte
	OutputIndex uint32
	Context     []byte
}

Output is one item of an output-list answer.

func (*Output) UnmarshalJSON

func (o *Output) UnmarshalJSON(b []byte) error

UnmarshalJSON accepts beef and context as either a JSON array of byte values (what the TypeScript host serialises a number[] to) or a base64 string (what encoding/json and go-sdk produce for []byte). Refusing either form would refuse a conforming host; the fixture test proves the array form is the live one.

type Question

type Question struct {
	Service string `json:"service"`
	Query   any    `json:"query"`
}

Question is the body of POST /lookup. Query is marshalled as it is, so its JSON shape is whatever the lookup service parses.