explorerapi

Documentation

Overview

Package explorerapi compiles closed Explorer projections and serves the bounded read-only query contract shared by HTTP, static export, and MCP.

Index

• Constants
• func AllowedHostsForListener(address string) ([]string, error)
• func Compile(ctx context.Context, index catalog.Index, mode explorercontract.ProjectionMode, ...) (explorercontract.Dataset, error)
• func NewHandler(service *Service, config HandlerConfig) (http.Handler, error)
• func RunServer(ctx context.Context, config ServerConfig) error
• func ValidateListenAddress(ctx context.Context, address string) error
• type GraphOptions
• type HandlerConfig
• type ListOptions
• type QueryError
  • func (e *QueryError) Error() string
• type Ready
• type SearchOptions
• type ServerConfig
• type Service
  • func NewService(dataset explorercontract.Dataset) (*Service, error)
  • func (s *Service) Dataset() explorercontract.Dataset
  • func (s *Service) EntityDetail(id string, edgeLimit int) (explorercontract.EntityDetail, explorercontract.Meta, error)
  • func (s *Service) Graph(options GraphOptions) (explorercontract.GraphPage, explorercontract.Meta, error)
  • func (s *Service) Health(severity explorercontract.HealthSeverity, limit int) (explorercontract.HealthReport, explorercontract.Meta, error)
  • func (s *Service) List(options ListOptions) (explorercontract.EntityPage, explorercontract.Meta, error)
  • func (s *Service) Search(options SearchOptions) (explorercontract.SearchPage, explorercontract.Meta, error)
  • func (s *Service) Status(productVersion string) explorercontract.Status

Constants

const (
	// MaxGraphNodes is the largest node set that one service response can carry.
	MaxGraphNodes = 500
	// MaxGraphEdges is the largest edge set that one service response can carry.
	MaxGraphEdges = 1500
	// MaxGraphDepth is the largest supported neighborhood traversal depth.
	MaxGraphDepth = 2
)

Functions

func AllowedHostsForListener

func AllowedHostsForListener(address string) ([]string, error)

AllowedHostsForListener returns exact Host values for one selected loopback listener.

func Compile

func Compile(ctx context.Context, index catalog.Index, mode explorercontract.ProjectionMode, policy catalog.ProjectionPolicy) (explorercontract.Dataset, error)

Compile creates the one closed dataset consumed by every Explorer transport.

func NewHandler

func NewHandler(service *Service, config HandlerConfig) (http.Handler, error)

NewHandler returns a Host-locked read-only Explorer handler.

func RunServer

func RunServer(ctx context.Context, config ServerConfig) error

RunServer serves until ctx is canceled and then drains active reads.

func ValidateListenAddress

func ValidateListenAddress(ctx context.Context, address string) error

ValidateListenAddress rejects every non-loopback address before Listen.

Types

type GraphOptions

type GraphOptions struct {
	Mode               explorercontract.GraphMode
	GroupBy            explorercontract.GraphGroup
	Group              string
	Entity             string
	Depth              int
	MaxNodes, MaxEdges int
}

GraphOptions defines one bounded aggregate, region, or neighborhood graph.

type HandlerConfig

type HandlerConfig struct {
	ProductVersion string
	AllowedHosts   []string
	Web            http.Handler
}

HandlerConfig defines the immutable inputs for one Explorer HTTP handler.

type ListOptions

type ListOptions struct {
	Query                   string
	Kinds, Statuses         []string
	Surfaces, Tags          []string
	Limit                   int
	Cursor, Sort, Direction string
}

ListOptions defines bounded filters, ordering, and pagination for List.

type QueryError

type QueryError struct {
	Code    string
	Summary string
	Status  int
}

QueryError is a stable transport-safe service failure.

func (*QueryError) Error

func (e *QueryError) Error() string

type Ready

type Ready struct {
	URL     string
	Receipt explorercontract.ServeReceipt
}

Ready describes the bound loopback server after it can accept requests.

type SearchOptions

type SearchOptions struct {
	Query           string
	Kinds, Statuses []string
	Surfaces, Tags  []string
	Limit           int
}

SearchOptions defines bounded filters and pagination for Search.

type ServerConfig

type ServerConfig struct {
	Listen         string
	ProductVersion string
	Service        *Service
	Web            http.Handler
	OnReady        func(Ready) error
}

ServerConfig defines the loopback listener and read-only Explorer handler.

type Service

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

Service provides bounded deterministic reads over one immutable projection.

func NewService

func NewService(dataset explorercontract.Dataset) (*Service, error)

NewService builds read indexes from projected fields only.

func (*Service) Dataset

func (s *Service) Dataset() explorercontract.Dataset

Dataset returns the immutable projection that backs this service.

func (*Service) EntityDetail

func (s *Service) EntityDetail(id string, edgeLimit int) (explorercontract.EntityDetail, explorercontract.Meta, error)

EntityDetail returns one entity and its bounded direct relationships.

func (*Service) Graph

func (s *Service) Graph(options GraphOptions) (explorercontract.GraphPage, explorercontract.Meta, error)

Graph returns a deterministic progressive graph at the requested level.

func (*Service) Health

func (s *Service) Health(severity explorercontract.HealthSeverity, limit int) (explorercontract.HealthReport, explorercontract.Meta, error)

Health returns bounded redacted findings for the immutable projection.

func (*Service) List

func (s *Service) List(options ListOptions) (explorercontract.EntityPage, explorercontract.Meta, error)

List returns one deterministic page of projected entities.

func (*Service) Search

func (s *Service) Search(options SearchOptions) (explorercontract.SearchPage, explorercontract.Meta, error)

Search returns one deterministic BM25-ranked page from projected fields.

func (*Service) Status

func (s *Service) Status(productVersion string) explorercontract.Status

Status returns bounded build and corpus counts for the current projection.