Skip to content

feat(plugin): load installed plugins through the SDK and Plugin CRs - #143

Open
imneov wants to merge 38 commits into
modelsphere:mainfrom
imneov:imneov/polaris-global-plugin-runtime
Open

imneov wants to merge 38 commits into
modelsphere:mainfrom
imneov:imneov/polaris-global-plugin-runtime

Conversation

@imneov

@imneov imneov commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • feature
  • breaking: API, config key, chart value, or CRD field changed

What this PR does and why

Plugins register through modelsphere.dev/v1alpha1 Plugin CRs instead of Console Helm values. Console watches CRs through an informer, reads each installed release's plugin.yaml and frontend/ files, and serves /plugins/index.json, /plugins/<group--name>/<asset> and /api/<plugin>/* from that registry.

The branch also carries the frontend plugin SDK and loader work from #114, rebased onto current main. That PR is closed in favour of this one. Its last commit, YAML navigation folders, is not carried over: it extends the static registration path this PR removes.

The old static path is removed outright:

  • helm/console no longer has plugins values; the rendered console.yaml no longer carries them, and the server no longer reads a static plugin list.
  • The static asset proxy, the dev/HMR proxy and the modelsphere.io/v1alpha1 manifest conversion are deleted.
  • The plugin descriptor is now id/group/version/entry/styles/backend; menus, components and internal routes come from the plugin's own SDK registration.
  • The SDK Vite dev preset is removed with the proxy it targeted.

Documentation added:

  • docs/development/plugin-architecture.md — the package, registration contract, loader, serving, proxy, capabilities and failure isolation.
  • docs/development/plugins.md — build a plugin end to end, including the SDK bundle, ReverseProxy and IAM.
  • README and docs/console-design.md link the new guides; modelsphere plugin install help text no longer claims it registers the runtime.

Without this, the two registration paths would keep diverging and the static one would still be able to serve assets no release owns.

Which issue(s) this PR fixes

Fixes #113

How it was tested

  • go build ./..., go vet ./...
  • go test ./internal/...
  • tsc -b --noEmit and tsc -p tsconfig.swiss.json in web/
  • vitest run in web/ (726 tests)
  • tsc --noEmit and vitest run in web/packages/plugin-sdk (13 files, 185 tests)
  • helm lint --strict helm/console
  • Branch is rebased onto current main with no conflicts.

Cluster-level install/upgrade/uninstall remains to be walked through on CPU16.

Checks

  • go test ./... and gofmt -l . is empty
  • npm run typecheck && npm test && npm run build in web/ (if web/ changed)
  • helm lint --strict helm/console (if the chart changed)
  • Docs updated where behaviour, a config key or a chart value moved
  • No internal hostnames, IPs, registries or credentials

Notes for reviewers

Start with internal/server/plugins.go (descriptor and asset serving), web/src/shell/global-sdk/runtime.tsx (SDK-only menus), then internal/plugincli (CR selection) and docs/development/plugin-cli.md.

Release note

action required: frontend plugins now register through a modelsphere.dev/v1alpha1
Plugin CR; the console chart's `plugins` value is removed. Upgrade the console
chart, apply `helm/console/crds/` once, and create a Plugin CR for each installed
plugin release.

imneov and others added 26 commits November 18, 2026 03:58
Discover trusted package manifests at runtime and reuse ConsoleModule for menus, routes and overview cards. Share host React and shell providers without adding plugin management UI.

