registry

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package registry stores metadata about every endpoint a nexus app exposes. It is the source of truth the dashboard reads from.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Endpoint 

type Endpoint struct {
	Service string
	// Module is the nexus.Module("name", ...) this endpoint was declared
	// inside. Empty when registered outside any module (top-level opt to
	// Run/New). Drives the architecture-view grouping: module containers
	// enclose their endpoints; services are depicted as separate dep
	// nodes the endpoints connect to.
	Module       string `json:",omitempty"`
	Name         string
	Transport    Transport
	Method       string // REST verb; GraphQL "query"/"mutation"/"subscription"; unused for WS
	Path         string // REST/WS path; for GraphQL this is the mount path (e.g. "/graphql")
	Description  string
	Middleware   []string
	Tags         map[string]string
	RegisteredAt time.Time

	// Resources is the list of named resources this endpoint touches,
	// derived at mount time from the handler's dep list (each dep that
	// implements NexusResourceProvider contributes its NexusResources()
	// entries). Surfaces on the dashboard as per-op chips so a reader
	// can see, for each resolver, exactly which DB/cache/queue it hits
	// without tracing through Go code.
	Resources []string `json:",omitempty"`

	// ServiceDeps is the list of OTHER services this endpoint calls into,
	// derived from any handler dep that unwraps to a *Service (e.g. a
	// *UsersService embedded wrapper). Drives per-op service→service
	// edges on the dashboard. The owning service itself is excluded —
	// no self-loops.
	ServiceDeps []string `json:",omitempty"`

	// ServiceAutoRouted is true when the handler didn't explicitly name
	// its owning service (no service-wrapper dep, no OnService option)
	// and the auto-mount adopted it into the app's single service at
	// startup. The dashboard renders an owner chip on rows where this is
	// true so readers can tell implicit placement from explicit.
	ServiceAutoRouted bool `json:",omitempty"`

	// RateLimit is the declared rate limit for this endpoint, if any.
	// Dashboard surfaces RPM/burst/per-IP as a chip; operators can
	// override the effective limit live via /__nexus/ratelimits.
	RateLimit *RateLimitInfo `json:",omitempty"`

	// GraphQL-specific metadata, populated when Transport == GraphQL.
	Args       []GraphQLArg `json:",omitempty"`
	ReturnType string       `json:",omitempty"`

	// Deprecation flows from graph.WithDeprecated on the underlying resolver.
	Deprecated        bool   `json:",omitempty"`
	DeprecationReason string `json:",omitempty"`
}

type GraphQLArg 

type GraphQLArg struct {
	Name        string
	Type        string             // SDL-style, e.g. "String!", "[Int]", "UUID"
	Description string             `json:",omitempty"`
	Required    bool               `json:",omitempty"`
	Default     any                `json:"Default,omitempty"`
	Validators  []GraphQLValidator `json:",omitempty"`
}

GraphQLArg describes one argument on a GraphQL field. Used by the dashboard to pre-fill the tester's query template with typed variables and render validator chips.

type GraphQLUpdate 

type GraphQLUpdate struct {
	Description       string
	ReturnType        string
	Args              []GraphQLArg
	Middleware        []string
	Deprecated        bool
	DeprecationReason string
}

GraphQLUpdate is the patch graphfx applies to an endpoint after it has introspected the go-graph resolver. Only fields set on the update overwrite the endpoint; others are preserved.

type GraphQLValidator 

type GraphQLValidator struct {
	Kind    string
	Message string `json:",omitempty"`
	Details any    `json:",omitempty"`
}

GraphQLValidator mirrors graph.ValidatorInfo — what kind of rule applies, the user-facing message, and any parameters (e.g. min/max for length).

type RateLimitInfo added in v0.3.0 

type RateLimitInfo struct {
	RPM        int  `json:"rpm"`
	Burst      int  `json:"burst,omitempty"`
	PerIP      bool `json:"perIP,omitempty"`
	Overridden bool `json:"overridden,omitempty"`
}

RateLimitInfo is the registry-serializable shape of a rate limit for dashboard display. Mirrors ratelimit.Limit but JSON-tagged for the UI plus an Overridden flag so a single GET can surface both "what the code says" and "what the operator tuned it to."

type Registry 

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

func New 

func New() *Registry

func (*Registry) AttachResource 

func (r *Registry) AttachResource(serviceName, resourceName string)

AttachResource links a resource to a service. The dashboard draws an edge service → resource. Multiple services may attach to the same resource.

func (*Registry) DefaultOfKind 

func (r *Registry) DefaultOfKind(kind resource.Kind) resource.Resource

DefaultOfKind returns the resource marked resource.AsDefault() for the kind, or — if none is marked — the lexically-first registered resource of that kind. Returns nil when no resources of the kind exist.

func (*Registry) Endpoints 

func (r *Registry) Endpoints() []Endpoint

func (*Registry) EndpointsByService 

func (r *Registry) EndpointsByService(name string) []Endpoint

func (*Registry) EnsureMiddleware 

func (r *Registry) EnsureMiddleware(name string)

