ModelRouter/internal/lua/plugin_adapter_bridge.go

// Package lua — 插件适配器管理桥接（R4-a / Phase 3）
//
// 用户需求：插件可安装、运行时修改适配器，以支持复杂认证与 token 轮换；
// 适配器本身不需要持续运行（它是无状态请求级弹性池）。
//
//	插件（长期运行）──定期/事件驱动──> install/update/remove_adapter
//	                                          │
//	                                          ▼
//	                          内核重建该适配器的池（LoadAdapterSource）
//	                                          │
//	                                          ▼
//	                              后续请求自然使用新逻辑
//
// 三条安全规则（与 R6 同源）：
//
//  1. 路径安全：名字必须通过 ValidateAdapterName（无穿越/绝对路径/空白）
//  2. 不得影子内置：插件不能注册与内置适配器同名的适配器
//     （用 VM.InstallPluginAdapter，运维仍可自行覆盖）
//  3. 归属可查：记录每个适配器的 owner（"plugin:名字" 或 "operator"），
//     于是「插件只能改自己装的」这条规则是可判定的，而不是靠约定
//
// 第 3 条是必要的：没有归属信息时，"插件 A 改插件 B 装的适配器" 无法区分
// 于合法的自身更新，会导致一个插件能劫持另一个插件的认证逻辑。
package lua

import (
	"fmt"
	"sort"
	"sync"

	golua "github.com/aarzilli/golua/lua"
)

// AdapterOwner 标识一个适配器由谁安装。
const (
	OwnerOperator = "operator" // 磁盘/首启 seed/管理员上传
	OwnerPlugin   = "plugin"   // 由某个插件经桥接安装
)

// adapterOwnership records which plugin installed each adapter.
//
// This is the state that makes rule 3 enforceable: InstallPluginAdapter marks
// the adapter as owned by that plugin, and a later update from a DIFFERENT
// plugin is refused. An adapter with no owner is the operator's, and no plugin
// may touch it.
type adapterOwnership struct {
	mu sync.RWMutex
	// owner maps adapter name -> installing plugin name (only for plugin-owned).
	owner map[string]string
}

// ownedBy reports the plugin that owns name, or "" when it is operator-owned.
func (o *adapterOwnership) ownedBy(name string) string {
	o.mu.RLock()
	defer o.mu.RUnlock()
	return o.owner[name]
}

func (o *adapterOwnership) set(name, plugin string) {
	o.mu.Lock()
	defer o.mu.Unlock()
	if o.owner == nil {
		o.owner = map[string]string{}
	}
	o.owner[name] = plugin
}

func (o *adapterOwnership) clear(name string) {
	o.mu.Lock()
	defer o.mu.Unlock()
	delete(o.owner, name)
}

// listOwned returns the adapter names a given plugin owns (for UI/diagnostics).
func (o *adapterOwnership) listOwned(plugin string) []string {
	o.mu.RLock()
	defer o.mu.RUnlock()
	var out []string
	for name, p := range o.owner {
		if p == plugin {
			out = append(out, name)
		}
	}
	sort.Strings(out)
	return out
}

// Plugins carries an adapter-ownership table.
func (ps *Plugins) adapterOwner() *adapterOwnership {
	ps.adapterOwnOnce.Do(func() { ps.adapterOwn = &adapterOwnership{} })
	return ps.adapterOwn
}

// InstallAdapter registers an adapter on behalf of a plugin.
//
// Returns the name that was actually registered — an adapter script may declare
// a different `name` than the file/registration key, and the declared name is
// what sources must reference. Callers get it back so they can update config.
func (ps *Plugins) InstallAdapter(plugin, name, code string) (string, error) {
	if plugin == "" {
		return "", fmt.Errorf("install_adapter: caller plugin is unknown")
	}
	if ps.vm == nil {
		return "", fmt.Errorf("install_adapter: no adapter VM available")
	}
	// Rule 3 first: an adapter another plugin already owns is off-limits.
	if owner := ps.adapterOwner().ownedBy(name); owner != "" && owner != plugin {
		return "", fmt.Errorf("install_adapter: adapter %q is owned by plugin %q and cannot be replaced by %q",
			name, owner, plugin)
	}
	// Rules 1+2 (path safety + no shadowing built-ins) live in
	// InstallPluginAdapter so there is exactly one enforcement point.
	if err := ps.vm.InstallPluginAdapter(name, code); err != nil {
		return "", err
	}
	// Ownership is recorded under the name sources will actually reference. A
	// script may declare a name different from the registration key, and it is
	// the declared name that ends up in the registry — recording it under the
	// key would leave the adapter un-owned and therefore mutable by anyone.
	// Ownership is recorded under the name sources will actually reference. A
	// script may declare a name different from the registration key, and it is
	// the declared name that ends up in the registry — recording it under the
	// key would leave the adapter un-owned and therefore mutable by anyone.
	//
	// Both names are recorded: the registration key so a later update through
	// the same key still matches, and the declared name so a lookup by the name
	// a source references also matches. Both entries are cleared together on
	// remove.
	effective := ps.vm.EffectiveAdapterName(name)
	ps.adapterOwner().set(effective, plugin)
	if effective != name {
		ps.adapterOwner().set(name, plugin)
	}
	return effective, nil
}

