@zhin.js/middleware 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @zhin.js/middleware
+
+Zhin Plugin Runtime 的 Middleware Feature。它从 `middlewares/**/*.ts` 发现定义，并按
+phase、order、Plugin topology 与 capability identity 形成稳定执行链。
+
+```ts
+import { defineMiddleware } from '@zhin.js/middleware';
+
+export default defineMiddleware({
+  phase: 'before-dispatch',
+  async handle(_context, next) { await next(); },
+});
+```
+
+Middleware 不直接持有 Root 或运行时 registry；每次执行使用同一 generation snapshot，
+更新时由 Feature Slot 原子替换。
+
+验证：`pnpm --filter @zhin.js/middleware test && pnpm --filter @zhin.js/middleware build`。
+
+生命周期与 HMR 说明见 [目标架构](../../docs/target-architecture.md)。

package/lib/definition.d.ts

@@ -0,0 +1,22 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+declare const middlewareBrand: "zhin.middleware/1";
+export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
+export type MiddlewareTarget = 'inbound' | 'outbound';
+export type MiddlewareNext = () => Promise<void>;
+export interface MiddlewareContext<TInput = unknown, TConfig = unknown> extends CapabilityContext<TConfig> {
+    readonly input: TInput;
+}
+export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown> {
+    readonly $feature: typeof middlewareBrand;
+    readonly phase: MiddlewarePhase;
+    readonly target: MiddlewareTarget;
+    readonly order: number;
+    handle(context: MiddlewareContext<TInput, TConfig>, next: MiddlewareNext): void | Promise<void>;
+}
+export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: Omit<MiddlewareDefinition<TInput, TConfig>, '$feature' | 'phase' | 'target' | 'order'> & {
+    readonly phase?: MiddlewarePhase;
+    readonly target?: MiddlewareTarget;
+    readonly order?: number;
+}): Readonly<MiddlewareDefinition<TInput, TConfig>>;
+export declare function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition;
+export {};

package/lib/definition.js

@@ -0,0 +1,33 @@
+const middlewareBrand = 'zhin.middleware/1';
+export function defineMiddleware(definition) {
+    if (typeof definition.handle !== 'function') {
+        throw new TypeError('Middleware handle must be a function');
+    }
+    const phase = definition.phase ?? 'before-dispatch';
+    if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
+        throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
+    }
+    const target = definition.target ?? 'inbound';
+    if (target !== 'inbound' && target !== 'outbound') {
+        throw new TypeError(`Invalid Middleware target: ${String(target)}`);
+    }
+    const order = definition.order ?? 0;
+    if (!Number.isSafeInteger(order))
+        throw new TypeError('Middleware order must be a safe integer');
+    return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order });
+}
+export function parseMiddlewareDefinition(value) {
+    if (!value || typeof value !== 'object')
+        throw invalidMiddleware();
+    const definition = value;
+    if (definition.$feature !== middlewareBrand
+        || typeof definition.handle !== 'function'
+        || (definition.phase !== 'before-dispatch' && definition.phase !== 'after-dispatch')
+        || (definition.target !== 'inbound' && definition.target !== 'outbound')
+        || !Number.isSafeInteger(definition.order))
+        throw invalidMiddleware();
+    return definition;
+}
+function invalidMiddleware() {
+    return new TypeError('Middleware module must default-export defineMiddleware(...)');
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './middleware-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './middleware-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/middleware-index.d.ts

@@ -0,0 +1,19 @@
+import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { MiddlewareDefinition, MiddlewareNext, MiddlewarePhase, MiddlewareTarget } from './definition.js';
+export interface MiddlewareDescriptor {
+    readonly owner: PluginId;
+    readonly name: string;
+    readonly source: string;
+    readonly phase: MiddlewarePhase;
+    readonly target: MiddlewareTarget;
+    readonly order: number;
+}
+export declare class MiddlewareIndex {
+    #private;
+    private readonly snapshot;
+    readonly $projection: "zhin.middleware-index/1";
+    constructor(slots: readonly Readonly<CapabilitySlot<MiddlewareDefinition>>[], snapshot: RuntimeSnapshot);
+    list(): readonly MiddlewareDescriptor[];
+    run<TInput>(input: TInput, terminal?: MiddlewareNext, target?: MiddlewareTarget): Promise<void>;
+}
+export declare function isMiddlewareIndex(value: unknown): value is MiddlewareIndex;

package/lib/middleware-index.js

@@ -0,0 +1,66 @@
+import { createCapabilityContext } from '@zhin.js/feature-kit';
+export class MiddlewareIndex {
+    snapshot;
+    $projection = 'zhin.middleware-index/1';
+    #records;
+    constructor(slots, snapshot) {
+        this.snapshot = snapshot;
+        const topology = topologyOrder(snapshot);
+        this.#records = Object.freeze(slots.map((slot) => Object.freeze({
+            owner: slot.owner,
+            name: slot.localName,
+            source: slot.source,
+            phase: slot.definition.phase,
+            target: slot.definition.target,
+            order: slot.definition.order,
+            slot,
+        })).sort((left, right) => compareMiddleware(left, right, topology)));
+    }
+    list() {
+        return this.#records.map(({ slot: _slot, ...descriptor }) => descriptor);
+    }
+    async run(input, terminal = async () => undefined, target = 'inbound') {
+        const records = this.#records.filter((record) => record.target === target);
+        let cursor = -1;
+        const dispatch = async (index) => {
+            if (index <= cursor)
+                throw new Error('Middleware next() called more than once');
+            cursor = index;
+            const record = records[index];
+            if (!record)
+                return terminal();
+            const context = Object.freeze({
+                ...createCapabilityContext(this.snapshot, record.owner),
+                input,
+            });
+            await record.slot.definition.handle(context, () => dispatch(index + 1));
+        };
+        await dispatch(0);
+    }
+}
+export function isMiddlewareIndex(value) {
+    return !!value && typeof value === 'object'
+        && value.$projection === 'zhin.middleware-index/1';
+}
+function compareMiddleware(left, right, topology) {
+    return phaseOrder(left.phase) - phaseOrder(right.phase)
+        || left.order - right.order
+        || (topology.get(left.owner) ?? Number.MAX_SAFE_INTEGER)
+            - (topology.get(right.owner) ?? Number.MAX_SAFE_INTEGER)
+        || left.slot.id.localeCompare(right.slot.id);
+}
+function phaseOrder(phase) {
+    return phase === 'before-dispatch' ? 0 : 1;
+}
+function topologyOrder(snapshot) {
+    const result = new Map();
+    const visit = (owner) => {
+        if (result.has(owner))
+            return;
+        result.set(owner, result.size);
+        for (const child of snapshot.tree.get(owner)?.children ?? [])
+            visit(child);
+    };
+    visit(snapshot.root);
+    return result;
+}

