1033 lines
34 KiB
Go
1033 lines
34 KiB
Go
package jsplugin
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"maps"
|
|
"net/http"
|
|
"regexp"
|
|
"slices"
|
|
"sort"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/QuantumNous/new-api/constant"
|
|
)
|
|
|
|
type RouteType string
|
|
|
|
const (
|
|
RouteTypeSubmit RouteType = "submit"
|
|
RouteTypeQuery RouteType = "query"
|
|
RouteTypeDynamic RouteType = "dynamic"
|
|
)
|
|
|
|
type Route struct {
|
|
Method string `json:"method"`
|
|
Path string `json:"path"`
|
|
Type RouteType `json:"type"`
|
|
Action string `json:"action,omitempty"`
|
|
Decode string `json:"decode,omitempty"`
|
|
Render string `json:"render,omitempty"`
|
|
TaskIDParam string `json:"taskIdParam,omitempty"`
|
|
// RetainResult, when explicitly false on a submit or dynamic route, tells
|
|
// the host not to persist the upstream snapshot of an immediate terminal
|
|
// result and to treat the task as not found on every retrieval surface
|
|
// afterwards. nil means the route did not declare it (retain).
|
|
RetainResult *bool `json:"retainResult,omitempty"`
|
|
// Models restricts this route to the listed models. The host matches the
|
|
// canonical top-level "model" body field before any JS hook runs; empty
|
|
// means unrestricted. Must be a subset of meta.models.
|
|
Models []string `json:"models,omitempty"`
|
|
}
|
|
|
|
// ProtocolClaim is one entry of meta.protocols. Models narrows the protocol's
|
|
// endpoint bindings to a subset of meta.models; empty binds every model.
|
|
// Supports names the request forms a mode-bearing protocol accepts; decode
|
|
// and normalize rewrite it into host-table order.
|
|
type ProtocolClaim struct {
|
|
Name string `json:"name"`
|
|
Models []string `json:"models,omitempty"`
|
|
Supports []string `json:"supports,omitempty"`
|
|
objectForm bool
|
|
}
|
|
|
|
// ProtocolMode is one client request form a host protocol operation accepts
|
|
// and the plugin hook that implements it.
|
|
type ProtocolMode struct {
|
|
Name string
|
|
Hook string
|
|
}
|
|
|
|
type BodyKind string
|
|
|
|
const (
|
|
BodyNone BodyKind = "none"
|
|
BodyJSON BodyKind = "json"
|
|
BodyForm BodyKind = "form"
|
|
BodyMultipart BodyKind = "multipart"
|
|
)
|
|
|
|
type HostProtocolOperation struct {
|
|
Name string
|
|
Methods []string
|
|
Path string
|
|
BodyKinds []BodyKind
|
|
ModelField string
|
|
RequiredProtocolMembers []string
|
|
Modes []ProtocolMode
|
|
RequiredDriverHooks []string
|
|
}
|
|
|
|
type HostProtocolDefinition struct {
|
|
Name string
|
|
Operations []HostProtocolOperation
|
|
}
|
|
|
|
var hostProtocols = []HostProtocolDefinition{
|
|
{Name: "openai_responses", Operations: []HostProtocolOperation{
|
|
{Name: "create", Methods: []string{http.MethodPost}, Path: "/v1/responses", BodyKinds: []BodyKind{BodyJSON}, ModelField: "model", RequiredProtocolMembers: []string{"decodeRequest"}, Modes: []ProtocolMode{{Name: "stream", Hook: "renderEvents"}, {Name: "sync", Hook: "renderFinal"}, {Name: "background", Hook: "renderFinal"}}},
|
|
{Name: "retrieve", Methods: []string{http.MethodGet}, Path: "/v1/responses/:response_id", BodyKinds: []BodyKind{BodyNone}},
|
|
}},
|
|
{Name: "openai_video", Operations: []HostProtocolOperation{
|
|
{Name: "create", Methods: []string{http.MethodPost}, Path: "/v1/videos", BodyKinds: []BodyKind{BodyJSON, BodyMultipart}, ModelField: "model", RequiredProtocolMembers: []string{"decodeRequest"}},
|
|
{Name: "retrieve", Methods: []string{http.MethodGet}, Path: "/v1/videos/:task_id", BodyKinds: []BodyKind{BodyNone}, RequiredProtocolMembers: []string{"render"}},
|
|
{Name: "content", Methods: []string{http.MethodGet, http.MethodHead}, Path: "/v1/videos/:task_id/content", BodyKinds: []BodyKind{BodyNone}, RequiredDriverHooks: []string{"listArtifacts", "buildContentRequest"}},
|
|
}},
|
|
// The OpenAI Images API is synchronous: both operations create a task and
|
|
// the host answers with the rendered image response once the task is
|
|
// terminal, so there is no retrieve operation and no request modes.
|
|
{Name: ProtocolOpenAIImage, Operations: []HostProtocolOperation{
|
|
{Name: "generate", Methods: []string{http.MethodPost}, Path: "/v1/images/generations", BodyKinds: []BodyKind{BodyJSON}, ModelField: "model", RequiredProtocolMembers: []string{"decodeRequest", "render"}},
|
|
{Name: "edit", Methods: []string{http.MethodPost}, Path: "/v1/images/edits", BodyKinds: []BodyKind{BodyJSON, BodyMultipart}, ModelField: "model", RequiredProtocolMembers: []string{"decodeRequest", "render"}},
|
|
}},
|
|
}
|
|
|
|
// ProtocolOpenAIImage is the host protocol that serves the OpenAI Images API
|
|
// (`POST /v1/images/generations` and `POST /v1/images/edits`) from a plugin.
|
|
const ProtocolOpenAIImage = "openai_image"
|
|
|
|
func HostProtocol(name string) (HostProtocolDefinition, bool) {
|
|
for _, definition := range hostProtocols {
|
|
if definition.Name == name {
|
|
return definition, true
|
|
}
|
|
}
|
|
return HostProtocolDefinition{}, false
|
|
}
|
|
|
|
func HostProtocols() []HostProtocolDefinition {
|
|
definitions := make([]HostProtocolDefinition, len(hostProtocols))
|
|
for index, definition := range hostProtocols {
|
|
definitions[index] = definition
|
|
definitions[index].Operations = append([]HostProtocolOperation(nil), definition.Operations...)
|
|
for operationIndex := range definitions[index].Operations {
|
|
operation := &definitions[index].Operations[operationIndex]
|
|
operation.Methods = append([]string(nil), operation.Methods...)
|
|
operation.BodyKinds = append([]BodyKind(nil), operation.BodyKinds...)
|
|
operation.RequiredProtocolMembers = append([]string(nil), operation.RequiredProtocolMembers...)
|
|
operation.Modes = append([]ProtocolMode(nil), operation.Modes...)
|
|
operation.RequiredDriverHooks = append([]string(nil), operation.RequiredDriverHooks...)
|
|
}
|
|
}
|
|
return definitions
|
|
}
|
|
|
|
// DefinedModes returns each distinct mode on the protocol in host-table order.
|
|
func (d HostProtocolDefinition) DefinedModes() []ProtocolMode {
|
|
seen := make(map[string]struct{})
|
|
modes := make([]ProtocolMode, 0)
|
|
for _, operation := range d.Operations {
|
|
for _, mode := range operation.Modes {
|
|
if _, exists := seen[mode.Name]; exists {
|
|
continue
|
|
}
|
|
seen[mode.Name] = struct{}{}
|
|
modes = append(modes, mode)
|
|
}
|
|
}
|
|
return modes
|
|
}
|
|
|
|
func orderProtocolSupports(protocol string, supports []string) []string {
|
|
if len(supports) == 0 {
|
|
return supports
|
|
}
|
|
definition, ok := HostProtocol(protocol)
|
|
if !ok {
|
|
return supports
|
|
}
|
|
rank := make(map[string]int)
|
|
for index, mode := range definition.DefinedModes() {
|
|
rank[mode.Name] = index
|
|
}
|
|
ordered := append([]string(nil), supports...)
|
|
slices.SortStableFunc(ordered, func(left, right string) int {
|
|
leftRank, leftKnown := rank[left]
|
|
rightRank, rightKnown := rank[right]
|
|
switch {
|
|
case leftKnown && rightKnown:
|
|
if leftRank < rightRank {
|
|
return -1
|
|
}
|
|
if leftRank > rightRank {
|
|
return 1
|
|
}
|
|
return 0
|
|
case leftKnown:
|
|
return -1
|
|
case rightKnown:
|
|
return 1
|
|
default:
|
|
return 0
|
|
}
|
|
})
|
|
return ordered
|
|
}
|
|
|
|
func LookupHostProtocolOperation(method, path string) (string, HostProtocolOperation, bool) {
|
|
method = strings.ToUpper(strings.TrimSpace(method))
|
|
for _, definition := range hostProtocols {
|
|
for _, operation := range definition.Operations {
|
|
if operation.Path != path || operation.ModelField == "" {
|
|
continue
|
|
}
|
|
if slices.Contains(operation.Methods, method) {
|
|
return definition.Name, operation, true
|
|
}
|
|
}
|
|
}
|
|
return "", HostProtocolOperation{}, false
|
|
}
|
|
|
|
type RouteBinding struct {
|
|
Plugin *LoadedPlugin
|
|
Route Route
|
|
}
|
|
|
|
type ProtocolBinding struct {
|
|
Plugin *LoadedPlugin
|
|
Protocol string
|
|
Operation HostProtocolOperation
|
|
Model string
|
|
}
|
|
|
|
const (
|
|
ContextKeyPinnedPlugin = "task_plugin_pinned_plugin"
|
|
ContextKeyPinnedRoute = "task_plugin_pinned_route"
|
|
ContextKeyPinnedEndpoint = "task_plugin_pinned_endpoint"
|
|
ContextKeyRouteRequest = "task_plugin_route_request"
|
|
ContextKeyProtocolRequest = "task_plugin_protocol_request"
|
|
// ContextKeyRequestBodyText holds, for a plugin that preserves JSON
|
|
// order, the decoded requestBody as JSON text (json.RawMessage) beside
|
|
// the Go value in task_request.
|
|
ContextKeyRequestBodyText = "task_plugin_request_body_text"
|
|
)
|
|
|
|
type PinnedPlugin struct {
|
|
Generation *RoutingGeneration
|
|
Plugin *LoadedPlugin
|
|
}
|
|
|
|
type PinnedRoute struct {
|
|
Generation *RoutingGeneration
|
|
Plugin *LoadedPlugin
|
|
Route Route
|
|
}
|
|
|
|
// PinnedEndpoint carries the exact generation and endpoint candidates selected
|
|
// before distribution. Plugin initially names the deterministic request parser;
|
|
// distribution may rebind it to another candidate from the same generation
|
|
// when multiple legacy providers expose the same model.
|
|
type PinnedEndpoint struct {
|
|
Generation *RoutingGeneration
|
|
Plugin *LoadedPlugin
|
|
Protocol string
|
|
Operation HostProtocolOperation
|
|
Model string
|
|
MappedModel string
|
|
Candidates []ProtocolBinding
|
|
}
|
|
|
|
// FileReference returns the opaque ref of the index-th uploaded file in a
|
|
// multipart field. The first file keeps the historical `request_file:<field>`
|
|
// spelling; later files in the same repeated field (`image[]`, `image[]`)
|
|
// append `#<index>` so a plugin can address each of them.
|
|
func FileReference(field string, index int) string {
|
|
if index <= 0 {
|
|
return "request_file:" + field
|
|
}
|
|
return "request_file:" + field + "#" + strconv.Itoa(index)
|
|
}
|
|
|
|
// ParseFileReference resolves a ref produced by FileReference back to the
|
|
// multipart field and the zero-based file index within that field.
|
|
func ParseFileReference(ref string) (field string, index int, ok bool) {
|
|
rest, found := strings.CutPrefix(ref, "request_file:")
|
|
if !found || rest == "" {
|
|
return "", 0, false
|
|
}
|
|
field, suffix, hasIndex := strings.Cut(rest, "#")
|
|
if field == "" {
|
|
return "", 0, false
|
|
}
|
|
if !hasIndex {
|
|
return field, 0, true
|
|
}
|
|
parsed, err := strconv.Atoi(suffix)
|
|
if err != nil || parsed < 0 || strconv.Itoa(parsed) != suffix {
|
|
return "", 0, false
|
|
}
|
|
return field, parsed, true
|
|
}
|
|
|
|
// RouteRequestContext is the canonical request view exposed to declarative
|
|
// routing hooks. RequestBody contains decoded JSON or multipart text fields;
|
|
// raw binary and multipart file bytes remain host-owned.
|
|
type RouteRequestContext struct {
|
|
Path string `json:"path"`
|
|
Method string `json:"method"`
|
|
Params map[string]string `json:"params"`
|
|
Query map[string][]string `json:"query"`
|
|
Body any `json:"body"`
|
|
Files []map[string]any `json:"-"`
|
|
RequestBody any `json:"-"`
|
|
// BodyText is the JSON body as the client sent it, which JSValueFor
|
|
// gives to plugins that preserve JSON order; Body stays the Go value the
|
|
// host reads. Body storage never changes these bytes, which the engine
|
|
// parses in place.
|
|
BodyText json.RawMessage `json:"-"`
|
|
}
|
|
|
|
// JSValue shares the request with hooks without copying it: the engine never
|
|
// writes JavaScript changes back into Go values, so the request must only stay
|
|
// unchanged while a hook runs. Missing params and query still reach hooks as
|
|
// empty objects rather than null.
|
|
func (r RouteRequestContext) JSValue() map[string]any {
|
|
params, query := r.Params, r.Query
|
|
if params == nil {
|
|
params = map[string]string{}
|
|
}
|
|
if query == nil {
|
|
query = map[string][]string{}
|
|
}
|
|
return map[string]any{
|
|
"path": r.Path,
|
|
"method": r.Method,
|
|
"params": params,
|
|
"query": query,
|
|
"body": r.Body,
|
|
}
|
|
}
|
|
|
|
// JSValueFor is JSValue for the decode hooks of the plugin meta describes. A
|
|
// plugin that preserves JSON order receives a JSON body as its text, which the
|
|
// engine parses in place, members in the client's order: a decoder reads the
|
|
// body, so it is parsed for every call.
|
|
func (r RouteRequestContext) JSValueFor(meta Meta) map[string]any {
|
|
value := r.JSValue()
|
|
if len(r.BodyText) > 0 && meta.PreservesJSONOrder() {
|
|
value["body"] = map[string]any{"kind": string(BodyJSON), "value": RawJSON(r.BodyText)}
|
|
}
|
|
return value
|
|
}
|
|
|
|
type ProtocolRequestContext struct {
|
|
RouteRequestContext
|
|
Protocol string `json:"protocol"`
|
|
Operation string `json:"operation"`
|
|
Model string `json:"model"`
|
|
// UpstreamModel is the declared machine identity when Model is a
|
|
// channel-mapping alias; empty otherwise. Decode hooks that key rate
|
|
// tables or request shaping by model must use it over Model.
|
|
UpstreamModel string `json:"upstreamModel,omitempty"`
|
|
Stream bool `json:"stream"`
|
|
}
|
|
|
|
func (p ProtocolRequestContext) JSValue() map[string]any {
|
|
return p.withProtocol(p.RouteRequestContext.JSValue())
|
|
}
|
|
|
|
// JSValueFor is RouteRequestContext.JSValueFor with the protocol fields.
|
|
func (p ProtocolRequestContext) JSValueFor(meta Meta) map[string]any {
|
|
return p.withProtocol(p.RouteRequestContext.JSValueFor(meta))
|
|
}
|
|
|
|
func (p ProtocolRequestContext) withProtocol(value map[string]any) map[string]any {
|
|
value["protocol"] = p.Protocol
|
|
value["operation"] = p.Operation
|
|
value["model"] = p.Model
|
|
if p.UpstreamModel != "" {
|
|
value["upstreamModel"] = p.UpstreamModel
|
|
}
|
|
value["stream"] = p.Stream
|
|
return value
|
|
}
|
|
|
|
// SupportsHostProtocol reports whether the current host release has a
|
|
// concrete wire/state machine for an otherwise valid manifest endpoint.
|
|
func SupportsHostProtocol(protocol string) bool { _, ok := HostProtocol(protocol); return ok }
|
|
|
|
// RoutingGeneration is an immutable, request-pinnable view of all effective
|
|
// plugins and their deterministic routing indexes.
|
|
type RoutingGeneration struct {
|
|
Number uint64
|
|
PublishedAt time.Time
|
|
|
|
byKey map[string]*LoadedPlugin
|
|
byModel map[string]*LoadedPlugin
|
|
modelPlugins map[string][]*LoadedPlugin
|
|
canonicalModelByFold map[string]string
|
|
byChannelType map[int]*LoadedPlugin
|
|
routeIndex map[string]RouteBinding
|
|
protocolIndex map[string][]ProtocolBinding
|
|
plugins []*LoadedPlugin
|
|
routes []RouteBinding
|
|
runtime http.Handler
|
|
retainCurrent map[string]struct{}
|
|
}
|
|
|
|
var (
|
|
routeMethodPattern = regexp.MustCompile(`^(GET|POST|PUT|PATCH|DELETE)$`)
|
|
pathNamePattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
|
|
staticSegment = regexp.MustCompile(`^[A-Za-z0-9._~-]+$`)
|
|
memberNamePattern = regexp.MustCompile(`^[A-Za-z_$][A-Za-z0-9_$]*$`)
|
|
)
|
|
|
|
var reservedRouteNamespaces = []string{
|
|
"/api",
|
|
"/assets",
|
|
"/setup",
|
|
"/v1/tasks",
|
|
"/console",
|
|
"/login",
|
|
"/forbidden",
|
|
"/sign-in",
|
|
"/sign-up",
|
|
"/forgot-password",
|
|
"/oauth",
|
|
"/otp",
|
|
"/register",
|
|
"/reset",
|
|
"/privacy-policy",
|
|
"/user-agreement",
|
|
"/about",
|
|
"/pricing",
|
|
"/rankings",
|
|
"/user",
|
|
"/401",
|
|
"/403",
|
|
"/404",
|
|
"/500",
|
|
"/503",
|
|
"/chat2link",
|
|
"/system-settings",
|
|
"/channels",
|
|
"/chat",
|
|
"/dashboard",
|
|
"/errors",
|
|
"/keys",
|
|
"/models",
|
|
"/playground",
|
|
"/profile",
|
|
"/redemption-codes",
|
|
"/subscriptions",
|
|
"/system-info",
|
|
"/task-plugins",
|
|
"/usage-logs",
|
|
"/users",
|
|
"/wallet",
|
|
}
|
|
|
|
func (g *RoutingGeneration) Get(key string) (*LoadedPlugin, bool) {
|
|
if g == nil {
|
|
return nil, false
|
|
}
|
|
plugin, ok := g.byKey[key]
|
|
return plugin, ok
|
|
}
|
|
|
|
func (g *RoutingGeneration) GetByChannelType(channelType int) (*LoadedPlugin, bool) {
|
|
if g == nil || channelType == 0 || channelType == constant.ChannelTypeTaskPlugin {
|
|
return nil, false
|
|
}
|
|
plugin, ok := g.byChannelType[channelType]
|
|
return plugin, ok
|
|
}
|
|
|
|
// GetByModel returns the deterministic effective plugin metadata used for a
|
|
// model-level host concern such as billing. When multiple providers expose the
|
|
// same model name, the first plugin in generation order owns that shared
|
|
// metadata view.
|
|
func (g *RoutingGeneration) GetByModel(model string) (*LoadedPlugin, bool) {
|
|
if g == nil || model == "" {
|
|
return nil, false
|
|
}
|
|
plugin, ok := g.byModel[model]
|
|
return plugin, ok
|
|
}
|
|
|
|
// PluginsByModel returns all plugins declaring model, in ascending key order.
|
|
func (g *RoutingGeneration) PluginsByModel(model string) []*LoadedPlugin {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
return slices.Clone(g.modelPlugins[model])
|
|
}
|
|
|
|
// SharedModel reports whether multiple plugins declare a model without copying
|
|
// its provider list on the relay hot path.
|
|
func (g *RoutingGeneration) SharedModel(model string) bool {
|
|
return g != nil && len(g.modelPlugins[model]) >= 2
|
|
}
|
|
|
|
// CanonicalModel returns the declared spelling for model. An exact byModel
|
|
// hit wins and returns the input unchanged; otherwise the ASCII-folded
|
|
// index is consulted. Miss and nil-receiver return ("", false).
|
|
func (g *RoutingGeneration) CanonicalModel(model string) (string, bool) {
|
|
if g == nil || model == "" {
|
|
return "", false
|
|
}
|
|
if _, ok := g.byModel[model]; ok {
|
|
return model, true
|
|
}
|
|
declared, ok := g.canonicalModelByFold[asciiFold(model)]
|
|
return declared, ok
|
|
}
|
|
|
|
// LookupDeclaredRoute resolves a manifest path declaration. It does not match
|
|
// an incoming concrete URL; runtime matching is delegated to Gin.
|
|
func (g *RoutingGeneration) LookupDeclaredRoute(method, path string) (RouteBinding, bool) {
|
|
if g == nil {
|
|
return RouteBinding{}, false
|
|
}
|
|
normalizedMethod, err := normalizeRouteMethod(method)
|
|
if err != nil {
|
|
return RouteBinding{}, false
|
|
}
|
|
shape, err := routePathShape(path)
|
|
if err != nil {
|
|
return RouteBinding{}, false
|
|
}
|
|
binding, ok := g.routeIndex[normalizedMethod+" "+shape]
|
|
return binding, ok
|
|
}
|
|
|
|
func (g *RoutingGeneration) LookupEndpoint(method, path, model string) (ProtocolBinding, bool) {
|
|
if g == nil {
|
|
return ProtocolBinding{}, false
|
|
}
|
|
normalizedMethod, err := normalizeRouteMethod(method)
|
|
if err != nil {
|
|
return ProtocolBinding{}, false
|
|
}
|
|
bindings := g.protocolIndex[endpointIndexKey(normalizedMethod, path, model)]
|
|
if len(bindings) == 0 {
|
|
return ProtocolBinding{}, false
|
|
}
|
|
return bindings[0], true
|
|
}
|
|
|
|
// LookupEndpointCandidates returns every plugin that can serve a shared model
|
|
// endpoint, in ascending key order. Each candidate decodes before distribution.
|
|
func (g *RoutingGeneration) LookupEndpointCandidates(method, path, model string) []ProtocolBinding {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
normalizedMethod, err := normalizeRouteMethod(method)
|
|
if err != nil {
|
|
return nil
|
|
}
|
|
bindings := g.protocolIndex[endpointIndexKey(normalizedMethod, path, model)]
|
|
return append([]ProtocolBinding(nil), bindings...)
|
|
}
|
|
|
|
func (g *RoutingGeneration) Plugins() []*LoadedPlugin {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
return append([]*LoadedPlugin(nil), g.plugins...)
|
|
}
|
|
|
|
func (g *RoutingGeneration) Routes() []RouteBinding {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
return append([]RouteBinding(nil), g.routes...)
|
|
}
|
|
|
|
// RuntimeHandler is the inner router built for this exact generation. It is
|
|
// published in the same atomic pointer as the routing indexes.
|
|
func (g *RoutingGeneration) RuntimeHandler() http.Handler {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
return g.runtime
|
|
}
|
|
|
|
func (g *RoutingGeneration) RetainsIncumbent(key string) bool {
|
|
if g == nil {
|
|
return false
|
|
}
|
|
_, retained := g.retainCurrent[key]
|
|
return retained
|
|
}
|
|
|
|
// RebuildWithPlugins creates a generation from the supplied exact plugin
|
|
// pointers. It is used when a rejected hot update must retain the incumbent
|
|
// runtime object for that key.
|
|
func (g *RoutingGeneration) RebuildWithPlugins(plugins []*LoadedPlugin) (*RoutingGeneration, error) {
|
|
if g == nil {
|
|
return nil, fmt.Errorf("cannot rebuild a nil routing generation")
|
|
}
|
|
byKey := make(map[string]*LoadedPlugin, len(plugins))
|
|
for _, plugin := range plugins {
|
|
if plugin == nil {
|
|
return nil, fmt.Errorf("cannot rebuild routing generation with a nil plugin")
|
|
}
|
|
if _, exists := g.byKey[plugin.Meta.Key]; !exists {
|
|
return nil, fmt.Errorf("plugin %q is not present in routing generation %d", plugin.Meta.Key, g.Number)
|
|
}
|
|
if _, duplicate := byKey[plugin.Meta.Key]; duplicate {
|
|
return nil, fmt.Errorf("plugin %q appears more than once in routing generation rebuild", plugin.Meta.Key)
|
|
}
|
|
byKey[plugin.Meta.Key] = plugin
|
|
}
|
|
rebuilt, err := buildRoutingGeneration(byKey, nil, g.Number)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
rebuilt.PublishedAt = g.PublishedAt
|
|
rebuilt.retainCurrent = cloneStringSet(g.retainCurrent)
|
|
return rebuilt, nil
|
|
}
|
|
|
|
// WithRuntime returns a shallow immutable copy carrying the prepared inner
|
|
// handler. Callers use it before publication; published generations must not
|
|
// be mutated.
|
|
func (g *RoutingGeneration) WithRuntime(handler http.Handler) *RoutingGeneration {
|
|
if g == nil {
|
|
return nil
|
|
}
|
|
prepared := *g
|
|
prepared.runtime = handler
|
|
return &prepared
|
|
}
|
|
|
|
func cloneStringSet(source map[string]struct{}) map[string]struct{} {
|
|
if len(source) == 0 {
|
|
return nil
|
|
}
|
|
clone := make(map[string]struct{}, len(source))
|
|
for key := range source {
|
|
clone[key] = struct{}{}
|
|
}
|
|
return clone
|
|
}
|
|
|
|
func normalizeRouteMethod(method string) (string, error) {
|
|
method = strings.ToUpper(strings.TrimSpace(method))
|
|
if !routeMethodPattern.MatchString(method) {
|
|
return "", fmt.Errorf("plugin route method %q is not supported", method)
|
|
}
|
|
return method, nil
|
|
}
|
|
|
|
// NormalizeRoutePath validates the canonical path syntax used by plugin route
|
|
// declarations. A trailing slash is allowed and remains significant.
|
|
func NormalizeRoutePath(routePath string) (string, error) {
|
|
if routePath == "" || routePath[0] != '/' {
|
|
return "", fmt.Errorf("plugin route path must start with /")
|
|
}
|
|
if routePath == "/" {
|
|
return "", fmt.Errorf("plugin route path / is reserved")
|
|
}
|
|
if strings.ContainsAny(routePath, "?#%") {
|
|
return "", fmt.Errorf("plugin route path %q must not contain a query, fragment, or percent-encoding", routePath)
|
|
}
|
|
if strings.Contains(routePath, "//") {
|
|
return "", fmt.Errorf("plugin route path %q must not contain empty segments", routePath)
|
|
}
|
|
|
|
segments := strings.Split(strings.TrimPrefix(routePath, "/"), "/")
|
|
seenNames := make(map[string]struct{})
|
|
for index, segment := range segments {
|
|
if segment == "" && index == len(segments)-1 {
|
|
continue
|
|
}
|
|
if segment == "." || segment == ".." {
|
|
return "", fmt.Errorf("plugin route path %q must not contain dot segments", routePath)
|
|
}
|
|
if after, ok := strings.CutPrefix(segment, ":"); ok {
|
|
name := after
|
|
if !pathNamePattern.MatchString(name) {
|
|
return "", fmt.Errorf("plugin route path %q has invalid parameter %q", routePath, segment)
|
|
}
|
|
if _, exists := seenNames[name]; exists {
|
|
return "", fmt.Errorf("plugin route path %q repeats parameter %q", routePath, name)
|
|
}
|
|
seenNames[name] = struct{}{}
|
|
continue
|
|
}
|
|
if after, ok := strings.CutPrefix(segment, "*"); ok {
|
|
name := after
|
|
if index != len(segments)-1 || !pathNamePattern.MatchString(name) {
|
|
return "", fmt.Errorf("plugin route path %q has an invalid catch-all segment", routePath)
|
|
}
|
|
if _, exists := seenNames[name]; exists {
|
|
return "", fmt.Errorf("plugin route path %q repeats parameter %q", routePath, name)
|
|
}
|
|
seenNames[name] = struct{}{}
|
|
continue
|
|
}
|
|
if !staticSegment.MatchString(segment) {
|
|
return "", fmt.Errorf("plugin route path %q has invalid segment %q", routePath, segment)
|
|
}
|
|
}
|
|
return routePath, nil
|
|
}
|
|
|
|
func routePathShape(routePath string) (string, error) {
|
|
normalized, err := NormalizeRoutePath(routePath)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
segments := strings.Split(strings.TrimPrefix(normalized, "/"), "/")
|
|
for index, segment := range segments {
|
|
if strings.HasPrefix(segment, ":") {
|
|
segments[index] = ":"
|
|
} else if strings.HasPrefix(segment, "*") {
|
|
segments[index] = "*"
|
|
}
|
|
}
|
|
return "/" + strings.Join(segments, "/"), nil
|
|
}
|
|
|
|
func endpointIndexKey(method, path, model string) string {
|
|
return method + "\x00" + path + "\x00" + model
|
|
}
|
|
|
|
func intersectingReservedNamespace(routePath string) (string, bool) {
|
|
for _, namespace := range reservedRouteNamespaces {
|
|
if routePatternIntersectsNamespace(routePath, namespace) {
|
|
return namespace, true
|
|
}
|
|
}
|
|
return "", false
|
|
}
|
|
|
|
func routePatternIntersectsNamespace(routePath, namespace string) bool {
|
|
routeSegments := strings.Split(strings.Trim(strings.TrimPrefix(routePath, "/"), "/"), "/")
|
|
namespaceSegments := strings.Split(strings.TrimPrefix(namespace, "/"), "/")
|
|
for index, namespaceSegment := range namespaceSegments {
|
|
if index >= len(routeSegments) {
|
|
return false
|
|
}
|
|
routeSegment := routeSegments[index]
|
|
if strings.HasPrefix(routeSegment, "*") {
|
|
return true
|
|
}
|
|
if !strings.HasPrefix(routeSegment, ":") && routeSegment != namespaceSegment {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
|
|
func validateRoute(route *Route) error {
|
|
if route.Method != strings.ToUpper(strings.TrimSpace(route.Method)) {
|
|
return fmt.Errorf("plugin route method %q must use canonical uppercase spelling", route.Method)
|
|
}
|
|
method, err := normalizeRouteMethod(route.Method)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
route.Method = method
|
|
route.Path, err = NormalizeRoutePath(route.Path)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if namespace, reserved := intersectingReservedNamespace(route.Path); reserved {
|
|
return fmt.Errorf("plugin route path %q intersects reserved namespace %s", route.Path, namespace)
|
|
}
|
|
switch route.Type {
|
|
case RouteTypeSubmit:
|
|
if route.Decode == "" || route.Render == "" || route.TaskIDParam != "" {
|
|
return fmt.Errorf("submit route %s %s must declare decode and render and must not declare taskIdParam", route.Method, route.Path)
|
|
}
|
|
case RouteTypeQuery:
|
|
if route.Decode != "" || strings.TrimSpace(route.Render) == "" {
|
|
return fmt.Errorf("query route %s %s must declare render and must not declare decode", route.Method, route.Path)
|
|
}
|
|
if route.Action != "" {
|
|
return fmt.Errorf("query route %s %s must not declare action", route.Method, route.Path)
|
|
}
|
|
if route.RetainResult != nil {
|
|
return fmt.Errorf("query route %s %s must not declare retainResult", route.Method, route.Path)
|
|
}
|
|
if route.TaskIDParam == "" {
|
|
route.TaskIDParam = "task_id"
|
|
}
|
|
if !pathNamePattern.MatchString(route.TaskIDParam) {
|
|
return fmt.Errorf("query route %s %s has invalid taskIdParam %q", route.Method, route.Path, route.TaskIDParam)
|
|
}
|
|
if !pathHasParameter(route.Path, route.TaskIDParam) {
|
|
return fmt.Errorf("query route %s %s must contain :%s", route.Method, route.Path, route.TaskIDParam)
|
|
}
|
|
case RouteTypeDynamic:
|
|
if route.Decode == "" || route.Render == "" || route.TaskIDParam != "" {
|
|
return fmt.Errorf("dynamic route %s %s must declare decode and render and must not declare taskIdParam", route.Method, route.Path)
|
|
}
|
|
default:
|
|
return fmt.Errorf("plugin route %s %s has unsupported type %q", route.Method, route.Path, route.Type)
|
|
}
|
|
if route.Decode != "" && !memberNamePattern.MatchString(route.Decode) {
|
|
return fmt.Errorf("plugin route %s %s has invalid decode %q", route.Method, route.Path, route.Decode)
|
|
}
|
|
if route.Render != "" && !memberNamePattern.MatchString(route.Render) {
|
|
return fmt.Errorf("plugin route %s %s has invalid render %q", route.Method, route.Path, route.Render)
|
|
}
|
|
if strings.TrimSpace(route.Action) != route.Action {
|
|
return fmt.Errorf("plugin route %s %s action must not have surrounding whitespace", route.Method, route.Path)
|
|
}
|
|
if len(route.Models) > 0 {
|
|
if route.Type == RouteTypeQuery {
|
|
return fmt.Errorf("query route %s %s must not declare models", route.Method, route.Path)
|
|
}
|
|
if err := validateModelScope(route.Models, fmt.Sprintf("route %s %s", route.Method, route.Path)); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// validateModelScope enforces the shared rules for route.models and
|
|
// per-protocol models entries: non-empty canonical names, no duplicates.
|
|
func validateModelScope(models []string, subject string) error {
|
|
seen := make(map[string]struct{}, len(models))
|
|
for _, model := range models {
|
|
if strings.TrimSpace(model) == "" || strings.TrimSpace(model) != model {
|
|
return fmt.Errorf("plugin %s models must contain non-empty canonical names", subject)
|
|
}
|
|
folded := asciiFold(model)
|
|
if _, duplicate := seen[folded]; duplicate {
|
|
return fmt.Errorf("plugin %s models must be unique case-insensitively", subject)
|
|
}
|
|
seen[folded] = struct{}{}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func pathHasParameter(routePath, name string) bool {
|
|
return slices.Contains(strings.Split(routePath, "/"), ":"+name)
|
|
}
|
|
|
|
func ResolveRouteAction(route Route, resolvedAction string) string {
|
|
if strings.TrimSpace(resolvedAction) != "" {
|
|
return resolvedAction
|
|
}
|
|
return route.Action
|
|
}
|
|
|
|
func buildRoutingGeneration(factory, override map[string]*LoadedPlugin, number uint64) (*RoutingGeneration, error) {
|
|
effective := effectivePlugins(factory, override)
|
|
return buildRoutingGenerationFromPlugins(effective, number)
|
|
}
|
|
|
|
func buildRoutingGenerationAdmitting(
|
|
factory, override map[string]*LoadedPlugin,
|
|
number uint64,
|
|
current *RoutingGeneration,
|
|
retainCurrent map[string]struct{},
|
|
) (*RoutingGeneration, map[string]string, error) {
|
|
candidates := effectivePlugins(factory, override)
|
|
accepted := make(map[string]*LoadedPlugin, len(candidates))
|
|
currentByKey := make(map[string]*LoadedPlugin)
|
|
if current != nil {
|
|
for _, plugin := range current.plugins {
|
|
currentByKey[plugin.Meta.Key] = plugin
|
|
}
|
|
}
|
|
generation, err := buildRoutingGenerationFromPlugins(accepted, number)
|
|
if err != nil {
|
|
return nil, nil, fmt.Errorf("initialize routing generation: %w", err)
|
|
}
|
|
|
|
unchangedKeys := make([]string, 0)
|
|
changedKeys := make([]string, 0)
|
|
newKeys := make([]string, 0)
|
|
for key, candidate := range candidates {
|
|
incumbent, exists := currentByKey[key]
|
|
switch {
|
|
case exists && candidate == incumbent:
|
|
unchangedKeys = append(unchangedKeys, key)
|
|
case exists:
|
|
changedKeys = append(changedKeys, key)
|
|
default:
|
|
newKeys = append(newKeys, key)
|
|
}
|
|
}
|
|
sort.Strings(unchangedKeys)
|
|
sort.Strings(changedKeys)
|
|
sort.Strings(newKeys)
|
|
|
|
routingErrors := make(map[string]string)
|
|
orderedKeys := append(unchangedKeys, changedKeys...)
|
|
orderedKeys = append(orderedKeys, newKeys...)
|
|
rejectedKeys := make([]string, 0)
|
|
for _, key := range orderedKeys {
|
|
candidate := candidates[key]
|
|
accepted[key] = candidate
|
|
trial, trialErr := buildRoutingGenerationFromPlugins(accepted, number)
|
|
if trialErr == nil {
|
|
generation = trial
|
|
continue
|
|
}
|
|
delete(accepted, key)
|
|
routingErrors[key] = fmt.Sprintf("plugin %s rejected from routing generation: %v", key, trialErr)
|
|
rejectedKeys = append(rejectedKeys, key)
|
|
}
|
|
|
|
for _, key := range rejectedKeys {
|
|
candidate := candidates[key]
|
|
incumbent, hasIncumbent := currentByKey[key]
|
|
_, mayRetain := retainCurrent[key]
|
|
if !hasIncumbent || !mayRetain || incumbent == candidate {
|
|
continue
|
|
}
|
|
accepted[key] = incumbent
|
|
fallback, fallbackErr := buildRoutingGenerationFromPlugins(accepted, number)
|
|
if fallbackErr == nil {
|
|
generation = fallback
|
|
continue
|
|
}
|
|
delete(accepted, key)
|
|
}
|
|
generation.retainCurrent = cloneStringSet(retainCurrent)
|
|
return generation, routingErrors, nil
|
|
}
|
|
|
|
func effectivePlugins(factory, override map[string]*LoadedPlugin) map[string]*LoadedPlugin {
|
|
effective := make(map[string]*LoadedPlugin, len(factory)+len(override))
|
|
maps.Copy(effective, factory)
|
|
maps.Copy(effective, override)
|
|
return effective
|
|
}
|
|
|
|
func buildRoutingGenerationFromPlugins(effective map[string]*LoadedPlugin, number uint64) (*RoutingGeneration, error) {
|
|
keys := make([]string, 0, len(effective))
|
|
for key := range effective {
|
|
keys = append(keys, key)
|
|
}
|
|
sort.Strings(keys)
|
|
|
|
generation := &RoutingGeneration{
|
|
Number: number,
|
|
PublishedAt: time.Now(),
|
|
byKey: make(map[string]*LoadedPlugin, len(effective)),
|
|
byModel: make(map[string]*LoadedPlugin),
|
|
modelPlugins: make(map[string][]*LoadedPlugin),
|
|
canonicalModelByFold: make(map[string]string),
|
|
byChannelType: make(map[int]*LoadedPlugin),
|
|
routeIndex: make(map[string]RouteBinding),
|
|
protocolIndex: make(map[string][]ProtocolBinding),
|
|
plugins: make([]*LoadedPlugin, 0, len(effective)),
|
|
}
|
|
for _, key := range keys {
|
|
plugin := effective[key]
|
|
generation.byKey[key] = plugin
|
|
generation.plugins = append(generation.plugins, plugin)
|
|
for _, model := range plugin.Meta.Models {
|
|
generation.modelPlugins[model] = append(generation.modelPlugins[model], plugin)
|
|
if _, exists := generation.byModel[model]; !exists {
|
|
generation.byModel[model] = plugin
|
|
}
|
|
folded := asciiFold(model)
|
|
if existing, exists := generation.canonicalModelByFold[folded]; exists {
|
|
if existing != model {
|
|
otherKey := plugin.Meta.Key
|
|
if other, ok := generation.byModel[existing]; ok {
|
|
otherKey = other.Meta.Key
|
|
}
|
|
return nil, fmt.Errorf("plugin %s model %q conflicts with plugin %s model %q", plugin.Meta.Key, model, otherKey, existing)
|
|
}
|
|
continue
|
|
}
|
|
generation.canonicalModelByFold[folded] = model
|
|
}
|
|
|
|
for _, channelType := range plugin.Meta.ChannelTypes {
|
|
if channelType == 0 || channelType == constant.ChannelTypeTaskPlugin {
|
|
continue
|
|
}
|
|
if other, exists := generation.byChannelType[channelType]; exists {
|
|
return nil, fmt.Errorf("plugin %s channelType %d conflicts with plugin %s", plugin.Meta.Key, channelType, other.Meta.Key)
|
|
}
|
|
generation.byChannelType[channelType] = plugin
|
|
}
|
|
|
|
for _, route := range plugin.Meta.Routes {
|
|
shape, err := routePathShape(route.Path)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
indexKey := route.Method + " " + shape
|
|
if other, exists := generation.routeIndex[indexKey]; exists {
|
|
return nil, fmt.Errorf("plugin %s route %s %s conflicts with plugin %s route %s", plugin.Meta.Key, route.Method, route.Path, other.Plugin.Meta.Key, other.Route.Path)
|
|
}
|
|
binding := RouteBinding{Plugin: plugin, Route: route}
|
|
generation.routeIndex[indexKey] = binding
|
|
generation.routes = append(generation.routes, binding)
|
|
}
|
|
|
|
for _, claim := range plugin.Meta.Protocols {
|
|
definition, _ := HostProtocol(claim.Name)
|
|
boundModels := plugin.Meta.Models
|
|
if len(claim.Models) > 0 {
|
|
boundModels = claim.Models
|
|
}
|
|
for _, operation := range definition.Operations {
|
|
if operation.ModelField == "" {
|
|
continue
|
|
}
|
|
for _, method := range operation.Methods {
|
|
for _, model := range boundModels {
|
|
indexKey := endpointIndexKey(method, operation.Path, model)
|
|
bindings := generation.protocolIndex[indexKey]
|
|
if len(bindings) > 0 {
|
|
other := bindings[0]
|
|
if claim.Name != other.Protocol {
|
|
return nil, fmt.Errorf("plugin %s protocol %s %s model %q conflicts with plugin %s", plugin.Meta.Key, method, operation.Path, model, other.Plugin.Meta.Key)
|
|
}
|
|
}
|
|
generation.protocolIndex[indexKey] = append(bindings, ProtocolBinding{Plugin: plugin, Protocol: claim.Name, Operation: operation, Model: model})
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return generation, nil
|
|
}
|
|
|
|
// PreflightRoutingConflict reports whether admitting candidate into the
|
|
// current generation would collide on a channel type, native route, or
|
|
// protocol-model binding. A same-key entry is replaced first so re-uploading
|
|
// a plugin (or overriding a factory built-in) does not self-conflict.
|
|
func PreflightRoutingConflict(current *RoutingGeneration, candidate *LoadedPlugin) error {
|
|
if candidate == nil {
|
|
return fmt.Errorf("cannot preflight a nil plugin")
|
|
}
|
|
effective := make(map[string]*LoadedPlugin)
|
|
number := uint64(0)
|
|
if current != nil {
|
|
for _, plugin := range current.Plugins() {
|
|
effective[plugin.Meta.Key] = plugin
|
|
}
|
|
number = current.Number
|
|
}
|
|
effective[candidate.Meta.Key] = candidate
|
|
_, err := buildRoutingGenerationFromPlugins(effective, number)
|
|
return err
|
|
}
|