feat: support custom plugins as a declarative resource

apps/cli/src/command/utils.ts

@@ -58,6 +58,7 @@ export const toKVConfiguration = (
           'plugin_metadata',
           'stream_routes',
           'upstreams',
+          'custom_plugins',
         ].includes(resourceType) // ensure that you don't convert unexpected keys
       ) {
         return [
@@ -131,7 +132,13 @@ export const filterConfiguration = (
 ): [ADCSDK.Configuration, ADCSDK.Configuration] => {
   const removed: ADCSDK.Configuration = {};
   Object.keys(configuration).forEach((resourceType) => {
-    if (resourceType === 'plugin_metadata' || resourceType === 'global_rules')
+    // Keyed-object and label-less resources are not subject to label filtering;
+    // custom plugins are global and must not be pruned by a label selector.
+    if (
+      resourceType === 'plugin_metadata' ||
+      resourceType === 'global_rules' ||
+      resourceType === 'custom_plugins'
+    )
       return;
     const result = labelFilter(configuration[resourceType], rules);
     configuration[resourceType] = result.filtered;
@@ -146,11 +153,10 @@ const labelFilter = <T extends ADCSDK.Event['newValue']>(
   rules: Record<string, string> = {},
 ) => {
   const filtered = resources.filter((resource) => {
+    // Some resources (e.g. custom plugins) carry no labels.
+    const labels = (resource as { labels?: ADCSDK.Labels })?.labels;
     return Object.entries(rules).every(
-      ([key, value]) =>
-        resource?.labels &&
-        resource?.labels[key] &&
-        resource?.labels[key] === value,
+      ([key, value]) => labels && labels[key] && labels[key] === value,
     );
   });
 
@@ -170,10 +176,17 @@ export const fillLabels = (
       : labels;
 
   for (const resourceType in configuration) {
-    if (['global_rules', 'plugin_metadata'].includes(resourceType)) continue;
+    // global_rules/plugin_metadata are keyed objects; custom_plugins are
+    // label-less, so none of them participate in label selectors.
+    if (
+      ['global_rules', 'plugin_metadata', 'custom_plugins'].includes(
+        resourceType,
+      )
+    )
+      continue;
 
-    (configuration[resourceType] as Array<ADCSDK.ResourceFor<any>>).forEach(
-      (resource) => {
+    (configuration[resourceType] as Array<{ labels?: ADCSDK.Labels }>).forEach(
+      (resource: any) => {
         resource.labels = assignSelector(resource.labels as ADCSDK.Labels);
 
         // Process the nested resources

apps/cli/src/tasks/load_local.ts

@@ -52,12 +52,16 @@ export const LoadLocalConfigurationTask = (
                   (await readFile(filePath, { encoding: 'utf-8' })) ?? '';
 
                 const ext = path.extname(filePath).toLowerCase();
-                if (ext === '.json') {
-                  subCtx.configurations[filePath] =
-                    JSON.parse(fileContent) ?? {};
-                  return;
-                }
-                subCtx.configurations[filePath] = YAML.load(fileContent) ?? {};
+                const config: ADCSDK.Configuration =
+                  ext === '.json'
+                    ? (JSON.parse(fileContent) ?? {})
+                    : (YAML.load(fileContent) ?? {});
+
+                // Inline external Lua sources referenced by custom plugins and
+                // validate the declared name against the source.
+                await resolveCustomPluginSources(config, filePath);
+
+                subCtx.configurations[filePath] = config;
               },
             };
           }),
@@ -111,3 +115,43 @@ export const LoadLocalConfigurationTask = (
     );
   },
 });
+
+// Resolve each custom plugin's `path` reference into an inline `content`
+// (read relative to the config file), and verify that the declared `name`
+// actually appears in the (plaintext) Lua source so a typo is caught locally
+// rather than rejected later by the control plane.
+const resolveCustomPluginSources = async (
+  config: ADCSDK.Configuration,
+  configFilePath: string,
+) => {
+  const customPlugins = config.custom_plugins;
+  if (!Array.isArray(customPlugins) || customPlugins.length === 0) return;
+
+  const baseDir = path.dirname(configFilePath);
+  const looksLikeLua = (source: string) =>
+    /\b(function|return|local)\b/.test(source);
+
+  for (const plugin of customPlugins) {
+    if (plugin.path) {
+      const sourcePath = path.resolve(baseDir, plugin.path);
+      if (!existsSync(sourcePath))
+        throw new Error(
+          `Custom plugin "${plugin.name}" references a source file that does not exist: ${sourcePath}`,
+        );
+      plugin.content =
+        (await readFile(sourcePath, { encoding: 'utf-8' })) ?? '';
+      delete plugin.path;
+    }
+
+    // Only validate when the source is plaintext Lua; obfuscated/bytecode
+    // uploads will not contain the name literally.
+    if (
+      plugin.content &&
+      looksLikeLua(plugin.content) &&
+      !plugin.content.includes(plugin.name)
+    )
+      throw new Error(
+        `Custom plugin name "${plugin.name}" was not found in its Lua source; the declared name must match the plugin's name in the source.`,
+      );
+  }
+};

libs/backend-api7/e2e/resources/custom-plugin.e2e-spec.ts

@@ -0,0 +1,84 @@
+import * as ADCSDK from '@api7/adc-sdk';
+import { globalAgent as httpAgent } from 'node:http';
+
+import { BackendAPI7 } from '../../src';
+import {
+  createEvent,
+  deleteEvent,
+  dumpConfiguration,
+  generateHTTPSAgent,
+  syncEvents,
+  updateEvent,
+} from '../support/utils';
+
+describe('Custom Plugin E2E', () => {
+  let backend: BackendAPI7;
+
+  beforeAll(() => {
+    backend = new BackendAPI7({
+      server: process.env.SERVER!,
+      token: process.env.TOKEN!,
+      tlsSkipVerify: true,
+      gatewayGroup: process.env.GATEWAY_GROUP,
+      cacheKey: 'default',
+      httpAgent,
+      httpsAgent: generateHTTPSAgent(),
+    });
+  });
+
+  describe('Sync and dump custom plugins', () => {
+    const pluginName = 'e2e-custom-plugin';
+    const pluginContent = [
+      'local core = require("apisix.core")',
+      'local schema = { type = "object", properties = {} }',
+      `local _M = { version = 0.1, priority = 0, name = "${pluginName}", schema = schema }`,
+      'function _M.check_schema(conf) return core.schema.check(schema, conf) end',
+      'function _M.access(conf, ctx) end',
+      'return _M',
+    ].join('\n');
+    const plugin = {
+      name: pluginName,
+      content: pluginContent,
+      description: 'created by e2e',
+    } as ADCSDK.CustomPlugin;
+
+    it('Create custom plugin', async () =>
+      syncEvents(backend, [
+        createEvent(ADCSDK.ResourceType.CUSTOM_PLUGIN, pluginName, plugin),
+      ]));
+
+    it('Dump', async () => {
+      const result = (await dumpConfiguration(backend)) as ADCSDK.Configuration;
+      expect(result.custom_plugins).toHaveLength(1);
+      expect(result.custom_plugins?.[0]).toMatchObject({
+        name: pluginName,
+        content: pluginContent,
+      });
+    });
+
+    it('Update custom plugin (description changed)', async () => {
+      plugin.description = 'updated by e2e';
+      await syncEvents(backend, [
+        updateEvent(ADCSDK.ResourceType.CUSTOM_PLUGIN, pluginName, plugin),
+      ]);
+    });
+
+    it('Dump again (description updated)', async () => {
+      const result = (await dumpConfiguration(backend)) as ADCSDK.Configuration;
+      expect(result.custom_plugins?.[0]).toMatchObject({
+        name: pluginName,
+        description: 'updated by e2e',
+      });
+    });
+
+    it('Delete custom plugin', async () =>
+      syncEvents(backend, [
+        deleteEvent(ADCSDK.ResourceType.CUSTOM_PLUGIN, pluginName),
+      ]));
+
+    it('Dump again (custom plugin should not exist)', async () => {
+      const result = (await dumpConfiguration(backend)) as ADCSDK.Configuration;
+      expect(result.custom_plugins ?? []).toHaveLength(0);
+    });
+  });
+});

libs/backend-api7/src/fetcher.ts

@@ -5,6 +5,7 @@ import { isEmpty } from 'lodash-es';
 import {
   Subject,
   combineLatest,
+  filter,
   from,
   map,
   mergeMap,
@@ -257,23 +258,63 @@ export class Fetcher extends ADCSDK.backend.BackendEventSource {
     );
   }
 
+  public listCustomPlugins() {
+    if (this.isSkip(ADCSDK.ResourceType.CUSTOM_PLUGIN))
+      return of<Array<ADCSDK.CustomPlugin>>([]);
+
+    const taskName = 'Fetch custom plugins';
+    const logger = this.getLogger(taskName);
+    const taskStateEvent = this.taskStateEvent(taskName);
+    logger(taskStateEvent('TASK_START'));
+    return from(
+      this.client.get<typing.ListResponse<typing.CustomPlugin>>(
+        '/api/custom_plugins',
+      ),
+    ).pipe(
+      tap((resp) => logger(this.debugLogEvent(resp))),
+      mergeMap((resp) =>
+        from(resp.data.list ?? []).pipe(
+          // Custom plugins are control-plane-global; only manage those deployed
+          // to the gateway group that this backend targets.
+          filter(
+            (plugin) =>
+              !this.opts.gatewayGroupId ||
+              (plugin.gateway_groups ?? []).includes(this.opts.gatewayGroupId),
+          ),
+          map((plugin) => this.toADC.transformCustomPlugin(plugin)),
+        ),
+      ),
+      toArray(),
+      tap(() => logger(taskStateEvent('TASK_DONE'))),
+    );
+  }
+
   public dump() {
     return combineLatest([
       this.listServices(),
       this.listConsumers(),
       this.listSSLs(),
       this.listGlobalRules(),
       this.listMetadatas(),
+      this.listCustomPlugins(),
     ]).pipe(
       takeLast(1),
       map(
-        ([services, consumers, ssls, global_rules, plugin_metadata]) =>
+        ([
+          services,
+          consumers,
+          ssls,
+          global_rules,
+          plugin_metadata,
+          custom_plugins,
+        ]) =>
           ({
             services,
             consumers,
             ssls,
             global_rules,
             plugin_metadata,
+            custom_plugins,
           }) as ADCSDK.Configuration,
       ),
     );