web-extend-plugin-vue2 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# web-extend-plugin-vue2
+
+Vue 2.7 宿主侧 **Web 扩展插件**运行时：拉取清单、`hostApi`、菜单与 **`registerSlotComponents` 注册表**，以及 **`ExtensionPoint`**（同一组件覆盖内容区、工具栏等任意扩展点；插件在该点挂载 Vue 组件即可）。
+
+## 依赖
+
+- `peerDependencies`: `vue@^2.7`, `vue-router@^3.6`
+- `dependencies`: `semver`
+
+## 在 Vite 宿主中使用
+
+```js
+import { bootstrapPlugins, createHostApi, registries } from 'web-extend-plugin-vue2'
+
+bootstrapPlugins(router, (pluginId) => createHostApi(pluginId, router)).catch(console.warn)
+```
+
+开发环境下清单前缀、插件 Vite 联调等默认从 `import.meta.env`（`VITE_FRONTEND_PLUGIN_BASE`、`VITE_WEB_PLUGIN_DEV_*`）读取。非 Vite 或需覆盖时可传入第三参数，见源码 `resolveRuntimeOptions` / `WebExtendPluginRuntimeOptions`。
+
+## 发布到 npm
+
+在包目录执行 `npm publish`（需有权限）。本仓库可用 `file:../web-extend-plugin-vue2` 联调示例宿主。

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "web-extend-plugin-vue2",
+  "version": "0.1.0",
+  "description": "Vue 2.7 host runtime for web-extend-plugin: manifest bootstrap, hostApi, registries, ExtensionPoint",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "vue": "^2.7.0",
+    "vue-router": "^3.6.0"
+  },
+  "dependencies": {
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9",
+    "vue": "^2.7.16",
+    "vue-router": "^3.6.5"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xtemplus/extend-plugin-framework.git",
+    "directory": "web-extend-plugin-vue2"
+  },
+  "keywords": [
+    "vue2",
+    "plugin",
+    "extension"
+  ]
+}

package/src/PluginRuntime.js

