@jayfong/x-server 2.119.0 → 3.1.1

package/lib/index.mjs

@@ -0,0 +1,45 @@
+import { ctxStorage } from "./core/ctx_storage.mjs";
+import { defineBus } from "./core/define_bus.mjs";
+import { defineCron } from "./core/define_cron.mjs";
+import { HttpError } from "./core/http_error.mjs";
+import { DisposeService } from "./services/dispose.mjs";
+import { HttpRedirect } from "./core/http_redirect.mjs";
+import { x } from "./x.mjs";
+import { HandlerMethodToHttpMethod } from "./core/http_method.mjs";
+import { Server } from "./core/server.mjs";
+import { Handler } from "./core/handler.mjs";
+import { defineHandler, defineHandlerANY, defineHandlerFILE, defineHandlerGET, defineHandlerXML } from "./core/define_handler.mjs";
+import { defineHook } from "./core/define_hook.mjs";
+import { defineServer } from "./core/define_server.mjs";
+import { defineSliceTask, defineTask } from "./core/define_task.mjs";
+import { getHandlerUrl } from "./core/get_handler_url.mjs";
+import { HttpRequestHeader, HttpResponseHeader } from "./core/http_header.mjs";
+import { CompressPlugin } from "./plugins/compress.mjs";
+import { CookiePlugin } from "./plugins/cookie.mjs";
+import { CorsPlugin } from "./plugins/cors.mjs";
+import { FileParserPlugin } from "./plugins/file_parser.mjs";
+import { FormBodyParserPlugin } from "./plugins/form_body_parser.mjs";
+import { WsParserPlugin } from "./plugins/ws_parser.mjs";
+import { XmlParserPlugin } from "./plugins/xml_parser.mjs";
+import { AiService } from "./services/ai.mjs";
+import { CacheService } from "./services/cache.mjs";
+import { CaptchaService } from "./services/captcha.mjs";
+import { CryptoService } from "./services/crypto.mjs";
+import { DbValueService } from "./services/db_value.mjs";
+import { DingtalkService } from "./services/dingtalk.mjs";
+import { EmojiService } from "./services/emoji.mjs";
+import { FileStoreService } from "./services/file_store.mjs";
+import { HtmlService } from "./services/html.mjs";
+import { JwtService } from "./services/jwt.mjs";
+import { LogService } from "./services/log.mjs";
+import { MailService } from "./services/mail.mjs";
+import { PayService } from "./services/pay.mjs";
+import { RandomService } from "./services/random.mjs";
+import { RateLimitService } from "./services/rate_limit.mjs";
+import { RedisService } from "./services/redis.mjs";
+import { SensitiveWordsService } from "./services/sensitive_words.mjs";
+import { SmsService } from "./services/sms.mjs";
+import "./x_init.mjs";
+import "./exports.mjs";
+export * from "@a/x/models";
+export { AiService, CacheService, CaptchaService, CompressPlugin, CookiePlugin, CorsPlugin, CryptoService, DbValueService, DingtalkService, DisposeService, EmojiService, FileParserPlugin, FileStoreService, FormBodyParserPlugin, Handler, HandlerMethodToHttpMethod, HtmlService, HttpError, HttpRedirect, HttpRequestHeader, HttpResponseHeader, JwtService, LogService, MailService, PayService, RandomService, RateLimitService, RedisService, SensitiveWordsService, Server, SmsService, WsParserPlugin, XmlParserPlugin, ctxStorage, defineBus, defineCron, defineHandler, defineHandlerANY, defineHandlerFILE, defineHandlerGET, defineHandlerXML, defineHook, defineServer, defineSliceTask, defineTask, getHandlerUrl, x };

package/lib/plugins/base.d.mts

@@ -0,0 +1,4 @@
+import { FastifyInstance } from "fastify";
+export interface BasePlugin {
+  readonly register: (fastify: FastifyInstance<any, any, any, any, any>) => void;
+}

package/lib/plugins/compress.d.mts

@@ -0,0 +1,12 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { FastifyCompressOptions } from "@fastify/compress";
+export interface CompressPluginOptions extends FastifyCompressOptions {}
+/**
+ * 响应压缩插件
+ */
+export declare class CompressPlugin implements BasePlugin {
+  private options?;
+  constructor(options?: CompressPluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/compress.mjs

@@ -0,0 +1,15 @@
+import FastifyCompress from "@fastify/compress";
+// src/plugins/compress.ts
+/**
+* 响应压缩插件
+*/
+var CompressPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		fastify.register(FastifyCompress, this.options ?? {});
+	}
+};
+export { CompressPlugin };