package/lib/provider.d.ts

@@ -0,0 +1,5 @@
+import { MiddlewareIndex } from './middleware-index.js';
+export declare const middlewareFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+declare const middlewareFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").MiddlewareDefinition<unknown, unknown>, MiddlewareIndex>>;
+export { middlewareFeature };
+export default middlewareFeature;

package/lib/provider.js

@@ -0,0 +1,23 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { parseMiddlewareDefinition } from './definition.js';
+import { MiddlewareIndex } from './middleware-index.js';
+export const middlewareFeatureId = featureId('zhin.middleware');
+const middlewareFeature = defineFeatureProvider({
+    protocol: 1,
+    id: middlewareFeatureId,
+    authoring: {
+        conventions: [typeScriptModules({
+                id: 'middlewares-ts',
+                directory: 'middlewares',
+            })],
+        validate: parseMiddlewareDefinition,
+    },
+    runtime: {
+        project(slots, context) {
+            return { value: new MiddlewareIndex(slots, context.snapshot) };
+        },
+    },
+});
+export { middlewareFeature };
+export default middlewareFeature;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhin.js/middleware",
+  "version": "1.0.0",
+  "description": "Convention-based Middleware Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/feature-kit": "1.0.0",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/middleware"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/middleware/tests"
+  }
+}

package/src/definition.ts