@@ -0,0 +1,347 @@
+import * as semver from 'semver'
+import { HOST_PLUGIN_API_VERSION } from './constants.js'
+
+/**
+ * @typedef {object} WebExtendPluginRuntimeOptions
+ * @property {string} [manifestBase] 清单服务 URL 前缀，默认 `/fp-api` 或 `VITE_FRONTEND_PLUGIN_BASE`
+ * @property {boolean} [isDev] 是否开发模式；默认取 Vite `import.meta.env.DEV`
+ * @property {string} [webPluginDevOrigin] 插件 Vite dev origin，如 `http://localhost:5188`
+ * @property {string} [webPluginDevIds] 逗号分隔插件 id，用于隐式 dev 入口
+ * @property {string} [webPluginDevMapJson] JSON 字符串，id → 入口 URL，等价 `VITE_WEB_PLUGIN_DEV_MAP`
+ */
+
+/** 与清单里 entryUrl 的 hostname 一致；含 IPv6 本机，避免部分环境解析 localhost → ::1 后被宿主拒绝 */
+const DEFAULT_ALLOWED_HOSTS = new Set(['localhost', '127.0.0.1', '::1'])
+
+function viteEnv(key, fallback = '') {
+  try {
+    if (typeof import.meta !== 'undefined' && import.meta.env && import.meta.env[key] !== undefined) {
+      const v = import.meta.env[key]
+      if (v !== '' && v !== undefined) return v
+    }
+  } catch (_) {
+    /* non-Vite bundler */
+  }
+  return fallback
+}
+
+function viteIsDev() {
+  try {
+    return !!import.meta.env.DEV
+  } catch (_) {
+    return false
+  }
+}
+
+/**
+ * 合并宿主传入项与 Vite 环境变量（便于 npm 包在 Vite 宿主中零配置；亦可在非 Vite 场景显式传入）。
+ * @param {WebExtendPluginRuntimeOptions} [user]
+ */
+export function resolveRuntimeOptions(user = {}) {
+  return {
+    manifestBase:
+      user.manifestBase !== undefined && user.manifestBase !== ''
+        ? user.manifestBase
+        : viteEnv('VITE_FRONTEND_PLUGIN_BASE', '/fp-api') || '/fp-api',
+    isDev: user.isDev !== undefined ? user.isDev : viteIsDev(),
+    webPluginDevOrigin:
+      user.webPluginDevOrigin !== undefined
+        ? user.webPluginDevOrigin
+        : viteEnv('VITE_WEB_PLUGIN_DEV_ORIGIN', ''),
+    webPluginDevIds:
+      user.webPluginDevIds !== undefined
+        ? user.webPluginDevIds
+        : viteEnv('VITE_WEB_PLUGIN_DEV_IDS', ''),
+    webPluginDevMapJson:
+      user.webPluginDevMapJson !== undefined
+        ? user.webPluginDevMapJson
+        : viteEnv('VITE_WEB_PLUGIN_DEV_MAP', '')
+  }
+}
+
+function normalizeHost(hostname) {
+  if (!hostname) return ''
+  const h = hostname.toLowerCase()
+  if (h.startsWith('[') && h.endsWith(']')) {
+    return h.slice(1, -1)
+  }
+  return h
+}
+
+function isScriptHostAllowed(url) {
+  try {
+    const u = new URL(url, window.location.origin)
+    const h = normalizeHost(u.hostname)
+    return DEFAULT_ALLOWED_HOSTS.has(h)
+  } catch {
+    return false
+  }
+}
+
+function parseWebPluginDevMapExplicit(opts) {
+  if (!opts.isDev) {
+    return null
+  }
+  const raw = opts.webPluginDevMapJson
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return null
+  }
+  try {
+    const map = JSON.parse(String(raw))
+    return map && typeof map === 'object' ? map : null
+  } catch {
+    console.warn('[plugins] VITE_WEB_PLUGIN_DEV_MAP is not valid JSON')
+    return null
+  }
+}
+
+async function buildImplicitWebPluginDevMap(opts) {
+  if (!opts.isDev) {
+    return {}
+  }
+  const origin = opts.webPluginDevOrigin === undefined || opts.webPluginDevOrigin === null
+    ? ''
+    : String(opts.webPluginDevOrigin).trim()
+  if (!origin) {
+    return {}
+  }
+  if (!isScriptHostAllowed(`${origin}/`)) {
+    return {}
+  }
+  const base = origin.replace(/\/$/, '')
+  const pingUrl = `${base}/__web_plugin_dev_ping`
+  try {
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 500)
+    const r = await fetch(pingUrl, {
+      mode: 'cors',
+      cache: 'no-store',
+      signal: ctrl.signal
+    })
+    clearTimeout(timer)
+    if (!r.ok) {
+      return {}
+    }
+    const body = (await r.text()).trim()
+    if (body !== 'ok') {
+      return {}
+    }
+  } catch {
+    return {}
+  }
+
+  const idsRaw = opts.webPluginDevIds
+  const ids =
+    idsRaw !== undefined && idsRaw !== null && String(idsRaw).trim() !== ''
+      ? String(idsRaw)
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : ['com.example.frontend.demo']
+
+  const map = {}
+  for (const id of ids) {
+    map[id] = `${base}/src/plugin-entry.js`
+  }
+  console.info(
+    '[plugins] 已检测到插件 Vite（',
+    base,
+    '），下列 id 将加载源码入口而非清单 dist：',
+    ids.join(', ')
+  )
+  return map
+}
+
+function mergeDevMaps(implicit, explicit) {
+  const i = implicit && typeof implicit === 'object' ? implicit : {}
+  const e = explicit && typeof explicit === 'object' ? explicit : {}
+  return { ...i, ...e }
+}
+
+/** @type {Set<string>} */
+const pluginDevSseStarted = typeof window !== 'undefined' ? new Set() : new Set()
+
+function isDevOriginAllowedForSse(origin) {
+  try {
+    const u = new URL(origin)
+    return DEFAULT_ALLOWED_HOSTS.has(normalizeHost(u.hostname))
+  } catch {
+    return false
+  }
+}
+
+function startPluginDevReloadSse(origin, isDev) {
+  if (!isDev || pluginDevSseStarted.has(origin)) {
+    return
+  }
+  if (!isDevOriginAllowedForSse(origin)) {
+    return
+  }
+  pluginDevSseStarted.add(origin)
+  const base = origin.replace(/\/$/, '')
+  const url = `${base}/__web_plugin_reload_stream`
+  try {
+    const es = new EventSource(url)
+    es.addEventListener('reload', () => {
+      window.location.reload()
+    })
+    es.onopen = () => {
+      console.info('[plugins] plugin dev reload SSE:', url)
+    }
+  } catch (e) {
+    console.warn('[plugins] EventSource failed', url, e)
+  }
+}
+
+function startPluginDevSseForMap(devMap, isDev) {
+  if (!isDev || !devMap) {
+    return
+  }
+  const origins = new Set()
+  for (const entry of Object.values(devMap)) {
+    if (typeof entry !== 'string') {
+      continue
+    }
+    const t = entry.trim()
+    if (!t) {
+      continue
+    }
+    try {
+      origins.add(new URL(t, window.location.href).origin)
+    } catch {
+      /* skip */
+    }
+  }
+  for (const o of origins) {
+    startPluginDevReloadSse(o, isDev)
+  }
+}
+
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    const s = document.createElement('script')
+    s.async = true
+    s.src = src
+    s.onload = () => resolve()
+    s.onerror = () => reject(new Error('loadScript failed: ' + src))
+    document.head.appendChild(s)
+  })
+}
+
+async function loadPluginEntry(p, entryUrl, devMap) {
+  const devEntry = devMap && typeof devMap[p.id] === 'string' ? devMap[p.id].trim() : ''
+  if (devEntry) {
+    if (!isScriptHostAllowed(devEntry)) {
+      console.warn('[plugins] dev entry URL not allowed', p.id, devEntry)
+      return
+    }
+    try {
+      await import(/* @vite-ignore */ devEntry)
+    } catch (e) {
+      console.warn('[plugins] dev module import failed, try manifest entryUrl', p.id, e)
+      if (entryUrl && isScriptHostAllowed(entryUrl)) {
+        await loadScript(entryUrl)
+      }
+      return
+    }
+    return
+  }
+  if (!entryUrl || !isScriptHostAllowed(entryUrl)) {
+    console.warn('[plugins] skip (entryUrl not allowed)', p.id, entryUrl)
+    return
+  }
+  await loadScript(entryUrl)
+}
+
+/**
+ * @param {import('vue-router').default} router
+ * @param {(pluginId: string) => object} createHostApi
+ * @param {WebExtendPluginRuntimeOptions} [runtimeOptions] 可选；不传则从 Vite `import.meta.env` 读取（若存在）
+ */
+export async function bootstrapPlugins(router, createHostApi, runtimeOptions) {
+  const opts = resolveRuntimeOptions(runtimeOptions || {})
+  const base = String(opts.manifestBase).replace(/\/$/, '')
+  const explicit = parseWebPluginDevMapExplicit(opts)
+
+  const [manifestResult, implicit] = await Promise.all([
+    (async () => {
+      try {
+        const res = await fetch(`${base}/api/frontend-plugins`, { credentials: 'include' })
+        if (!res.ok) {
+          return { ok: false, status: res.status, data: null }
+        }
+        const data = await res.json()
+        return { ok: true, data }
+      } catch (e) {
+        return { ok: false, error: e, data: null }
+      }
+    })(),
+    buildImplicitWebPluginDevMap(opts)
+  ])
+
+  const devMap = mergeDevMaps(implicit, explicit)
+  startPluginDevSseForMap(devMap, opts.isDev)
+
+  if (!manifestResult.ok) {
+    if (manifestResult.error) {
+      console.warn('[plugins] fetch manifest failed', manifestResult.error)
+    } else {
+      console.warn('[plugins] manifest HTTP', manifestResult.status)
+    }
+    return
+  }
+  /** @type {{ hostPluginApiVersion?: string, plugins?: object[] }} */
+  const data = manifestResult.data
+  if (!data) {
+    return
+  }
+
+  const apiVer = data.hostPluginApiVersion
+  if (apiVer) {
+    const coerced = semver.coerce(apiVer)
+    const maj = coerced ? coerced.major : 0
+    const range = `^${maj}.0.0`
+    if (!semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
+      console.warn(
+        '[plugins] host API version mismatch: host implements',
+        HOST_PLUGIN_API_VERSION,
+        'server declares',
+        apiVer
+      )
+    }
+  }
+
+  window.__PLUGIN_ACTIVATORS__ = window.__PLUGIN_ACTIVATORS__ || {}
+
+  const plugins = data.plugins || []
+  if (plugins.length === 0) {
+    console.info(
+      '[plugins] 清单为空。请检查：① web-extend-plugin-server 是否已启动；② 其 JVM 工作目录下 web-plugins-dir 是否指向含 manifest 的目录（通常应在 web-extend-plugin-server 目录执行 mvn spring-boot:run，且存在 ../web-plugins/子目录）；③ 浏览器访问清单 URL 是否有 plugins 条目。'
+    )
+  }
+  for (const p of plugins) {
+    const range = p.engines && p.engines.host
+    if (range && !semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
+      console.warn('[plugins] skip (engines.host)', p.id, range)
+      continue
+    }
+    const entryUrl = p.entryUrl
+    try {
+      await loadPluginEntry(p, entryUrl, devMap)
+    } catch (e) {
+      console.warn('[plugins] script load failed', p.id, e)
+      continue
+    }
+    const activator = window.__PLUGIN_ACTIVATORS__[p.id]
+    if (typeof activator !== 'function') {
+      console.warn('[plugins] no activator for', p.id)
+      continue
+    }
+    const hostApi = createHostApi(p.id)
+    try {
+      activator(hostApi)
+    } catch (e) {
+      console.error('[plugins] activate failed', p.id, e)
+    }
+  }
+}