package/lib/plugins/cookie.d.mts

@@ -0,0 +1,12 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { FastifyCookieOptions } from "@fastify/cookie";
+export interface CookiePluginOptions extends FastifyCookieOptions {}
+/**
+ * Cookie 支持插件
+ */
+export declare class CookiePlugin implements BasePlugin {
+  private options?;
+  constructor(options?: CookiePluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/cookie.mjs

@@ -0,0 +1,15 @@
+import FastifyCookie from "@fastify/cookie";
+// src/plugins/cookie.ts
+/**
+* Cookie 支持插件
+*/
+var CookiePlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		fastify.register(FastifyCookie, this.options ?? {});
+	}
+};
+export { CookiePlugin };

package/lib/plugins/cors.d.mts

@@ -0,0 +1,22 @@
+import { BasePlugin } from "./base.mjs";
+import { MsValue } from "vtils";
+import { FastifyInstance } from "fastify";
+import { FastifyCorsOptions } from "@fastify/cors";
+export interface CorsPluginOptions extends FastifyCorsOptions {
+  /**
+   * 允许的来源，支持位于开头的 * 通配符
+   */
+  allow: string[];
+  /**
+   * 预检请求缓存时长
+   */
+  ttl: MsValue;
+}
+/**
+ * CORS 支持插件
+ */
+export declare class CorsPlugin implements BasePlugin {
+  private options;
+  constructor(options: CorsPluginOptions);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/cors.mjs

@@ -0,0 +1,34 @@
+import { memoize, ms, omitStrict } from "vtils";
+import FastifyCors from "@fastify/cors";
+// src/plugins/cors.ts
+/**
+* CORS 支持插件
+*/
+var CorsPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		const allows = this.options.allow.map((item) => ({
+			type: item === "*" ? "all" : item.startsWith("*.") ? "endsWith" : "equal",
+			domain: item.startsWith("*.") ? item.replace("*.", ".") : item
+		}));
+		const allowAll = allows.length === 1 && allows[0].type === "all";
+		const check = memoize((origin) => {
+			let i = origin.indexOf(":");
+			let j = origin.indexOf(":", i + 1);
+			i += 3;
+			j = j === -1 ? origin.length : j;
+			const domain = origin.substring(i, j);
+			return allows.some((item) => item.type === "equal" ? domain === item.domain : domain.endsWith(item.domain));
+		});
+		fastify.register(FastifyCors, {
+			origin: (origin, cb) => allowAll ? cb(null, true) : cb(null, origin ? check(origin) : true),
+			maxAge: ms(this.options.ttl, true),
+			exposedHeaders: ["x-trace-id"],
+			...omitStrict(this.options, ["allow", "ttl"])
+		});
+	}
+};
+export { CorsPlugin };

package/lib/plugins/file_parser.d.mts

@@ -0,0 +1,15 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { FastifyMultipartOptions, MultipartFile } from "@fastify/multipart";
+export interface FileParserPluginOptions extends FastifyMultipartOptions {}
+/**
+ * file 解析器插件
+ *
+ * 注意：默认文件大小限制 1MB
+ */
+export declare class FileParserPlugin implements BasePlugin {
+  private options?;
+  constructor(options?: FileParserPluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}
+export type { MultipartFile };

package/lib/plugins/file_parser.mjs

@@ -0,0 +1,24 @@
+import { bytes } from "vtils";
+import FastifyMultipart from "@fastify/multipart";
+// src/plugins/file_parser.ts
+/**
+* file 解析器插件
+*
+* 注意：默认文件大小限制 1MB
+*/
+var FileParserPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		fastify.register(FastifyMultipart, {
+			...this.options,
+			limits: {
+				fileSize: bytes(1, "MB"),
+				...this.options?.limits
+			}
+		});
+	}
+};
+export { FileParserPlugin };

package/lib/plugins/form_body_parser.d.mts