Fixes modelsphere#113
A Plugin CR is the registration; the Helm release is the runtime. Console
watches modelsphere.dev/v1alpha1 Plugin objects, reads the installed release's
plugin.yaml and frontend/ files from Helm's Secret storage, and serves
/plugins/index.json, /plugins/<cr-name>/<asset> and /api/<plugin>/* through the
release's ReverseProxy. Disabling or deleting the CR removes the frontend and
routes without a Console restart.

The CLI no longer edits Console Helm values. install applies only the host
capabilities the package declares in plugin.yaml requires, and registration
prints a CR for a separate apply.
The strict v1 decode used PluginMeta, which had no requires field, so every
package that declared host capabilities failed inspection. Requirements now
live on PluginMeta and the package manifest aliases that type.
console.yaml is mounted from a ConfigMap, and nothing in the pod template changed when it did, so a values edit that only alters plugins or backends stayed invisible until pods were restarted by hand. Hash the rendered ConfigMap into the pod template.
helm upgrade does not install crds/ on an existing release, so the readyz failure seen on CPU16 needs an explicit kubectl apply. Record the same for clearing the old values plugins list, which otherwise keeps a duplicate index entry beside the CR one.
Plugins now register only through modelsphere.dev/v1alpha1 Plugin CRs;
Console reads each installed release's plugin.yaml and frontend/ files.

- drop Console Helm values plugins, the config type, static/dev proxies,
  and the legacy modelsphere.io/v1alpha1 manifest conversion
- build the plugin index and assets solely from the CR registry
- take menus from SDK registration; descriptor keeps only file locations
- remove the SDK Vite dev preset that targeted the deleted proxy
Plugins load after the shell's first render and add their bundles then. The
sidebar computed its labels before that, kept the fallback literal, and never
re-rendered: i18next lands bundles on the resource store, which emits "added"
on itself, not on the instance. Subscribe to both languageChanged and the
store's added, and route the SDK's subscribeLocale through the same function.

Also serve the SPA shell with no-cache and content-hashed assets as immutable,
so a tab opened before an upgrade revalidates instead of running the old
bundle.
Plugins no longer ask the host for named capabilities with boolean flags.
A provider — the platform or another plugin — declares what it publishes in
`provides`; a consumer names what it binds to in `consumes`, optionally
pinning the provider and product version with `from`. The CLI resolves each
binding before Helm and writes the published values under
`consumed.<group>/<name>.<key>`.

- api: replace PluginRequirements with PluginCapability and
  PluginCapabilityBinding; regenerate deepcopy and the Plugin CRD
- pluginpackage: validate capability ids, schema versions, value paths,
  provider kind and SemVer constraints
- plugincli: resolve platform built-ins (image pull secrets, inference
  namespaces, Swiss gateway) plus registered plugins; a plugin declaration
  shadows the matching built-in; fail preflight on missing, ambiguous,
  out-of-range, cross-namespace or unpublished values
- docs: describe the capability model in plugins.md, plugin-cli.md and
  plugin-platform-config.md
Console serves the bundle from the installed Chart's frontend/ directory, so a
package without the declared entry can never load. validate, package and install
now reject it before Helm runs.

install also passes --atomic, so a timed-out upgrade rolls back and a failed
first install is uninstalled instead of leaving a pending release that blocks
the next attempt.
workflow_dispatch only: stamps the chart's image reference, lints it, packages
it and uploads console-<version>.tgz. With push on it also builds the image and
pushes it; any registry but GHCR authenticates with the REGISTRY_USERNAME and
REGISTRY_PASSWORD secrets, and chart_repository optionally pushes the chart.
Discovery only needs the name, namespace and status labels Helm puts on
release Secrets, but kubectl returned every Secret body: a release record
carries the packaged chart and values, so the cluster-wide list here is
megabytes. Over a slow API path the response is cut off mid-stream and
install fails before Helm runs with a stream ID INTERNAL_ERROR.

Read the list through client-go's metadata client instead, which asks the
API server for PartialObjectMetadata and pages at 500 records. The same
discovery now transfers 61 KB instead of about 8 MB and finishes in
seconds.
Move the ReverseProxy types next to User, IAMRole and IAMRoleBinding in internal/iam, faithful to the CRD schema, and drop the separate api/iam package whose SchemeBuilder and generated deepcopy nothing used. Plugin registration parses the Helm-rendered manifest, so it only needs decoding, not scheme registration.
@imneov
imneov force-pushed the imneov/polaris-global-plugin-runtime branch from 17765c4 to c8d1d98 Compare November 17, 2026 20:01
@imneov imneov changed the title feat(plugin): register plugins through Plugin CRs feat(plugin): load installed plugins through the SDK and Plugin CRs Nov 17, 2026
@imneov
imneov marked this pull request as ready for review November 17, 2026 23:59
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T00:14:08.324051Z c8d1d98 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8d1d98517

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +127 to +129
prefix := strings.TrimSuffix(route.Spec.Matcher.Path, "*")
if !strings.HasPrefix(prefix, "/api/") || !strings.HasSuffix(prefix, "/") || !route.Spec.Directives.AuthProxy {
return nil, fmt.Errorf("plugin ReverseProxy must authenticate an /api/ prefix")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Reject plugin routes that overlap Console-owned APIs

A registered chart can supply /api/iam/* or even /api/* and pass this check. Server.Handler runs pluginBackends before the built-in mux, so such a route captures requests such as GET /api/iam/users and authorizes them as backends/<plugin> instead of reaching the native handler. Existing config.validateBackend explicitly reserves these paths for static backends, but registrations bypass that protection. Reject Console-owned prefixes and broader prefixes covering them before publishing routes, so installing a plugin cannot take over session or IAM APIs.

Useful? React with 👍 / 👎.

Comment thread internal/plugincli/capabilities.go Outdated
Comment on lines +79 to +82
if bindsPlatformCapability(bindings, capabilitySwissGateway) {
provider, err := swissCapabilityProvider(console)
if err != nil {
return nil, err

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve plugin providers before validating the Swiss fallback

When externalSwiss.url is empty—the chart default—and an installed Plugin CR provides swiss.modelsphere.dev/gateway, a consumer with an unpinned binding still fails here. swissCapabilityProvider returns an error before runner.Registrations is queried, so preferPluginProviders never lets the real plugin shadow the built-in as documented. This prevents installing consumers against a plugin-provided gateway unless the unrelated built-in URL is also configured. Discover matching plugin providers first and validate the built-in fallback only when it is needed.

Useful? React with 👍 / 👎.

Comment thread web/src/extensions/surface.tsx Outdated
Comment on lines +34 to +36
const data = Object.fromEntries(
dataExtensions.map((extension, index) => [extension.id, queries[index]?.data]),
);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Namespace extension results by their owning plugin

When two plugins both declare a data extension named owner for inference-service, both registrations are accepted because duplicate checks in createRegistration are plugin-local. This map nevertheless keeps only the last response because its key omits extension.plugin, and both plugins' presentation and visibility callbacks receive the overwritten data. A valid pair of plugins can therefore silently display another plugin's ownership or status results. Construct plugin-local data maps for callbacks, or introduce plugin-qualified keys consistently in the SDK contract.

Useful? React with 👍 / 👎.

Comment thread web/src/shell/plugins.ts
Comment on lines +15 to +16
asset.onload = () => finish();
asset.onerror = () => finish(new Error(`Cannot load ${asset instanceof HTMLScriptElement ? asset.src : asset.href}`));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject execution failures before committing plugin registrations

If an entry registers its definition, component and extensions and then throws synchronously during the remaining initialization, a classic script reports that exception through the window's error event and still emits its element's load event. These listeners therefore resolve successfully: runtime.finish() and commit() retain the partial module and extensions, while loadPlugins reports no failure. Observe execution errors for the active entry as well as resource-loading errors before committing, so this scenario follows the intended per-plugin rollback path.

Useful? React with 👍 / 👎.

pluginBackends matches before the native mux, so a registered chart could
claim /api/* or /api/iam/* and answer Console's own API as a backend. Reject
the bare /api prefix and the prefixes Console serves itself, sharing the
reserved list with configured backends.
A consumer of swiss.modelsphere.dev/gateway failed when externalSwiss.url was
unset, even when an installed plugin provided the capability, because the
built-in was validated before registrations were read. Discover plugins first
and validate the built-in only when a binding still needs it.
Two plugins that both named a result "owner" shared one map key, so one
overwrote the other for both visibility and presentation callbacks. Build the
map from the owning plugin's extensions only.
A classic script that throws still fires load, so a partial registration
committed and the failure went unreported. Watch window's error event for the
active entry and reject before commit.
The guide was tied to one environment: a named cluster, a VPN step, personal
paths, an internal Console URL, private branches and an internal registry.
Rewrite it in English alongside the other developer docs, keep every CLI
behavior, and use plugin.yaml 'my-plugin' as the running example so the same
identity appears in all three plugin documents.
The chart_repository help named one team's registry. Keep the example generic
so the workflow reads the same for every fork and every cluster.
…ixture

The fixture carried an internal registry address. A documentation-range host
exercises the same host:port split.
@huskcass

huskcass commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Not all require a fix, posting here just for reference

Verdict: Request Changes

The overall direction of modelsphere/console#143 (0d842c2, 128 files / +15,181 / −65) is clean — replacing static Helm plugins values with read-only observation of modelsphere.dev/v1alpha1 Plugin CRs and chart-embedded bundles removes a whole class of drift, and the four follow-up commits after Codex's review moved in the right direction. However, there are security, runtime-isolation, CLI-correctness, and public-repo hygiene blockers that should be fixed before merging.

(Note on the 4 follow-up fixes since c8d1d98: each addressed the narrow case flagged by Codex but left adjacent gaps noted below — /api/k8s & configured backends in 98fa423, from: { kind: Platform } in 3ca0221, visibility scoping in 958b06e, and host-frame throws in 0d842c2.)


1. Security & Public-Repo Blockers

  1. Multiline input bypass → $GITHUB_OUTPUT injection & GNU sed RCE in package.yml

    • .github/workflows/package.yml:103-117, .github/workflows/package.yml:138-146, .github/workflows/package.yml:195-196
    • printf '%s' "$var" | grep -Eq '^...$' matches per line, so a multiline workflow_dispatch input (e.g., chart_repository containing \nrepository=x|;1e <cmd>;s|a|b or \nimage_host=attacker.invalid) passes validation, overwrites earlier keys in $GITHUB_OUTPUT, and either executes arbitrary shell commands via GNU sed's e command (even with push: false) or exfiltrates REGISTRY_USERNAME/REGISTRY_PASSWORD via docker/login-action (lines 160–166).
    • Fix: Reject \n/\r and validate with Bash [[ ... =~ ... ]], and replace sed string interpolation with a safe YAML/env-based substitution.
  2. Internal IPs, private paths, VPN/cluster names, and private registries committed (violates PR checklist)

    • docs/development/plugin-cli.md:3, docs/development/plugin-cli.md:56-97, docs/development/plugin-cli.md:135-138, docs/development/plugin-cli.md:279: exposes CPU16 cluster/VPN, /Users/neov/.kube/kubeconfig-cpu16-admin.yaml, /Users/neov/orca/workspaces/console/可拔插, http://172.28.44.16:30370, private branches, and swr.cn-east-3.myhuaweicloud.com/risecloud (with a specific commit SHA).
    • .github/workflows/package.yml:13-18, .github/workflows/package.yml:46: leaks oci://quanzhenglong.com/edge/charts in comments and the GitHub Actions UI tooltip.
    • web/packages/plugin-sdk/src/create-instance.test.ts:6-15: uses 10.126.126.53:30016 instead of an RFC 5737/example host.
  3. Plugin ReverseProxy can still hijack /api/k8s/* and configured backend prefixes

    • internal/config/config.go:268, internal/pluginregistry/release.go:131-136, internal/server/server.go:152, internal/server/workload.go:16-21
    • pluginBackends runs before the native mux, but reservedPrefixes omits /api/k8s (Console's workload/pod-log API) and never rejects prefixes owned by configured backends (/api/deploy, /api/llm, etc.) or another already-registered plugin.
    • Additionally, plugin_registry.go authorizes and indexes backends by bare meta.Name (internal/server/plugin_registry.go:42, internal/server/plugin_registry.go:79-88), so a plugin named swiss or two plugins across different groups sharing name collide on RBAC (backends/<name>), /api/capabilities, and frontend id.
  4. Archive validation smuggling (duplicate plugin.yaml & yaml.v3 vs sigs.k8s.io/yaml case mismatch)

    • internal/pluginpackage/artifact.go:138-156, internal/pluginpackage/artifact.go:222-234, internal/pluginregistry/release.go:69-75
    • inspectArchive allows duplicate tar paths and validates only the last plugin.yaml, whereas pluginregistry/release.go loops over installed.Chart.Files and unmarshals every plugin.yaml into the same PluginMeta without resetting — letting an earlier entry smuggle unvalidated provides into status.pluginMeta.
    • parseMetadata parses Manifest with case-sensitive yaml.v3 (validated & used by CLI), then checks strict schema with case-insensitive sigs.k8s.io/yaml (used by pluginregistry). Capitalized Provides: / Consumes: is silently skipped by yaml.v3 (Validate() and install see empty slices) yet accepted by sigyaml.UnmarshalStrict and published to the cluster.
  5. CLI flag injection & broken credential redaction

    • Flag injection: Unvalidated spec.chart.releaseName (and positional chart paths) are passed to helm get values / helm uninstall / helm lint / helm package without -- (internal/plugincli/runner.go:178-228, internal/plugincli/capabilities.go:213-217, internal/plugincli/root.go:567-571). A releaseName starting with - is parsed as a Helm flag.
    • Broken redaction:
      • sensitiveLogPattern (internal/plugincli/runner.go:29) matches only one token after authorization:, so Authorization: Bearer <jwt> becomes Authorization: <redacted> <jwt> (token left in plaintext).
      • Error returns at internal/plugincli/runner.go:72-82 emit up to 4096 bytes of unredacted stderr + stdout even at -v=0.
      • redactCommandArgs (internal/plugincli/runner.go:121-144) misses --token=<val>, --password=<val>, --kube-token, and space-separated --set <val> / --set-string <val> / --set-file <val>.
  6. Unpinned third-party GitHub Action & broadened namespace Secret RBAC

    • .github/workflows/ci.yml:64: pnpm/action-setup@v4 is unpinned while every other action across workflows is pinned to a 40-char commit SHA.
    • helm/console/templates/rbac.yaml:51-74: grants blanket secrets get, list across {{ .Release.Namespace }} (which also holds Console's jwtSecret, swiss-proxy-key, backendSecrets, and router API keys that router-rbac.yaml intentionally scoped via resourceNames). If Helm Secret storage requires this trade-off, document it clearly; also add missing console.labels to the new Role/RoleBinding and trim plugins/status verbs (get/patch are unused).

2. High-Severity Correctness & Runtime Bugs

Backend, Helm & Upgrade Path

  1. Helm upgrade stalls indefinitely on /readyz when Plugin CRD is not pre-applied

    • cmd/console/main.go:81, internal/pluginregistry/registry.go:63-85, internal/server/server.go:208-211
    • Helm never installs crds/ during helm upgrade, so upgrading any existing Console release with --wait will fail /readyz (503 loading plugin registrations) forever unless helm/console/crds/ is applied first. This also breaks CRD-less auth.disabled installs promised in docs/console-design.md. At minimum, helm/console/README.md / README.zh-CN.md must document the mandatory CRD pre-apply step and add plugins.modelsphere.dev and reverseproxies.iam.theriseunion.io to the uninstall commands (or make the observer degrade gracefully when the CRD is absent).
  2. Disabling a Plugin CR never updates status; 30s resync lists full Helm Secret bodies

    • internal/pluginregistry/registry.go:62, internal/pluginregistry/registry.go:120-123, internal/pluginregistry/release.go:33-37
    • When spec.enabled becomes false, reconcile removes the in-memory entry and returns nil without calling UpdateStatus, leaving status.phase: Installed and frontendStatus.distributed: true stale.
    • The 30s informer resync triggers driver.NewSecrets.Last(name) (which lists all historical revision Secrets with full gzipped chart bodies) for every plugin on every Console replica every 30s — the same multi-megabyte Secret list pattern commit 2622f23 fixed for CLI discovery.

Plugin CLI & Packaging

  1. CommandTimeout == --timeout SIGKILLs helm before --atomic rollback can execute

    • internal/plugincli/root.go:230, internal/plugincli/root.go:503, internal/plugincli/runner.go:54-57, internal/plugincli/runner.go:232-238
    • exec.CommandContext starts a timer for r.CommandTimeout before spawning helm --wait --atomic --timeout <same-duration>. On rollout timeout, Go kills helm with SIGKILL before Helm's --atomic rollback/uninstall runs, leaving the release stuck in pending-install/pending-upgrade. Give the outer context headroom over Helm's --timeout (and set cmd.WaitDelay).
  2. Hardcoded artifact.Manifest.Name release name causes cross-group & Console release overwrites

    • internal/plugincli/root.go:153, internal/plugincli/root.go:527, internal/plugincli/registration.go:87
    • lifecycleFlags.pluginRelease is never bound, and prepareInstall/registrationCommand hardcode artifact.Manifest.Name. Two plugins from different groups with the same name overwrite each other's Helm release in the default namespace; a plugin with name: console overwrites the Console Helm release itself; and valid DNS-1123 names >53 chars pass validate/package then fail Helm's 53-char release-name limit.
  3. Capability resolution bugs: disabled/degraded CRs act as providers; preferPluginProviders breaks from: { kind: Platform } & version coexistence

    • internal/plugincli/capabilities.go:95-118, internal/plugincli/capabilities.go:204-269
    • pluginCapabilityProvider never checks registration.Spec.Enabled, Status.Phase == Installed, or DeletionTimestamp.IsZero(). A disabled CR still shadows built-ins, and a Degraded CR with a missing release makes helm get values fail unrelated consumer installs.
    • preferPluginProviders globally deletes built-in declarations by capability name alone (ignoring binding.From and capability Version). Even though needsSwissBuiltin adds the built-in for from: { kind: Platform }, line 102 immediately strips it back out, breaking from: { kind: Platform } and v1/v2 coexistence.
    • Also: swissCapabilityProvider only reads externalSwiss.* (broken for bundled swiss.enabled: true installs) and sets SameNamespace: false even though externalSwiss.proxyKey.secretName is namespace-local to Console (internal/plugincli/capabilities.go:171-200, helm/console/values.yaml:107-113).
  4. Console auto-discovery relies on non-existent Helm Secret chart label; multi-file KUBECONFIG breaks all CLI commands

    • internal/plugincli/discovery.go:99-112, internal/plugincli/root.go:270-303: Helm's Secret driver only writes owner, name, status, version, modifiedAt — never chart. labels["chart"] is always "", so isConsoleRelease fails for any custom release name (even when --console-release <name> is passed explicitly!). Duplicate status=deployed Secrets for one release also aren't deduplicated.
    • internal/plugincli/root.go:38, internal/plugincli/discovery.go:87, internal/plugincli/runner.go:158-175: passing os.Getenv("KUBECONFIG") into --kubeconfig / rules.ExplicitPath breaks whenever KUBECONFIG contains colon-separated paths (a:b).

Frontend Shell, Extensions & Plugin SDK

  1. useLocale() / useT() still does not re-render when late plugin i18n bundles load

    • web/src/shell/i18n.ts:87-94, web/src/shell/i18n.ts:128-131, web/src/shell/i18n.test.tsx:62-77
    • Commit 1135fd1 subscribed to i18n.store's "added" event, but useSyncExternalStore(subscribe, getLocale) still uses getLocale() as the snapshot. Because addResourceBundle doesn't change i18n.language, Object.is(prev, next) is true and React bails out without re-rendering Layout/Sidebar/MenuLink. (i18n.test.tsx only tested subscribeLocale, not useLocale()/useT().) Track a monotonic bundle revision in the snapshot.
  2. No error isolation in ResourceExtensionSurface or plugin routes — a throwing plugin white-screens Console

    • web/src/extensions/surface.tsx:38-46, web/src/shell/App.tsx:69-83
    • candidate.evaluate(...) runs in render with no try/catch (and receives data[id] === undefined before queries resolve), and there is no ErrorBoundary around plugin presentations or <RoutePage />. Because ResourceExtensionSurface renders in every InferenceList row and the InferenceDetail header, one plugin exception crashes built-in Console pages.
  3. Broken extension contracts across surface.tsx, registry.ts, and InferenceDetail.tsx / InferenceList.tsx

    • Cross-plugin visibility sabotage: web/src/extensions/surface.tsx:39-41 ANDs all plugins' visibility extensions for (resourceType, placement) rather than scoping to candidate.plugin === extension.plugin. Plugin A returning false hides Plugin B's presentation. Also line 44 keys by extension.key while runtime.tsx:152 checks uniqueness on extension.id.
    • evaluateResourceAction drops extension data: web/src/extensions/registry.ts:47-56 always passes data: {} (never loaded dataExtensions), and hardcodes Chinese "扩展策略暂不可用" on error.
    • uninstall block disables slo: web/src/modules/inferences/InferenceDetail.tsx:113, web/src/modules/inferences/InferenceDetail.tsx:145 folds actionBlocked("uninstall") into blockedWrite, which is still passed to the slo action's disabled prop.
    • Mismatched resource shapes on shared cache key: web/src/modules/inferences/InferenceList.tsx:70 passes Deployment (has uid), whereas web/src/modules/inferences/InferenceDetail.tsx:170 passes ReleaseStatus (web/src/modules/swiss/lib/api.ts:728-762, no uid), under the same resourceType="inference-service" and React Query key (staleTime: 30_000).
    • Wasted queries & TanStack Query v5 retry storm: web/src/extensions/surface.tsx:25-32 runs useQueries even when presentations.length === 0, and any load() returning undefined triggers 3 retries per row in TanStack Query v5.
  4. react-dom build alias and SDK ↔ Console host contract mismatches

    • Broken react-dom shim: web/packages/plugin-sdk/src/build.ts:122-123 aliases 'react-dom' to web/packages/plugin-sdk/src/react-shim.ts:11-49, which exports zero react-dom APIs (createPortal, flushSync, etc.) and breaks react-dom/client via esbuild prefix aliasing; web/src/shell/global-sdk/host.tsx:36-38 never exposes react-dom. react-shim.ts also omits React 19 exports (use, useActionState, useOptimistic, Profiler, etc.) despite Console running React 19.3.
    • build.ts / shared-imports.ts footguns: web/packages/plugin-sdk/src/build.ts:149-151 passes opts.cssSource || 'src' to sharedImports, crashing or producing empty virtual modules when cssSource: false is used with the documented frontend/src layout; ...restTsupOverrides clobbers esbuildOptions and banner if overridden.
    • createMockSDK() is broken out of the box: web/packages/plugin-sdk/src/testing.ts:91 sets VERSION: '0.1.0', which immediately throws a major-version mismatch in createPlugin() (SDK_VERSION = '1.0.1'), and omits registerPluginRoutes and *Extension methods.
    • Host runtime gaps:
      • useClusterDisplayName (web/packages/plugin-sdk/src/cluster-display-name.ts:5-8) always throws TypeError in Console (host.tsx:38 has no business.useClusterDisplayName).
      • registerSlot (web/src/shell/global-sdk/runtime.tsx:163-174) uses id: target, key: target instead of slot.name, so reusing one component across two placements fails as duplicate registration.
      • menu.authKey (web/src/shell/global-sdk/runtime.tsx:63-79) is never mapped to ModulePage.permission.
      • GlobalSDKSession (web/src/shell/global-sdk/host.tsx:22-26) populates currentUser in useLayoutEffect, so getAuth() sees null during initial render of plugin pages.
      • apiClient (web/src/shell/global-sdk/api.ts:14) calls response.json() for all non-204 responses, throwing SyntaxError on empty 200/201/202/205 bodies.
      • watchScriptErrors (web/src/shell/plugins.ts:26) filters on event.filename !== script.src, missing synchronous errors thrown inside host SDK methods (where event.filename is Console's bundle URL), and record() (web/src/shell/global-sdk/runtime.tsx:113) swallows registration errors so createPlugin() still executes onMount(ctx) for a doomed plugin.

3. Medium Issues & Cleanups

  • CLI & Packaging edge cases:
    • Runner.LogWriter has a data race at -v>=4 between stderr redactingWriter and waitCommand's heartbeat ticker (internal/plugincli/runner.go:60-95).
    • inspectArchive (internal/pluginpackage/artifact.go:96-156) breaks on valid tarballs containing a PAX global header (tar.TypeXGlobalHeader), lacks an outer decompression limit / TypeDir count limit, and skips device/FIFO entries instead of rejecting them like boundedDirectory.
    • Validation drift between CLI and runtime: pluginpackage accepts 0-byte frontend/<entry>, skips ValidPluginAsset on sibling frontend/ files, uses a loose semverPattern (accepting 01.02.03 / 1.0.0-a..b that later fail semver.NewVersion in capabilities.go:375), and accepts dotted/digit-leading plugin.yaml name (IsDNS1123Subdomain) that fails frontend validateModules (/^[a-z][a-z0-9-]*$/ at web/src/shell/module.tsx:76).
    • plugin uninstall (internal/plugincli/root.go:539-578, internal/plugincli/registration.go:47-52): interactive prompt displays c.Name instead of CR name when releaseName is empty; empty spec.chart.namespace runs helm uninstall --namespace "" after deleting the CR; in-process CRs aren't rejected; --console-* / --plugin-namespace flags are bound but ignored.
    • plugin package (internal/plugincli/root.go:113-140) writes directly to output on first run (leaving a corrupt .tgz behind if post-package Inspect fails) and doesn't reject .tgz inputs; plugin registration (internal/plugincli/registration.go:78-95) binds unused --wait/-f flags and requires cluster discovery even when --plugin-namespace is explicit; explicit --config / MODELSPHERE_CONFIG silently falls back to ambient kubeconfig if the file doesn't exist (internal/plugincli/config.go:31-33).
  • Helm values & package.yml:
    • helm/console/values.yaml:126-127 defaults platform.inferenceNamespaces: [swiss-deploy] instead of [], defeating the documented preflight failure and silently passing swiss-deploy to non-default/bundled Swiss clusters.
    • .github/workflows/package.yml:99-136: 2-segment Docker Hub repos like 4pdosc/console parse image_host=4pdosc and fail login; line 134 reports $image_host even when chart_host is the external registry; non-SemVer version builds and pushes the image before helm package fails.
  • SDK & Web packaging hygiene:
    • Unused js-yaml / @types/js-yaml added to web/package.json:25 (and lockfile); unused extensions.modules in web/src/modules/index.ts:10.
    • web/packages/plugin-sdk/package.json:9-29 omits ./react-jsx-runtime-shim from exports and lists build-only @tailwindcss/oxide and typescript in runtime dependencies; Dockerfile:29 COPY web/packages ./packages busts npm ci cache whenever plugin-sdk changes.
    • web/packages/plugin-sdk/src/cluster-resource-api.ts:63-178: path.includes('://') rejects URLs in query params; extractNamespaceSegment misses /namespaces//pods and second /namespaces/_all; control-char check skips query strings and 0x7f; AbortSignal.timeout() (TimeoutError) is misclassified as a network error.
  • Documentation drift:
    • docs/plans/2026-11-05-global-sdk-design.md (still linked as active design from docs/console-design.md:139 and docs/installed-plugins-proposal.md) describes the deleted static YAML plugins: [] + Vite HMR proxy architecture and has broken anchors.
    • docs/development/plugins.md:
      • Lines 166–168 tell extension-only plugins to reuse the annotated page's basePath, which validateModules rejects (already taken).
      • Lines 393–395 claim modelsphere plugin validate validates ReverseProxy (it does not).
      • Examples use separate namespaces (my-plugin-system, canary-modelsphere-system) without warning that Console's Role only reads Helm Secrets in Console's own namespace.
      • Line 114 puts package.json at frontend/package.json, contradicting the chart-root layout and .helmignore on lines 16 & 371–379.
      • Line 496 / docs/development/plugin-architecture.md:186 say loader errors go to the browser console (plugins.ts doesn't call console.error; they render in a floating UI <details role="alert"> — which also shows on /login).

Verified Clean

  • api/plugin/v1alpha1/types.go matches helm/console/crds/modelsphere.dev_plugins.yaml 1:1, and zz_generated.deepcopy.go deep-copies all fields/maps/slices properly.
  • internal/iam/reverseproxy_types.go matches helm/console/crds/iam.theriseunion.io_reverseproxies.yaml 1:1.
  • helm/console/templates/deployment.yaml checksum/config annotation and configmap.yaml writePermission template render cleanly.
  • gofmt -l is clean and all 5 GitHub PR CI checks (ci/go, ci/web, ci/plugin-sdk, ci/gate, publish/publish) pass on 0d842c2.

@aceforeverd
aceforeverd requested a review from zoboth November 19, 2026 05:54
Comment thread .github/workflows/package.yml Outdated
# With push on the same run also builds and pushes the image, and pushes the chart
# when chart_repository names a target.
on:
workflow_dispatch:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to drop it, workflow_dispatch does not help. the lib's own publish will added to publish workflow, we can do it later after merged

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

drop it

@zoboth zoboth left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocker

A plugin's ReverseProxy route can silently hijack an existing configured backend's prefix (or another plugin's), because the only prefix checks are against Console's own reserved list.

  • internal/pluginregistry/release.go (readRoutes) only rejects a plugin route when the prefix is the literal /api or matches config.ReservedAPIPrefix (/api/iam, /api/me, /api/router, /api/capabilities). It never checks the prefix against s.cfg.ConfiguredBackends() (the statically configured backends mounted by mountBackends in internal/server/proxy.go) or against routes other Plugin entries already publish.
  • In internal/server/server.go, the handler chain is s.pluginBackends(pluginPaths(mux)), and pluginBackends (internal/server/plugin_registry.go) walks plugin routes and proxies a match before falling through to next.ServeHTTP (the mux, which is where mountBackends registered the static backends).

So if a chart registers a ReverseProxy whose prefix equals (or is a parent of) an existing configured backend's prefix — e.g. an admin's backends: [{name: deploy, prefix: /api/deploy}] — installing that Plugin CR makes pluginBackends intercept and proxy all /api/deploy/* traffic to the plugin's own (CR-declared) upstream instead of the intended backend, with no startup validation or conflict error anywhere in the registration path. The same gap lets two plugins silently shadow each other if they pick the same prefix. Please cross-check a candidate route's prefix against ConfiguredBackends() and already-registered entries (same way /api and the reserved Console prefixes are rejected today) before publishing it.

Non-blocking note

  • internal/pluginregistry/registry.go reconcile: when spec.enabled flips to false, the entry is removed from the in-memory registry immediately (assets/backends stop being served), but the early return nil skips r.report(...), so status.phase stays Installed and status.frontendStatus.distributed stays true even though Console no longer serves that release. Minor status/observability drift rather than a functional break.

Everything else I checked reads cleanly: ValidPluginAsset is sound against path traversal/absolute paths/escapes (backed by fs.ValidPath plus the extra char blocklist), asset bytes are served from an in-memory map keyed by validated relative paths (no filesystem traversal even if a key were unexpected), the Helm-release/CR identity/scope/type checks in release.go are strict, backend proxy requests still go through s.authorize, and the mandatory crds/ pre-apply step for helm upgrade is documented with the exact symptom and command in docs/development/plugin-cli.md.

A package that ships the Plugin CR registers itself, so the old fixed message
told the user to do work that was already done. Read the registrations after
the upgrade and report what is actually there; a Chart without the CR still
gets the follow-up step.
Registration belongs to the release: the recommended package ships the Plugin
CR, so install registers and uninstall removes it. Document the template, the
version and enabled values, and keep the separate registration command for
Charts that do not ship the CR.
The CLI had no way to report which build it was; --version now prints the same
version constant the Console binary and the Chart appVersion share.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

design: Console plugin SDK and configured navigation folders

4 participants