Design: configurable model-router auto-routing trigger model ID

Author: zmuxunyCreated Sep 16, 2026Updated Sep 16, 2026

Configurable model-router auto-routing trigger model ID

Proposal Issue: #4706
Source RFC: #4605
Requirement: SPEC-4706001
Audited baseline: faccaad586a3cdc9e85dc7fa39358ff31a6453b2

Goal

Allow one model-router plugin instance to replace the hard-coded higress/auto auto-routing trigger with one configured exact model ID while preserving the current sentinel as the compatibility default.

Current implementation locations

plugins/wasm-go/extensions/model-router/main.go
- AutoModelPrefix defines higress/auto.
- ModelRouterConfig has no trigger-model field.
- parseConfig reads autoRouting.enable, defaultModel, and rules.
- handleJsonBody checks modelValue == AutoModelPrefix.
plugins/wasm-go/extensions/model-router/main_test.go already covers auto-routing config, rule matching, and request handling.
README.md and README_EN.md document the plugin configuration.

Selected design

Add autoModelId string to ModelRouterConfig.
While parsing autoRouting, read modelId verbatim. If the parsed string is empty, assign AutoModelPrefix (higress/auto). Do not trim or normalize a non-empty configured value; trigger semantics remain exact and case-sensitive.
In handleJsonBody, replace the hard-coded comparison with modelValue == config.autoModelId.
A custom value replaces the default trigger for that plugin instance. It is not an alias in addition to higress/auto.
Keep the existing rule loop, first-match behavior, defaultModel fallback, body rewrite, and routing-header write unchanged.
Document autoRouting.modelId, its default, and replacement semantics in both plugin READMEs.

Behavior matrix

Configuration	Incoming model	Auto route?
`enable: true`, no `modelId`	`higress/auto`	yes
`enable: true`, no `modelId`	`company-assistant`	no
`enable: true`, `modelId: company-assistant`	`company-assistant`	yes
`enable: true`, `modelId: company-assistant`	`higress/auto`	no
`enable: false`, any `modelId`	any	no

Scope and ownership

Production scope is main.go; regression coverage is main_test.go; user-facing configuration documentation is README.md and README_EN.md. No VERSION, shared SDK, control-plane, or unrelated model-router behavior is changed.

Compatibility and risks

Existing configurations are behavior-compatible because the default remains higress/auto.
A user who explicitly configures a custom modelId intentionally stops using higress/auto as the trigger for that plugin instance.
Exact matching avoids accidental activation by prefixes, regexes, or model families and keeps the change bounded.
The primary regression risk is an uninitialized default; config tests must prove the default is set whenever autoRouting exists and modelId is empty.

Verification Plan

Record the exact implementation parent and fixed SHA. From plugins/wasm-go/extensions/model-router run on the exact fixed head:

bash

go test ./... -count=1
go test -race ./... -count=1
go vet ./...
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o /tmp/model-router.wasm ./
sha256sum /tmp/model-router.wasm
git diff --check BASELINE_SHA...FIXED_SHA

Focused tests must prove config parsing for omitted, empty, and custom modelId; request behavior for the default and custom triggers; rejection of the old sentinel after a custom trigger is configured; disabled-auto behavior; and unchanged target selection/default-model fallback once auto routing starts.

The README assertions are reviewed against the tested config semantics. No runtime-only correctness claim is introduced by this feature; if implementation reveals a proxy-Wasm-specific discrepancy, stop and amend this Design before expanding scope.

Rejected alternatives

Wildcard/regex trigger matching: larger ambiguity and accidental-match surface.
Treating a custom ID as an alias in addition to higress/auto: makes the configuration unable to replace the public model ID cleanly.
Multiple auto-routing profiles in one plugin instance: useful but a separate configuration/model-selection problem outside SPEC-4706001.

Rollback

Revert the config field and comparison. No persisted data, migration, or external schema version is introduced.

Agent participation

A coding agent materially assisted with source analysis and this Design. No implementation or verification has begun. Implementation remains blocked until Proposal #4706 and this Design receive explicit Higress maintainer approval and an implementation TASK is authorized.