@@ -0,0 +1,12 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { FastifyFormbodyOptions } from "@fastify/formbody";
+export interface FormBodyParserPluginOptions extends FastifyFormbodyOptions {}
+/**
+ * POST application/x-www-form-urlencoded 解析器插件
+ */
+export declare class FormBodyParserPlugin implements BasePlugin {
+  private options?;
+  constructor(options?: FormBodyParserPluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/form_body_parser.mjs

@@ -0,0 +1,15 @@
+import FastifyFormBody from "@fastify/formbody";
+// src/plugins/form_body_parser.ts
+/**
+* POST application/x-www-form-urlencoded 解析器插件
+*/
+var FormBodyParserPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		fastify.register(FastifyFormBody, this.options || {});
+	}
+};
+export { FormBodyParserPlugin };

package/lib/plugins/ws_parser.d.mts

@@ -0,0 +1,12 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { WebsocketPluginOptions } from "@fastify/websocket";
+export interface WsParserPluginOptions extends WebsocketPluginOptions {}
+/**
+ * websocket 解析器插件
+ */
+export declare class WsParserPlugin implements BasePlugin {
+  private options?;
+  constructor(options?: WsParserPluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/ws_parser.mjs

@@ -0,0 +1,15 @@
+import FastifyWebsocket from "@fastify/websocket";
+// src/plugins/ws_parser.ts
+/**
+* websocket 解析器插件
+*/
+var WsParserPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		fastify.register(FastifyWebsocket, this.options ?? {});
+	}
+};
+export { WsParserPlugin };

package/lib/plugins/xml_parser.d.mts

@@ -0,0 +1,19 @@
+import { BasePlugin } from "./base.mjs";
+import { FastifyInstance } from "fastify";
+import { X2jOptions } from "fast-xml-parser";
+export interface XmlParserPluginOptions extends Partial<X2jOptions> {
+  /**
+   * 要处理的 `Content-Type`
+   */
+  contentType?: string | RegExp | string[];
+}
+/**
+ * XML 解析器插件
+ *
+ * 底层解析器是 [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser)
+ */
+export declare class XmlParserPlugin implements BasePlugin {
+  private options?;
+  constructor(options?: XmlParserPluginOptions | undefined);
+  register(fastify: FastifyInstance<any, any, any, any, any>): void;
+}

package/lib/plugins/xml_parser.mjs

@@ -0,0 +1,40 @@
+import { XMLParser } from "fast-xml-parser";
+// src/plugins/xml_parser.ts
+/**
+* XML 解析器插件
+*
+* 底层解析器是 [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser)
+*/
+var XmlParserPlugin = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	register(fastify) {
+		const { contentType = ["text/xml", "application/xml"], ...parseOptions } = this.options || {};
+		const xmlParser = new XMLParser(parseOptions);
+		fastify.addContentTypeParser(contentType, (_req, payload, done) => {
+			let body = "";
+			const handleError = (err) => done(err);
+			const handleData = (data) => body += data;
+			const handleEnd = () => {
+				let data;
+				let err;
+				try {
+					data = xmlParser.parse(body);
+				} catch (_err) {
+					err = _err;
+				}
+				payload.removeListener("error", handleError);
+				payload.removeListener("data", handleData);
+				payload.removeListener("end", handleEnd);
+				if (err) done(err);
+				else done(null, data);
+			};
+			payload.on("error", handleError);
+			payload.on("data", handleData);
+			payload.on("end", handleEnd);
+		});
+	}
+};
+export { XmlParserPlugin };

package/lib/services/ai.d.mts

@@ -0,0 +1,31 @@
+import { BaseService } from "./base.mjs";
+import { PartialBy } from "vtils/types";
+export type AiServiceOptions = {
+  /** 基础路径，如: https://dashscope.aliyuncs.com/compatible-mode/v1 */
+  baseUrl: string;
+  /** API密钥，如: sk-xxx */
+  apiKey: string;
+  /** 模型名称，如: deepseek-v3.1 */
+  model: string;
+  /** 额外请求头 */
+  headers?: Record<string, string>;
+};
+export type AiServiceAskPayload = AiServiceOptions & {
+  prompt?: string;
+  question: string;
+};
+export type AiServiceAskResult = {
+  answer: string;
+};
+export declare class AiService implements BaseService {
+  private options;
+  serviceName: string;
+  static ask(payload: AiServiceAskPayload): Promise<AiServiceAskResult>;
+  constructor(options: AiServiceOptions);
+  ask(payload: PartialBy<AiServiceAskPayload, keyof AiServiceOptions>): Promise<AiServiceAskResult>;
+}
+declare module '../x.mjs' {
+  interface X {
+    ai: AiService;
+  }
+}

