Skip to main content
Version: 0.4.x(Latest)

Overview​

services.Route() reads dynamic route metadata attached to the current request. Source plugins access it through services.Route(), while dynamic plugins declare service: route in plugin.yaml and access it via pluginbridge.Default().Route(). This service primarily supports host audit, operation logging, or source plugin context enrichment when handling dynamic plugin requests.

Source plugins do not need RouteService to register their own routes; route registration is done through pluginhost.Declarations.HTTP().RegisterRoutes.

Capability Phase: Runtime

Supported Types: Source plugins, dynamic plugins

Capability Design​

Metadata View Model​

DynamicRouteMetadata is a read-only view attached to the current request, containing full descriptive information about a dynamic route:

FieldDescription
PluginIDThe plugin ID that owns the current dynamic route
MethodThe HTTP method declared by the dynamic route
PublicPathThe path exposed and matched by the host
TagsTags declared by the dynamic route
SummarySummary declared by the dynamic route
MetaPlugin-defined custom route metadata
ResponseBodyThe raw response body captured by the dispatcher
ResponseContentTypeThe response content type

Route Dispatch Flow​

Read-only Data Semantics​

Callers cannot modify dynamic routes or responses through this service. Non-dynamic routes return nil; callers should perform a nil check before use. ResponseBody depends on runtime capture results and should not be treated as an authoritative source of business data.

Interface Definitions​

Source Plugin Interface​

MethodDescription
DynamicRouteMetadataReads dynamic route metadata from context.Context; returns nil for non-dynamic routes

Dynamic Plugin Interface​

Dynamic plugins declare authorized methods through hostServices.route:

Dynamic MethodDescription
metadata.getReads dynamic route metadata attached to the current request

Usage​

Source Plugin Usage​

Source plugins read dynamic route metadata through services.Route(), with typical scenarios including audit logging and operation recording:

// Read dynamic route metadata
meta := services.Route().DynamicRouteMetadata(ctx)
if meta != nil {
    // Record audit log
    log.Infof("Dynamic plugin %s route %s %s was accessed", meta.PluginID, meta.Method, meta.PublicPath)
}

Source plugins register their own routes using pluginhost.Declarations.HTTP().RegisterRoutes:

plugin := pluginhost.NewDeclarations("my-author-my-domain-my-cap")
err := plugin.HTTP().RegisterRoutes(
    pluginhost.ExtensionPointHTTPRouteRegister,
    pluginhost.CallbackExecutionModeBlocking,
    registerRoutes,
)

Dynamic Plugin Usage​

Dynamic plugins declare the route service in plugin.yaml:

hostServices:
  - service: route
    methods:
      - metadata.get

Dynamic plugins call through pluginbridge.Default().Route():

routeSvc := pluginbridge.Default().Route()
meta := routeSvc.DynamicRouteMetadata(ctx)

Design Constraints​

  • Read-only data. Callers cannot modify dynamic routes or responses through this service.
  • Non-dynamic routes return nil. Callers should perform a nil check before use.
  • Response body may be empty. ResponseBody depends on runtime capture results and should not be treated as an authoritative source of business data.
  • Dynamic plugins read the request envelope directly. Route information within dynamic plugins comes from BridgeRequestEnvelopeV1.Route, not from calling RouteService through hostServices.