package/src/bridge.js

@@ -0,0 +1,22 @@
+const ALLOWED_PREFIXES = ['/api/']
+
+/**
+ * @returns {{ request: (path: string, init?: RequestInit) => Promise<Response> }}
+ */
+export function createRequestBridge() {
+  return {
+    async request(path, init = {}) {
+      if (typeof path !== 'string' || !path.startsWith('/')) {
+        throw new Error('[bridge] path must be a string starting with /')
+      }
+      const allowed = ALLOWED_PREFIXES.some((p) => path.startsWith(p))
+      if (!allowed) {
+        throw new Error('[bridge] path not allowed: ' + path)
+      }
+      return fetch(path, {
+        credentials: 'same-origin',
+        ...init
+      })
+    }
+  }
+}

package/src/bridge.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { createRequestBridge } from './bridge.js'
+
+describe('createRequestBridge', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn(() => Promise.resolve(new Response(null, { status: 200 })))
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('allows paths under /api/', async () => {
+    const bridge = createRequestBridge()
+    await bridge.request('/api/channels')
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      '/api/channels',
+      expect.objectContaining({ credentials: 'same-origin' })
+    )
+  })
+
+  it('rejects paths outside allowlist', async () => {
+    const bridge = createRequestBridge()
+    await expect(bridge.request('/fp-api/x')).rejects.toThrow(/not allowed/)
+    await expect(bridge.request('http://evil.com/api/x')).rejects.toThrow()
+  })
+})