package/lib/services/ai.mjs

@@ -0,0 +1,44 @@
+import { xr } from "@jayfong/x-request";
+import { ms } from "vtils";
+// src/services/ai.ts
+var AiService = class AiService {
+	options;
+	serviceName = "ai";
+	static async ask(payload) {
+		const res = await xr.postJson({
+			url: `${payload.baseUrl}/chat/completions`,
+			headers: {
+				Authorization: `Bearer ${payload.apiKey}`,
+				...payload.headers
+			},
+			data: {
+				model: payload.model,
+				messages: [...payload.prompt ? [{
+					role: "system",
+					content: payload.prompt
+				}] : [], {
+					role: "user",
+					content: payload.question
+				}],
+				stream: false
+			},
+			timeoutMs: ms("1m"),
+			noThrowHttpErrors: true
+		});
+		if (res.status !== 200) {
+			console.error(res.data);
+			throw new Error(JSON.stringify(res.data));
+		}
+		return { answer: res.data.choices[0].message.content };
+	}
+	constructor(options) {
+		this.options = options;
+	}
+	ask(payload) {
+		return AiService.ask({
+			...this.options,
+			...payload
+		});
+	}
+};
+export { AiService };

package/lib/services/base.d.mts

@@ -0,0 +1,4 @@
+export interface BaseService {
+  /** 服务名称 */
+  readonly serviceName: string;
+}

package/lib/services/base.mjs

@@ -0,0 +1 @@
+export {};

package/lib/services/cache.d.mts

