Documentation
¶
Overview ¶
Package registry stores metadata about every endpoint a nexus app exposes. It is the source of truth the dashboard reads from.
Index ¶
- type Endpoint
- type GraphQLArg
- type GraphQLUpdate
- type GraphQLValidator
- type RateLimitInfo
- type Registry
- func (r *Registry) AttachResource(serviceName, resourceName string)
- func (r *Registry) DefaultOfKind(kind resource.Kind) resource.Resource
- func (r *Registry) Endpoints() []Endpoint
- func (r *Registry) EndpointsByService(name string) []Endpoint
- func (r *Registry) EnsureMiddleware(name string)
- func (r *Registry) FindResource(name string) resource.Resource
- func (r *Registry) GetService(name string) (Service, bool)
- func (r *Registry) GlobalMiddlewares() []string
- func (r *Registry) Middlewares() []middleware.Info
- func (r *Registry) RegisterEndpoint(e Endpoint)
- func (r *Registry) RegisterGlobalMiddleware(name string)
- func (r *Registry) RegisterMiddleware(m middleware.Info)
- func (r *Registry) RegisterResource(res resource.Resource)
- func (r *Registry) RegisterService(s Service)
- func (r *Registry) RegisterWorker(w Worker)
- func (r *Registry) Resources() []ResourceSnapshot
- func (r *Registry) Services() []Service
- func (r *Registry) SetEndpointDeployment(service, name, deployment string)
- func (r *Registry) SetEndpointMiddlewares(service string, transport Transport, names []string)
- func (r *Registry) SetEndpointModule(service, name, module string)
- func (r *Registry) SetEndpointRateLimit(service, name string, info RateLimitInfo)
- func (r *Registry) SetEndpointResources(service, name string, resources []string)
- func (r *Registry) SetEndpointServiceAutoRouted(service, name string)
- func (r *Registry) SetEndpointServiceDeps(service, name string, services []string)
- func (r *Registry) SetServiceDeps(name string, resourceDeps, serviceDeps []string)
- func (r *Registry) UpdateGraphQLEndpoint(service, name string, u GraphQLUpdate)
- func (r *Registry) UpdateWorkerStatus(name, status, lastError string)
- func (r *Registry) Workers() []Worker
- type ResourceSnapshot
- type Service
- type Transport
- type Worker
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"`
// Deployment is the nexus.DeployAs(tag) marker on the enclosing
// module — it names the unit a future split would peel off. Empty
// for modules that are always local. Surfaces on the dashboard so
// readers can see which endpoints belong to a planned (or current)
// deployment unit.
Deployment 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 (*Registry) AttachResource ¶
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 ¶
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) EndpointsByService ¶
func (*Registry) EnsureMiddleware ¶
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 ¶
FindResource looks a resource up by name. Returns nil if unknown.
func (*Registry) GetService ¶ added in v0.15.0
GetService returns the registered service entry for name, or (zero, false) when no service of that name exists yet. Used by the framework's cross-module-dep merge path to read-modify-write ServiceDeps without losing existing fields.
func (*Registry) GlobalMiddlewares ¶ added in v0.3.0
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 (*Registry) RegisterGlobalMiddleware ¶ added in v0.3.0
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 ¶
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 (*Registry) RegisterWorker ¶ added in v0.7.0
RegisterWorker records a new worker entry. If a worker with the same name already exists, its metadata (deps, description) is preserved but its Status is reset — typically called when fx constructs a new instance on app restart within a test.
func (*Registry) Resources ¶
func (r *Registry) Resources() []ResourceSnapshot
Resources returns a fresh snapshot with health probed right now.
func (*Registry) SetEndpointDeployment ¶ added in v0.9.0
SetEndpointDeployment records the nexus.DeployAs tag for an endpoint. Called by the auto-mount path (GraphQL) — REST/WS invokes stamp the field directly at RegisterEndpoint time. Empty tag is a no-op.
func (*Registry) SetEndpointMiddlewares ¶
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
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
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
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
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) SetServiceDeps ¶ added in v0.6.0
SetServiceDeps records the resource + service dependencies of a service's constructor. Called by nexus.ProvideService after fx has resolved the constructor's params, so we know which resources (NexusResourceProvider) and services (service-wrapper types) were injected. Replaces any previously-recorded deps for the service.
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).
func (*Registry) UpdateWorkerStatus ¶ added in v0.7.0
UpdateWorkerStatus sets a worker's Status and optional LastError. Timestamps (StartedAt / StoppedAt) are filled in based on status transitions so the dashboard can surface runtime durations.
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
// Deployment carries the DeployAs tag of the module that owns this
// service (if any). When the service has no owning module — or
// the module isn't tagged — this is empty.
Deployment string `json:",omitempty"`
// Remote marks a service that lives in a different deployment
// unit. Set by the shadow generator's RemoteService option so
// the dashboard can render peer services distinctively (a
// "remote" badge, ghosted card style) rather than mixing them
// with the locally-owned services.
Remote bool `json:",omitempty"`
// ResourceDeps is the set of resource names the service's
// CONSTRUCTOR depends on — i.e. NewXService(app, db *DBManager,
// ...) records "db"'s NexusResources here. These drive
// service-level architecture edges (service → resource) in the
// dashboard, separate from per-endpoint edges which come from
// each handler's own deps.
ResourceDeps []string `json:",omitempty"`
// ServiceDeps is the set of OTHER service names the constructor
// depends on — detected when the constructor takes another
// service wrapper as a parameter. Renders as service → service
// edges on the architecture graph.
ServiceDeps []string `json:",omitempty"`
}
type Worker ¶ added in v0.7.0
type Worker struct {
Name string
Status string // "starting" | "running" | "stopped" | "failed"
Description string `json:",omitempty"`
StartedAt time.Time
StoppedAt time.Time `json:",omitempty"`
LastError string `json:",omitempty"`
ResourceDeps []string `json:",omitempty"`
ServiceDeps []string `json:",omitempty"`
}
Worker describes a long-lived background task registered via nexus.AsWorker. The Dashboard renders workers as a separate node kind on the architecture view — like a service, they have resource/service deps (inferred from the worker func's params), but they don't handle HTTP traffic. Status reflects the current lifecycle stage; LastError carries the message from a panic or a non-nil error return.
Source Files