package/src/components/ExtensionPoint.vue

@@ -0,0 +1,62 @@
+<template>
+  <div class="extension-point" :data-point-id="pointId">
+    <SlotErrorBoundary
+      v-for="item in items"
+      :key="item.key"
+      :label="item.pluginId"
+    >
+      <component :is="item.component" v-bind="forwardProps" />
+    </SlotErrorBoundary>
+  </div>
+</template>
+
+<script>
+import { registries } from '../registries.js'
+
+const SlotErrorBoundary = {
+  name: 'SlotErrorBoundary',
+  props: { label: String },
+  data() {
+    return { error: null }
+  },
+  errorCaptured(err) {
+    this.error = err && err.message ? err.message : String(err)
+    console.error('[ExtensionPoint] render error in', this.label, err)
+    return false
+  },
+  render(h) {
+    if (this.error) {
+      return h(
+        'div',
+        { class: 'plugin-point-error', style: { color: '#c00', fontSize: '12px' } },
+        `[插件 ${this.label}] 渲染失败`
+      )
+    }
+    const d = this.$slots.default
+    return d && d[0] ? d[0] : h('span')
+  }
+}
+
+export default {
+  name: 'ExtensionPoint',
+  components: { SlotErrorBoundary },
+  props: {
+    pointId: { type: String, required: true },
+    slotProps: { type: Object, default: () => ({}) }
+  },
+  computed: {
+    items() {
+      return registries.slots[this.pointId] || []
+    },
+    forwardProps() {
+      return this.slotProps || {}
+    }
+  }
+}
+</script>
+
+<style scoped>
+.extension-point {
+  min-height: 8px;
+}
+</style>