EnsureMiddleware registers an unknown name as a Custom middleware. Builders call this whenever .Use("name", fn) runs so the dashboard surfaces every middleware name the app references, even those the user never declared explicitly. Does nothing when the name already exists (preserves builtin).

func (*Registry) FindResource 

func (r *Registry) FindResource(name string) resource.Resource

FindResource looks a resource up by name. Returns nil if unknown.

func (*Registry) GlobalMiddlewares added in v0.3.0 

func (r *Registry) GlobalMiddlewares() []string

GlobalMiddlewares returns the ordered list of global middleware names. Dashboard reads this to render the top-of-canvas strip.

func (*Registry) Middlewares 

func (r *Registry) Middlewares() []middleware.Info

Middlewares returns the middleware metadata snapshot, sorted by name.

func (*Registry) RegisterEndpoint 

func (r *Registry) RegisterEndpoint(e Endpoint)

func (*Registry) RegisterGlobalMiddleware added in v0.3.0 

func (r *Registry) RegisterGlobalMiddleware(name string)

RegisterGlobalMiddleware marks name as installed at engine root. Order matters — same order as Config.GlobalMiddleware + built-in extras — so the dashboard strip reads left-to-right as the request encounters them. Safe to call multiple times with the same name; later calls become no-ops.

func (*Registry) RegisterMiddleware 

func (r *Registry) RegisterMiddleware(m middleware.Info)

RegisterMiddleware adds or overwrites a middleware entry. Safe to call at any time; the dashboard reflects the latest on its next poll.

func (*Registry) RegisterResource 

func (r *Registry) RegisterResource(res resource.Resource)

RegisterResource adds a resource to the registry. Safe to call multiple times with the same resource — later calls overwrite earlier ones.

func (*Registry) RegisterService 

func (r *Registry) RegisterService(s Service)

func (*Registry) Resources 

func (r *Registry) Resources() []ResourceSnapshot

Resources returns a fresh snapshot with health probed right now.

func (*Registry) Services 

func (r *Registry) Services() []Service

func (*Registry) SetEndpointMiddlewares 

func (r *Registry) SetEndpointMiddlewares(service string, transport Transport, names []string)

SetEndpointMiddlewares applies a middleware chain to every registered endpoint matching (service, transport). Used by graphfx to tag a whole GraphQL mount with the middleware that actually applied inside go-graph.

func (*Registry) SetEndpointModule added in v0.4.0 

func (r *Registry) SetEndpointModule(service, name, module string)

SetEndpointModule records the nexus.Module name this endpoint was declared inside. Called by the auto-mount (GraphQL) and by the REST invoke path after an endpoint is registered. A later call overwrites an earlier one so nested Module(...) wrappers resolve innermost-wins.

func (*Registry) SetEndpointRateLimit added in v0.3.0 

func (r *Registry) SetEndpointRateLimit(service, name string, info RateLimitInfo)

SetEndpointRateLimit attaches rate-limit info to an endpoint. Called after mount when an op declared RateLimit(...); subsequent dashboard overrides are reflected separately via the ratelimit.Store snapshot.

func (*Registry) SetEndpointResources added in v0.3.0 

func (r *Registry) SetEndpointResources(service, name string, resources []string)

SetEndpointResources records the resources a specific endpoint touches. Dedupes and sorts so chip rendering is deterministic. Match is on (service, name) — unique per GraphQL op, and per method+path for REST.

func (*Registry) SetEndpointServiceAutoRouted added in v0.3.0 

func (r *Registry) SetEndpointServiceAutoRouted(service, name string)

SetEndpointServiceAutoRouted flags an endpoint as having been auto-adopted into its service by the auto-mount (the handler didn't declare the owning service). Dashboard uses it to render an owner chip only on implicitly-routed rows.

func (*Registry) SetEndpointServiceDeps added in v0.3.0 

func (r *Registry) SetEndpointServiceDeps(service, name string, services []string)

SetEndpointServiceDeps records the OTHER services this endpoint calls into. Shape-parallel with SetEndpointResources so the dashboard can draw per-op edges to services the same way it draws resource edges.

func (*Registry) UpdateGraphQLEndpoint 

func (r *Registry) UpdateGraphQLEndpoint(service, name string, u GraphQLUpdate)

UpdateGraphQLEndpoint patches an existing GraphQL endpoint with richer metadata from go-graph introspection. Non-empty fields on the update overwrite the endpoint; empty fields are left alone (so a follow-up call only carrying middleware names won't wipe previously-set args).

type ResourceSnapshot 

type ResourceSnapshot struct {
	Name        string         `json:"name"`
	Kind        resource.Kind  `json:"kind"`
	Description string         `json:"description,omitempty"`
	Healthy     bool           `json:"healthy"`
	Details     map[string]any `json:"details,omitempty"`
	AttachedTo  []string       `json:"attachedTo,omitempty"`
}

ResourceSnapshot is the serializable view of a resource at a point in time. The dashboard polls this via /__nexus/resources — healthy is probed fresh on every snapshot so the UI reflects live state.

type Service 

type Service struct {
	Name        string
	Description string
}

type Transport 

type Transport string
const (
	REST      Transport = "rest"
	GraphQL   Transport = "graphql"
	WebSocket Transport = "websocket"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.