@@ -0,0 +1,165 @@
+import { BaseService } from "./base.mjs";
+import { MsValue } from "vtils";
+import { AsyncOrSync, IsEmptyArray } from "vtils/types";
+export interface CacheSerializer {
+  stringify(value: unknown): string;
+  parse<T>(value: string): T;
+}
+export interface CacheServiceOptions {
+  /** 默认过期时间 */
+  ttl: MsValue;
+  /**
+   * 启用内存缓存
+   *
+   * - `true` 表示启用内存缓存
+   * - `'only'` 表示仅使用内存缓存，不使用 Redis
+   */
+  memory?: boolean | 'only';
+  /**
+   * 序列化工具
+   *
+   * - `'nativeJson'` 使用原生 JSON 进行序列化和反序列化（默认）
+   * - `'superJson'` 使用 SuperJson 进行序列化和反序列化，支持更多数据类型（比如Date、RegExp等）但性能较原生 JSON 略差
+   * - 也可直接传入自定义 `{ stringify, parse }`
+   */
+  serializer?: 'nativeJson' | 'superJson' | CacheSerializer;
+}
+type Data = { [K in string]: (...args: any[]) => any; };
+type Key<T extends Data> = keyof T;
+type KeyPath<T extends Data> = { [K in keyof T]: T[K] extends ((...args: infer X) => any) ? IsEmptyArray<X> extends true ? K : [K, ...X] : never; }[keyof T];
+type KeyPathForNumberValue<T extends Data> = { [K in keyof T]: T[K] extends ((...args: infer X) => number) ? IsEmptyArray<X> extends true ? K : [K, ...X] : never; }[keyof T];
+type Value<T extends Data, P extends KeyPath<T>> = ReturnType<T[P extends any[] ? P[0] : P]>;
+type KeyPartialPath<T extends Data> = { [K in keyof T]: T[K] extends ((...args: infer X) => any) ? IsEmptyArray<X> extends true ? K : [K, ...Partial<X>] : never; }[keyof T];
+type CacheSetTTL<V> = MsValue | ((data: V, defaultTTL: MsValue) => MsValue);
+type CacheSetOptions<V> = CacheSetTTL<V> | {
+  ttl?: CacheSetTTL<V>;
+};
+export declare class CacheService<TData extends Data = Data, TKey extends Key<TData> = any, TKeyPath extends KeyPath<TData> = any, TKeyPathForNumberValue extends KeyPathForNumberValue<TData> = any, TKeyPartialPath extends KeyPartialPath<TData> = any> implements BaseService {
+  options: CacheServiceOptions;
+  serviceName: string;
+  private prefix;
+  private hasMemoryCache;
+  private hasMemoryCacheOnly;
+  private memoryCache;
+  private serializer;
+  constructor(options: CacheServiceOptions);
+  private toRedisKey;
+  private serialize;
+  private deserialize;
+  /**
+   * 设置缓存内容。对象类内容尽量避免使用，以免造成问题。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param value 值
+   * @param ttlOrOptions 缓存时间或选项
+   * @returns 返回设置的缓存内容
+   */
+  set<K extends TKeyPath, V extends Value<TData, K>>(key: K, value: V, ttlOrOptions?: CacheSetOptions<V>): Promise<V>;
+  /**
+   * 存储值然后返回其对应的键，该键 URL 友好。
+   *
+   * @memory 支持
+   * @param value 值
+   * @param ttl 存活时间
+   */
+  save<T>(value: T | ((key: string) => AsyncOrSync<T>), ttl?: MsValue): Promise<string>;
+  /**
+   * 获取缓存内容。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param options 选项
+   * @returns 返回获取到的缓存内容
+   */
+  get<K extends TKeyPath, V extends Value<TData, K>>(key: K): Promise<V | null>;
+  /**
+   * 获取多个缓存内容。
+   *
+   * @memory 支持
+   * @param keys 键
+   * @returns 返回获取到的缓存内容
+   */
+  getMany<K extends TKeyPath, V extends Value<TData, K>>(...keys: K[]): Promise<Array<V | null>>;
+  /**
+   * 获取距离过期时间的毫秒数（未设置过期时间返回-1，键不存在返回-2）。
+   * memory=only 模式下内存缓存无 TTL 概念，始终返回-1。
+   *
+   * @memory 支持
+   * @param key 键
+   * @returns 返回距离过期时间的毫秒数
+   */
+  ttl<K extends TKeyPath>(key: K): Promise<number>;
+  /**
+   * 缓存内容。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param action 获取缓存内容的操作
+   * @param ttlOrOptions 缓存时间或选项
+   * @returns 返回获取到的内容
+   */
+  remember<K extends TKeyPath, V extends Value<TData, K>>(key: K, action: () => V | Promise<V>, ttlOrOptions?: CacheSetOptions<V>): Promise<V>;
+  rememberMany<T, K extends TKeyPath, V extends Value<TData, K>>(raws: T[], key: (raw: T) => K, action: (raws: T[]) => V[] | Promise<V[]>, ttlOrOptions?: CacheSetOptions<V>): Promise<V[]>;
+  /**
+   * 自增。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param increment 增量
+   */
+  increase<K extends TKeyPathForNumberValue>(key: K, increment?: number): Promise<number>;
+  /**
+   * 自减。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param decrement 减量
+   */
+  decrease<K extends TKeyPathForNumberValue>(key: K, decrement?: number): Promise<number>;
+  /**
+   * 新增元素。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param values 元素列表
+   */
+  push<K extends TKeyPath, V extends Value<TData, K>>(key: K, ...values: V[]): Promise<any>;
+  /**
+   * 从头部弹出元素并返回。
+   *
+   * @memory 支持
+   * @param key 键
+   * @param count 弹出元素个数
+   */
+  shift<K extends TKeyPath, V extends Value<TData, K>>(key: K, count?: number): Promise<V[]>;
+  /**
+   * 删除缓存。
+   *
+   * @memory 支持
+   * @param keys 键列表
+   */
+  remove<K extends TKeyPath>(...keys: K[]): Promise<number>;
+  /**
+   * 清空全部缓存。
+   *
+   * @memory 支持
+   */
+  clearAll(): Promise<number>;
+  /**
+   * 清空指定前缀的缓存。
+   *
+   * @memory 支持
+   */
+  clear(...prefixes: Array<TKey | TKeyPartialPath>): Promise<number>;
+  /**
+   * 派生出一个指定类型的缓存服务。
+   */
+  fork<TNextData extends Data>(options?: Partial<CacheServiceOptions>): CacheService<TNextData, Key<TNextData>, KeyPath<TNextData>, KeyPathForNumberValue<TNextData>, KeyPartialPath<TNextData>>;
+}
+declare module '../x.mjs' {
+  interface X {
+    cache: CacheService;
+  }
+}
+export {};