package/src/constants.js

@@ -0,0 +1,2 @@
+/** Must match web-extend-plugin-server FrontendPluginsResponse.hostPluginApiVersion */
+export const HOST_PLUGIN_API_VERSION = '1.0.0'

package/src/createHostApi.js

@@ -0,0 +1,93 @@
+import Vue from 'vue'
+import { HOST_PLUGIN_API_VERSION } from './constants.js'
+import { createRequestBridge } from './bridge.js'
+import { registries } from './registries.js'
+
+/**
+ * @param {string} pluginId
+ * @param {import('vue-router').default} router
+ */
+export function createHostApi(pluginId, router) {
+  const bridge = createRequestBridge()
+  const teardowns = []
+
+  function injectStylesheet(href) {
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href = href
+    link.setAttribute('data-plugin-asset', pluginId)
+    document.head.appendChild(link)
+  }
+
+  function injectScript(src) {
+    return new Promise((resolve, reject) => {
+      const s = document.createElement('script')
+      s.async = true
+      s.src = src
+      s.setAttribute('data-plugin-asset', pluginId)
+      s.onload = () => resolve()
+      s.onerror = () => reject(new Error('script failed: ' + src))
+      document.head.appendChild(s)
+    })
+  }
+
+  return {
+    hostPluginApiVersion: HOST_PLUGIN_API_VERSION,
+
+    registerRoutes(routes) {
+      const wrapped = routes.map((r) => ({
+        ...r,
+        meta: { ...(r.meta || {}), pluginId }
+      }))
+      router.addRoutes(wrapped)
+    },
+
+    registerMenuItems(items) {
+      for (const item of items) {
+        registries.menus.push({ ...item, pluginId })
+      }
+      registries.menus.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    },
+
+    registerSlotComponents(pointId, components) {
+      if (!pointId) return
+      if (!registries.slots[pointId]) {
+        Vue.set(registries.slots, pointId, [])
+      }
+      const list = registries.slots[pointId]
+      for (const c of components) {
+        list.push({
+          pluginId,
+          component: c.component,
+          priority: c.priority ?? 0,
+          key: `${pluginId}-${pointId}-${list.length}-${Date.now()}`
+        })
+      }
+      list.sort((a, b) => b.priority - a.priority)
+    },
+
+    registerStylesheetUrls(urls) {
+      for (const u of urls || []) {
+        if (typeof u === 'string' && u) injectStylesheet(u)
+      }
+    },
+
+    registerScriptUrls(urls) {
+      const chain = (urls || []).filter((u) => typeof u === 'string' && u).reduce(
+        (p, u) => p.then(() => injectScript(u)),
+        Promise.resolve()
+      )
+      chain.catch((e) => console.warn('[plugins] registerScriptUrls', pluginId, e))
+    },
+
+    registerSanitizedHtmlSnippet() {
+      throw new Error('registerSanitizedHtmlSnippet is not enabled in MVP')
+    },
+
+    getBridge: () => bridge,
+
+    onTeardown(_pid, fn) {
+      if (typeof fn === 'function') teardowns.push(fn)
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export { bootstrapPlugins, resolveRuntimeOptions } from './PluginRuntime.js'
+export { createHostApi } from './createHostApi.js'
+export { registries } from './registries.js'
+export { createRequestBridge } from './bridge.js'
+export { HOST_PLUGIN_API_VERSION } from './constants.js'
+export { default as ExtensionPoint } from './components/ExtensionPoint.vue'

package/src/registries.js

@@ -0,0 +1,10 @@
+import Vue from 'vue'
+
+/**
+ * Reactive registries for menus, extension slots, and button toolbars.
+ */
+export const registries = Vue.observable({
+  menus: [],
+  /** pointId -> Array<{ pluginId, component, priority, key }>（工具栏等扩展点与内容区共用同一模型） */
+  slots: {}
+})