// UpdateAdapter replaces an adapter a plugin previously installed — the token
// rotation path. The plugin gets a NEW pool; the old one is shut down, so an
// in-flight request either uses the old or the new code, never a mixture.
//
// Only the owning plugin may update. Updating an operator-installed adapter is
// refused: the operator's file on disk would then disagree with what the running
// gateway executes, and the next restart would silently revert the "update".
func (ps *Plugins) UpdateAdapter(plugin, name, code string) error {
	if plugin == "" {
		return fmt.Errorf("update_adapter: caller plugin is unknown")
	}
	owner := ps.adapterOwner().ownedBy(name)
	if owner == "" {
		return fmt.Errorf("update_adapter: adapter %q is operator-installed; "+
			"only adapters a plugin installed can be updated at runtime", name)
	}
	if owner != plugin {
		return fmt.Errorf("update_adapter: adapter %q is owned by plugin %q, not %q",
			name, owner, plugin)
	}
	if err := ps.vm.InstallPluginAdapter(name, code); err != nil {
		return err
	}
	// Ownership is unchanged: same plugin, new version.
	return nil
}

// RemoveAdapter removes an adapter a plugin installed. Operator-installed
// adapters are refused (same reasoning as UpdateAdapter).
func (ps *Plugins) RemoveAdapter(plugin, name string) error {
	owner := ps.adapterOwner().ownedBy(name)
	if owner == "" {
		return fmt.Errorf("remove_adapter: adapter %q is operator-installed; "+
			"use DELETE /api/adapters/%s", name, name)
	}
	if owner != plugin {
		return fmt.Errorf("remove_adapter: adapter %q is owned by plugin %q, not %q",
			name, owner, plugin)
	}
	ps.vm.RemoveAdapter(name)
	ps.adapterOwner().clear(name)
	return nil
}

// PluginAdapters lists the adapters a plugin owns (its token-rotation surface).
func (ps *Plugins) PluginAdapters(plugin string) []string {
	return ps.adapterOwner().listOwned(plugin)
}

// AdapterOwnerOf reports the owning plugin of an adapter, or "" if operator-owned.
func (ps *Plugins) AdapterOwnerOf(name string) string {
	return ps.adapterOwner().ownedBy(name)
}

// ---- Lua 绑定（R4：插件在运行时改自己的适配器）----

// adapterBridgeGlobal 暴露给插件 Lua 的适配器管理表。
//
// 用一张表而不是三个顶层全局，是为了少占插件可见的全局命名空间。表用
// buildJSONTable 的同一套写法（NewTable + PushGoClosure + SetField），
// 该写法在 json 表上已被长期验证。
const adapterBridgeGlobal = "__llmsproxy_adapters"

// registerAdapterBridge 把适配器管理表装进插件的 Lua 状态。
//
// name 是**该插件自己的启动名**，随每次调用一起交给 Go 侧桥接 —— 归属校验
// 因此来自启动时的固定身份，而不是从 Lua 状态里现读（那样一个分片或任何持有
// 已编译脚本的调用者就能冒充别的插件）。
func registerAdapterBridge(L *golua.State, ps *Plugins, name string) {
	L.NewTable()
	install := luaInstallAdapter(L, ps, name)
	L.PushGoClosure(install)
	L.SetField(-2, "install")
	update := luaUpdateAdapter(L, ps, name)
	L.PushGoClosure(update)
	L.SetField(-2, "update")
	remove := luaRemoveAdapter(L, ps, name)
	L.PushGoClosure(remove)
	L.SetField(-2, "remove")
	L.SetGlobal(adapterBridgeGlobal)
}

func luaInstallAdapter(L *golua.State, ps *Plugins, name string) golua.LuaGoFunction {
	return func(L *golua.State) int {
		adapterName := L.ToString(1)
		code := L.ToString(2)
		effective, err := ps.InstallAdapter(name, adapterName, code)
		if err != nil {
			L.PushNil()
			L.PushString(err.Error())
			return 2
		}
		L.PushString(effective)
		L.PushNil()
		return 2
	}
}

func luaUpdateAdapter(L *golua.State, ps *Plugins, name string) golua.LuaGoFunction {
	return func(L *golua.State) int {
		adapterName := L.ToString(1)
		code := L.ToString(2)
		if err := ps.UpdateAdapter(name, adapterName, code); err != nil {
			L.PushNil()
			L.PushString(err.Error())
			return 2
		}
		L.PushBoolean(true)
		L.PushNil()
		return 2
	}
}

func luaRemoveAdapter(L *golua.State, ps *Plugins, name string) golua.LuaGoFunction {
	return func(L *golua.State) int {
		adapterName := L.ToString(1)
		if err := ps.RemoveAdapter(name, adapterName); err != nil {
			L.PushNil()
			L.PushString(err.Error())
			return 2
		}
		L.PushBoolean(true)
		L.PushNil()
		return 2
	}
}