fluxion-ts 0.0.4

package/document/src/view/App.tsx

@@ -0,0 +1,304 @@
+import { CodeBlock } from './CodeBlock.js';
+import { Section } from './Section.js';
+
+const startCode = `# 1) 安装依赖
+pnpm install
+
+# 2) 启动 fluxion（默认读取 ./dynamicDirectory）
+pnpm dev
+
+# 3) 启动文档站点（当前页面）
+pnpm doc:dev`;
+
+const configCode = `{
+  "dynamicDirectory": "./dynamicDirectory",
+  "host": "127.0.0.1",
+  "port": 3000
+}`;
+
+const treeCode = `dynamicDirectory/
+├── aaa/
+│   ├── bb/
+│   │   ├── cc/index.mjs      # 动态路由 /aaa/bb/cc（优先）
+│   │   └── cc.mjs            # 动态路由 /aaa/bb/cc（次优先）
+│   ├── public/app.js         # 静态资源 /aaa/public/app.js
+│   └── page.html             # 静态资源 /aaa/page.html
+├── index.mjs                 # 动态路由 /
+└── _lib/
+    ├── tool.mjs              # 不可路由（_ 前缀目录）
+    └── helper.js             # 不可路由（_ 前缀目录）`;
+
+const handlerCode = `// dynamicDirectory/aaa/bb/cc/index.mjs
+export default function handler(req, res) {
+  res.statusCode = 200;
+  res.setHeader('content-type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify({
+    ok: true,
+    method: req.method,
+    url: req.url,
+  }));
+}`;
+
+const routeDecisionCode = `请求进入后，按以下顺序判定：
+
+1. 先匹配元接口 /_fluxion/*
+2. URL 解析与安全校验：
+   - 段不能为空、不能是 . 或 ..
+   - 段不能包含 / 或 \\
+   - 任意段以 _ 开头 => 直接 404
+3. 动态路由判定（仅 .mjs 作为 handler）：
+   - 先试 <path>/index.mjs
+   - 再试 <path>.mjs
+   - 命中后加载 default 导出并执行
+4. 若动态未命中，再判定静态文件：
+   - 仅 GET/HEAD
+   - .mjs 永不当静态文件返回
+   - 其他文件存在则直接返回
+5. 仍未命中 => 404`;
+
+const cacheCode = `handler 缓存键 = "mtimeMs:size"
+
+- 首次访问：import(file://...?.v=mtime:size)
+- 后续访问：
+  - mtime/size 未变化 -> 复用缓存函数
+  - mtime 或 size 变化 -> 重新 import 新版本
+
+这意味着：只要文件内容导致 mtime 或 size 变化，下一次请求就会热更新。`;
+
+const metaRoutesCode = `GET /_fluxion/routes
+
+返回示例：
+{
+  "routes": {
+    "handlers": [
+      {
+        "route": "/aaa/bb/cc",
+        "file": "aaa/bb/cc/index.mjs",
+        "version": "1740751930123.123:289"
+      }
+    ],
+    "staticFiles": [
+      {
+        "route": "/aaa/public/app.js",
+        "file": "aaa/public/app.js",
+        "version": "1740751930456.456:31"
+      }
+    ]
+  }
+}`;
+
+const healthzCode = `GET /_fluxion/healthz
+
+返回示例：
+{
+  "ok": true,
+  "now": 1740751930999
+}`;
+
+const uploadCode = `curl -X POST \
+  'http://127.0.0.1:3000/_fluxion/upload?filename=my-module.tar.gz' \
+  -H 'content-type: application/octet-stream' \
+  --data-binary @./my-module.tar.gz`;
+
+const uploadRuleCode = `上传仅支持：.tar / .tar.gz / .tgz
+
+解压后布局判定：
+
+A) 仅一个顶层目录
+   -> moduleName = 顶层目录名
+   -> 安装为 dynamicDirectory/<moduleName>
+
+B) 多个顶层项（文件或目录）
+   -> moduleName = 压缩包文件名（去扩展名）
+   -> 所有顶层项复制到 dynamicDirectory/<moduleName>
+
+C) 解压后没有可用内容
+   -> 400（Invalid archive structure）`;
+
+const requestMapCode = `访问路径 -> 结果
+
+/aaa/bb/cc         -> 查找 aaa/bb/cc/index.mjs，再查 aaa/bb/cc.mjs
+/aaa/public/app.js -> 若文件存在，作为静态文件返回
+/aaa/bb/cc.mjs     -> 不直接暴露源码，返回 404
+/_lib/x            -> _ 前缀目录，不路由，返回 404
+/_fluxion/routes   -> 元接口，返回当前路由快照`;
+
+export function App() {
+  return (
+    <div class="doc-page">
+      <div class="bg-glow bg-glow-left" />
+      <div class="bg-glow bg-glow-right" />
+
+      <header class="hero">
+        <p class="eyebrow">Fluxion 使用说明（中文版）</p>
+        <h1 class="hero-title">文件即路由：.mjs 动态处理，.js 静态返回</h1>
+        <p class="hero-copy">
+          Fluxion 是一个基于 Node.js HTTP 的元服务器。它不要求固定的 server/web 目录，直接以
+          <code class="inline-code">dynamicDirectory</code>
+          中的文件结构来决定路由行为。
+        </p>
+        <div class="hero-actions">
+          <a href="#quick-start" class="button button-primary">
+            快速开始
+          </a>
+          <a href="#decision" class="button button-ghost">
+            判定规则
+          </a>
+        </div>
+      </header>
+
+      <nav class="toc">
+        <a href="#quick-start">快速开始</a>
+        <a href="#layout">目录约定</a>
+        <a href="#decision">判定顺序</a>
+        <a href="#handler">动态加载</a>
+        <a href="#meta-api">元接口</a>
+        <a href="#upload">上传规则</a>
+        <a href="#examples">请求示例</a>
+      </nav>
+
+      <main class="content">
+        <Section id="quick-start" title="快速开始" lead="先跑起来，再按规则组织文件。">
+          <div class="grid-two">
+            <article class="panel">
+              <h3 class="panel-title">启动命令</h3>
+              <CodeBlock code={startCode} />
+            </article>
+            <article class="panel">
+              <h3 class="panel-title">核心配置</h3>
+              <p class="panel-note">
+                运行时配置等价于下面 JSON。默认值来自环境变量：
+                <code class="inline-code">DYNAMIC_DIRECTORY</code>、
+                <code class="inline-code">HOST</code>、
+                <code class="inline-code">PORT</code>。
+              </p>
+              <CodeBlock code={configCode} />
+            </article>
+          </div>
+        </Section>
+
+        <Section
+          id="layout"
+          title="目录约定"
+          lead="不再强制 server/web。所有内容都直接放在 dynamicDirectory 下。"
+        >
+          <div class="panel">
+            <CodeBlock code={treeCode} />
+            <ul class="check-list panel-note-list">
+              <li>
+                <code class="inline-code">.mjs</code>：作为动态 handler，必须
+                <code class="inline-code">export default (req, res) =&gt; {}</code>。
+              </li>
+              <li>
+                <code class="inline-code">.js</code>：作为静态资源返回（也是推荐的前端脚本后缀）。
+              </li>
+              <li>其他非 .mjs 文件（如 .html/.css/.json）也会按静态文件处理。</li>
+              <li>
+                目录名以 <code class="inline-code">_</code> 开头（如 <code class="inline-code">_lib/</code>）永不路由。
+              </li>
+            </ul>
+          </div>
+        </Section>
+
+        <Section
+          id="decision"
+          title="请求判定顺序（最重要）"
+          lead="同一个请求会严格按固定顺序处理，这决定了最终命中哪个文件。"
+        >
+          <div class="grid-two">
+            <article class="panel">
+              <h3 class="panel-title">判定流程</h3>
+              <CodeBlock code={routeDecisionCode} />
+            </article>
+            <article class="panel panel-warning">
+              <h3 class="panel-title">安全与保留规则</h3>
+              <ul class="warning-list">
+                <li>
+                  <code class="inline-code">/_fluxion/*</code> 是系统保留前缀，优先级最高。
+                </li>
+                <li>路径包含非法段或解码失败时，会直接返回 404。</li>
+                <li>
+                  <code class="inline-code">.mjs</code> 文件不会被当静态资源直接下载。
+                </li>
+                <li>
+                  <code class="inline-code">_</code> 前缀目录即使存在文件，也不会暴露路由。
+                </li>
+              </ul>
+            </article>
+          </div>
+        </Section>
+
+        <Section
+          id="handler"
+          title="动态加载与热更新"
+          lead="Fluxion 按 mtime + size 识别版本，避免重启进程。"
+        >
+          <div class="grid-two">
+            <article class="panel">
+              <h3 class="panel-title">Handler 写法</h3>
+              <CodeBlock code={handlerCode} />
+            </article>
+            <article class="panel panel-positive">
+              <h3 class="panel-title">缓存机制</h3>
+              <CodeBlock code={cacheCode} />
+            </article>
+          </div>
+        </Section>
+
+        <Section
+          id="meta-api"
+          title="元接口（Meta API）"
+          lead="用于观测路由、健康检查和上传部署。"
+        >
+          <div class="grid-two">
+            <article class="panel">
+              <h3 class="panel-title">GET /_fluxion/routes</h3>
+              <p class="panel-note">返回当前用于 diff 的完整快照对象。</p>
+              <CodeBlock code={metaRoutesCode} />
+            </article>
+            <article class="panel">
+              <h3 class="panel-title">GET /_fluxion/healthz</h3>
+              <p class="panel-note">健康检查接口，返回 ok 与当前时间戳。</p>
+              <CodeBlock code={healthzCode} />
+            </article>
+          </div>
+        </Section>
+
+        <Section
+          id="upload"
+          title="上传接口与解压判定"
+          lead="POST /_fluxion/upload 用于在线发布 tar 包，不支持 zip。"
+        >
+          <div class="grid-two">
+            <article class="panel">
+              <h3 class="panel-title">调用示例</h3>
+              <CodeBlock code={uploadCode} />
+              <p class="panel-note">
+                文件名可通过 query 参数 <code class="inline-code">filename</code> 或请求头
+                <code class="inline-code">x-fluxion-filename</code> 提供。
+              </p>
+            </article>
+            <article class="panel">
+              <h3 class="panel-title">解压判定规则</h3>
+              <CodeBlock code={uploadRuleCode} />
+            </article>
+          </div>
+        </Section>
+
+        <Section
+          id="examples"
+          title="访问示例速查"
+          lead="下面是最常见的路径到行为映射，便于快速排错。"
+        >
+          <div class="panel">
+            <CodeBlock code={requestMapCode} />
+          </div>
+        </Section>
+      </main>
+
+      <footer class="footer">
+        <p>Fluxion 文档页（kt.js + Vite）</p>
+      </footer>
+    </div>
+  );
+}

package/document/src/view/CodeBlock.tsx

@@ -0,0 +1,11 @@
+interface CodeBlockProps {
+  code: string;
+}
+
+export function CodeBlock(props: CodeBlockProps) {
+  return (
+    <pre class="code-block">
+      <code>{props.code}</code>
+    </pre>
+  );
+}

package/document/src/view/Section.tsx

@@ -0,0 +1,18 @@
+interface SectionProps {
+  id: string;
+  title: string;
+  lead: string;
+  children?: any;
+}
+
+export function Section(props: SectionProps) {
+  return (
+    <section id={props.id} class="doc-section">
+      <header class="section-header">
+        <h2 class="section-title">{props.title}</h2>
+        <p class="section-lead">{props.lead}</p>
+      </header>
+      {props.children}
+    </section>
+  );
+}

package/document/vite.config.ts

@@ -0,0 +1,23 @@
+import path from 'node:path';
+
+import { defineConfig } from 'vite';
+import ktjsx from '@ktjs/vite-plugin-ktjsx';
+
+const rootDir = import.meta.dirname;
+
+export default defineConfig({
+  root: rootDir,
+  build: {
+    outDir: path.join(rootDir, 'dist'),
+    emptyOutDir: true,
+  },
+  esbuild: {
+    jsx: 'automatic',
+    jsxImportSource: 'kt.js',
+  },
+  plugins: [ktjsx()],
+  server: {
+    port: 4173,
+    open: true,
+  },
+});

package/draft/vibe.md

@@ -0,0 +1,50 @@
+请以http包、findmyway包，制作一个非常简单的服务器，要求：
+
+1. 配置如下。
+
+```json
+{
+  "dynamicDirectory": "string",
+  "host": "string",
+  "port": "number"
+}
+```
+
+2. dynamicDirectory用来指定一个目录，这个目录下的代码结构为：
+
+```text
+dynamicDirectory
+└─somemodule
+  ├── server
+  │   ├── index.js
+  └── web
+      ├── index.html
+      └── style.css/main.js ...
+```
+
+3. dynamicDirectory是核心。服务器fs.watch这个目录.当这个目录下的文件变化，会触发diff。对于新增的somemodule，会将web下的内容注册为
+   router `/somemodule/...`,而server的路由注册为`/somemodule/api`。 不见了的文件夹，则删除这两个路由。你暂时不需要处理web静态资源问题，先把路由注册和删除做好。
+
+4. 在开始的时候，服务器会扫描dynamicDirectory下的所有somemodule，并注册路由。
+5. 增加一个输出jsonline日志的机制。不过，路由的注册可以用oneline那种日志，比如
+
+```
+[timestamp] [INFO] Registered   route: /somemodule/
+[timestamp] [INFO] Unregistered route: /somemodule/
+```
+
+---
+
+你记住现在我们的项目叫fluxion，可以写在AGENTS.md里。我希望的是，假如我访问了/aaa/bb/cc这个路由，那么fluxion会寻找dynamicDirectory下的aaa文件夹里的server里的bb文件夹里的cc.js文件或者cc/index.js(优先)文件，以里面的函数作为handler来处理这个请求。这个函数的签名是`(req, res) => {}`，你可以在里面写任何逻辑来处理请求和响应。我不知道await import(xxx)能否胜任以及它缓存是否原生，或者是否有性能问题。我希望的是加载这个js文件的default导出。
+请你评估这个方案
+
+---
+
+worker优化：
+1、直接从worker返回你说的buffer来限制大小、判定,减少拷贝传输成本避免内存膨胀；
+2、mjs编写的时候可以选择自己需要远程的什么对象，比如{handler,db:['pg','xxxDB']}等；handler里会传入第三个入参context来包含这些功能;
+3、实现workerstrategy这个方案。
+
+---
+
+现在，请你把db config的interface保留下来。我已经删除了pg和mysql2依赖，因为它们不应该这样写，它们应该在用户npm install fluxion后由用户自行安装引入，fluxion只做配置传递。为不失一般性，mjs返回的不再是db:{key:value}，而是modules:[{module:'mysql2',injectKey:"mydb",factory:(...)=>{ 这里返回最终注入context的对象}}]。而这个modules数组将会传输到worker，其中，factory因为是函数，所以会tostring后传输，传输到worker内部后再new Function的形式绕回来,而最终这个数据库链接实例会出现在context.mydb。

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "fluxion-ts",
+  "version": "0.0.4",
+  "author": {
+    "name": "Kasukabe Tsumugi",
+    "email": "futami16237@gmail.com"
+  },
+  "purpose": "npm",
+  "description": "Fluxion is able to start a server that can dynamically load routers and js files. It is designed to be used to replace PHP",
+  "description_zh": "Fluxion可以启动一个能够动态加载路由和js文件的服务器，旨在替代PHP",
+  "type": "module",
+  "homepage": "https://github.com/baendlorel/fluxion#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baendlorel/fluxion"
+  },
+  "keywords": [
+    "framework",
+    "server",
+    "typescript",
+    "javascript"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@ktjs/ts-plugin": "^0.1.13",
+    "@ktjs/vite-plugin-ktjsx": "^0.4.3",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^25.3.2",
+    "axios": "^1.13.6",
+    "kt.js": "^0.31.4",
+    "oxlint": "^1.50.0",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.3",
+    "rollup": "4.59.0",
+    "rollup-plugin-conditional-compilation": "^2.1.2",
+    "rollup-plugin-dts": "^6.3.0",
+    "rollup-plugin-func-macro": "^1.2.2",
+    "tslib": "^2.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "find-my-way": "^9.5.0"
+  },
+  "scripts": {
+    "start": "code-server --bind-addr 0.0.0.0:3000 /app/dynamic && node /app/index.js",
+    "dev": "tsx ./src/index.ts --watch",
+    "exp": "vite dev --config document/vite.config.ts",
+    "lines": "tsx ./scripts/lines.ts",
+    "doc:dev": "vite --config document/vite.config.ts",
+    "doc:build": "vite build --config document/vite.config.ts",
+    "image": "tsx ./scripts/build-image.ts",
+    "build": "rollup -c",
+    "pub": "tsx ./scripts/publish.ts",
+    "test": "vitest",
+    "lint": "oxlint ."
+  }
+}

package/rollup.config.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+import { rimraf } from 'rimraf';
+import resolve from '@rollup/plugin-node-resolve';
+import json from '@rollup/plugin-json';
+import commonjs from '@rollup/plugin-commonjs';
+import typescript from '@rollup/plugin-typescript';
+import terser from '@rollup/plugin-terser';
+import replace from '@rollup/plugin-replace';
+import dts from 'rollup-plugin-dts';
+
+export default async (_commandLineArgs) => {
+  const libPath = import.meta.dirname;
+
+  await rimraf(path.join(libPath, 'dist'));
+  return [
+    {
+      input: path.join(libPath, 'src', 'index.ts'),
+      output: [
+        {
+          file: path.join(libPath, 'dist', 'index.mjs'),
+          format: 'esm', // ES module output
+          sourcemap: true,
+        },
+      ],
+      plugins: [
+        typescript({ tsconfig: './tsconfig.json' }),
+        resolve(),
+        json(),
+        commonjs(),
+        replace(replaceOpts(libPath)),
+        void terser(),
+      ].filter(Boolean),
+      external: [/^node:/],
+    },
+    {
+      input: path.join(libPath, 'src', 'index.ts'),
+      output: [{ file: path.join(libPath, 'dist', 'index.d.ts'), format: 'es' }],
+      plugins: [dts({ tsconfig: './tsconfig.json' })],
+      external: [/^node:/],
+    },
+  ];
+};
+
+// #region replace options
+
+export const globalDefines = {
+  'process.env.NODE_ENV': '"production"',
+};
+
+export function replaceOpts(packagePath) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(packagePath, 'package.json'), 'utf-8'));
+  function formatDateFull(dt = new Date()) {
+    const y = dt.getFullYear();
+    const m = String(dt.getMonth() + 1).padStart(2, '0');
+    const d = String(dt.getDate()).padStart(2, '0');
+    const hh = String(dt.getHours()).padStart(2, '0');
+    const mm = String(dt.getMinutes()).padStart(2, '0');
+    const ss = String(dt.getSeconds()).padStart(2, '0');
+    const ms = String(dt.getMilliseconds()).padStart(3, '0');
+    return `${y}.${m}.${d} ${hh}:${mm}:${ss}.${ms}`;
+  }
+
+  const __KEBAB_NAME__ = pkg.name.replace('rollup-plugin-', '');
+  const __VERSION__ = pkg.version;
+  const __NAME__ = __KEBAB_NAME__.replace(/(^|-)(\w)/g, (_, __, c) => c.toUpperCase());
+
+  const __PKG_INFO__ = `## About
+ * @package ${__NAME__}
+ * @author ${pkg.author.name} <${pkg.author.email}>
+ * @version ${pkg.version} (Last Update: ${formatDateFull()})
+ * @license ${pkg.license}
+ * @link ${pkg.repository.url}
+ * @link https://baendlorel.github.io/ Welcome to my site!
+ * @description ${pkg.description.replace(/\n/g, '\n * \n * ')}
+ * @copyright Copyright (c) ${new Date().getFullYear()} ${pkg.author.name}. All rights reserved.`;
+
+  return {
+    preventAssignment: true,
+    delimiters: ['', ''],
+    values: {
+      __IS_DEV__: 'false',
+      __NAME__,
+      __KEBAB_NAME__,
+      __PKG_INFO__,
+      __VERSION__,
+
+      // global flags
+      ...globalDefines,
+
+      // global error/warn/debug
+      "$throw('": `throw new Error('[${__NAME__} error] `,
+      '$throw(`': `throw new Error(\`[${__NAME__} error] `,
+      '$throw("': `throw new Error("[${__NAME__} error] `,
+      '$warn(': `console.warn('[${__NAME__} warn]',`,
+      '$error(': `console.error('[${__NAME__} error]',`,
+      '$debug(': `console.debug('[${__NAME__} debug]',`,
+    },
+  };
+}
+// #endregion

package/scripts/build-image.ts

@@ -0,0 +1,13 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { bumpVersion } from './bump-version';
+
+const pkgPath = path.resolve(import.meta.dirname, '..', '.image.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { name: string; version: string };
+const imageName = `${pkg.name}:${pkg.version}`;
+
+execSync('pnpm build', { stdio: 'inherit' });
+execSync(`docker build -t ${imageName} .`, { stdio: 'inherit' });
+
+bumpVersion(pkgPath);

package/scripts/bump-version.ts

@@ -0,0 +1,12 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export function bumpVersion(pkgPath: string = path.resolve(import.meta.dirname, '..', 'package.json')) {
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { name: string; version: string };
+  const [major, minor, patch] = pkg.version.split('.').map(Number);
+  const nextVersion = [major, minor, patch + 1].join('.');
+  const oldVersion = pkg.version;
+  pkg.version = nextVersion;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  console.log(`Bumped version: ${oldVersion} -> ${nextVersion}`);
+}