@@ -0,0 +1,63 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+
+const middlewareBrand = 'zhin.middleware/1' as const;
+
+export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
+export type MiddlewareTarget = 'inbound' | 'outbound';
+export type MiddlewareNext = () => Promise<void>;
+
+export interface MiddlewareContext<TInput = unknown, TConfig = unknown>
+  extends CapabilityContext<TConfig> {
+  readonly input: TInput;
+}
+
+export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown> {
+  readonly $feature: typeof middlewareBrand;
+  readonly phase: MiddlewarePhase;
+  readonly target: MiddlewareTarget;
+  readonly order: number;
+  handle(context: MiddlewareContext<TInput, TConfig>, next: MiddlewareNext): void | Promise<void>;
+}
+
+export function defineMiddleware<TInput = unknown, TConfig = unknown>(
+  definition: Omit<
+    MiddlewareDefinition<TInput, TConfig>,
+    '$feature' | 'phase' | 'target' | 'order'
+  > & {
+    readonly phase?: MiddlewarePhase;
+    readonly target?: MiddlewareTarget;
+    readonly order?: number;
+  },
+): Readonly<MiddlewareDefinition<TInput, TConfig>> {
+  if (typeof definition.handle !== 'function') {
+    throw new TypeError('Middleware handle must be a function');
+  }
+  const phase = definition.phase ?? 'before-dispatch';
+  if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
+    throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
+  }
+  const target = definition.target ?? 'inbound';
+  if (target !== 'inbound' && target !== 'outbound') {
+    throw new TypeError(`Invalid Middleware target: ${String(target)}`);
+  }
+  const order = definition.order ?? 0;
+  if (!Number.isSafeInteger(order)) throw new TypeError('Middleware order must be a safe integer');
+  return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order });
+}
+
+export function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition {
+  if (!value || typeof value !== 'object') throw invalidMiddleware();
+  const definition = value as Partial<MiddlewareDefinition>;
+  if (
+    definition.$feature !== middlewareBrand
+    || typeof definition.handle !== 'function'
+    || (definition.phase !== 'before-dispatch' && definition.phase !== 'after-dispatch')
+    || (definition.target !== 'inbound' && definition.target !== 'outbound')
+    || !Number.isSafeInteger(definition.order)
+  ) throw invalidMiddleware();
+  return definition as MiddlewareDefinition;
+}
+
+function invalidMiddleware(): TypeError {
+  return new TypeError('Middleware module must default-export defineMiddleware(...)');
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './middleware-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/src/middleware-index.ts

@@ -0,0 +1,100 @@
+import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { createCapabilityContext } from '@zhin.js/feature-kit';
+import type {
+  MiddlewareContext,
+  MiddlewareDefinition,
+  MiddlewareNext,
+  MiddlewarePhase,
+  MiddlewareTarget,
+} from './definition.js';
+
+export interface MiddlewareDescriptor {
+  readonly owner: PluginId;
+  readonly name: string;
+  readonly source: string;
+  readonly phase: MiddlewarePhase;
+  readonly target: MiddlewareTarget;
+  readonly order: number;
+}
+
+interface MiddlewareRecord extends MiddlewareDescriptor {
+  readonly slot: Readonly<CapabilitySlot<MiddlewareDefinition>>;
+}
+
+export class MiddlewareIndex {
+  readonly $projection = 'zhin.middleware-index/1' as const;
+  readonly #records: readonly MiddlewareRecord[];
+
+  constructor(
+    slots: readonly Readonly<CapabilitySlot<MiddlewareDefinition>>[],
+    private readonly snapshot: RuntimeSnapshot,
+  ) {
+    const topology = topologyOrder(snapshot);
+    this.#records = Object.freeze(slots.map((slot) => Object.freeze({
+      owner: slot.owner,
+      name: slot.localName,
+      source: slot.source,
+      phase: slot.definition.phase,
+      target: slot.definition.target,
+      order: slot.definition.order,
+      slot,
+    })).sort((left, right) => compareMiddleware(left, right, topology)));
+  }
+
+  list(): readonly MiddlewareDescriptor[] {
+    return this.#records.map(({ slot: _slot, ...descriptor }) => descriptor);
+  }
+
+  async run<TInput>(
+    input: TInput,
+    terminal: MiddlewareNext = async () => undefined,
+    target: MiddlewareTarget = 'inbound',
+  ): Promise<void> {
+    const records = this.#records.filter((record) => record.target === target);
+    let cursor = -1;
+    const dispatch = async (index: number): Promise<void> => {
+      if (index <= cursor) throw new Error('Middleware next() called more than once');
+      cursor = index;
+      const record = records[index];
+      if (!record) return terminal();
+      const context: MiddlewareContext<TInput> = Object.freeze({
+        ...createCapabilityContext(this.snapshot, record.owner),
+        input,
+      });
+      await record.slot.definition.handle(context, () => dispatch(index + 1));
+    };
+    await dispatch(0);
+  }
+}
+
+export function isMiddlewareIndex(value: unknown): value is MiddlewareIndex {
+  return !!value && typeof value === 'object'
+    && (value as { readonly $projection?: unknown }).$projection === 'zhin.middleware-index/1';
+}
+
+function compareMiddleware(
+  left: MiddlewareRecord,
+  right: MiddlewareRecord,
+  topology: ReadonlyMap<PluginId, number>,
+): number {
+  return phaseOrder(left.phase) - phaseOrder(right.phase)
+    || left.order - right.order
+    || (topology.get(left.owner) ?? Number.MAX_SAFE_INTEGER)
+      - (topology.get(right.owner) ?? Number.MAX_SAFE_INTEGER)
+    || left.slot.id.localeCompare(right.slot.id);
+}
+
+function phaseOrder(phase: MiddlewarePhase): number {
+  return phase === 'before-dispatch' ? 0 : 1;
+}
+
+function topologyOrder(snapshot: RuntimeSnapshot): ReadonlyMap<PluginId, number> {
+  const result = new Map<PluginId, number>();
+  const visit = (owner: PluginId): void => {
+    if (result.has(owner)) return;
+    result.set(owner, result.size);
+    for (const child of snapshot.tree.get(owner)?.children ?? []) visit(child);
+  };
+  visit(snapshot.root);
+  return result;
+}

package/src/provider.ts

@@ -0,0 +1,26 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { parseMiddlewareDefinition } from './definition.js';
+import { MiddlewareIndex } from './middleware-index.js';
+
+export const middlewareFeatureId = featureId('zhin.middleware');
+
+const middlewareFeature = defineFeatureProvider({
+  protocol: 1,
+  id: middlewareFeatureId,
+  authoring: {
+    conventions: [typeScriptModules({
+      id: 'middlewares-ts',
+      directory: 'middlewares',
+    })],
+    validate: parseMiddlewareDefinition,
+  },
+  runtime: {
+    project(slots, context) {
+      return { value: new MiddlewareIndex(slots, context.snapshot) };
+    },
+  },
+});
+
+export { middlewareFeature };
+export default middlewareFeature;