This commit is contained in:
ditiqi 2025-03-02 16:45:36 +08:00
parent 8c0a478ae0
commit d0a5571b50
1 changed files with 456 additions and 389 deletions

View File

@ -1,31 +1,39 @@
import http from 'node:http' import http from "node:http";
import { EventEmitter } from 'node:events' import { EventEmitter } from "node:events";
import debug from 'debug' import debug from "debug";
import { GetHandler } from './handlers/GetHandler' import { GetHandler } from "./handlers/GetHandler";
import { HeadHandler } from './handlers/HeadHandler' import { HeadHandler } from "./handlers/HeadHandler";
import { OptionsHandler } from './handlers/OptionsHandler' import { OptionsHandler } from "./handlers/OptionsHandler";
import { PatchHandler } from './handlers/PatchHandler' import { PatchHandler } from "./handlers/PatchHandler";
import { PostHandler } from './handlers/PostHandler' import { PostHandler } from "./handlers/PostHandler";
import { DeleteHandler } from './handlers/DeleteHandler' import { DeleteHandler } from "./handlers/DeleteHandler";
import { validateHeader } from './validators/HeaderValidator' import { validateHeader } from "./validators/HeaderValidator";
import type stream from 'node:stream' import type stream from "node:stream";
import type { ServerOptions, RouteHandler, WithOptional } from './types' import type { ServerOptions, RouteHandler, WithOptional } from "./types";
import { MemoryLocker } from './lockers' import { MemoryLocker } from "./lockers";
import { EVENTS, Upload, DataStore, REQUEST_METHODS, ERRORS, TUS_RESUMABLE, EXPOSED_HEADERS, CancellationContext } from './utils' import {
import { message } from 'antd'; EVENTS,
Upload,
DataStore,
REQUEST_METHODS,
ERRORS,
TUS_RESUMABLE,
EXPOSED_HEADERS,
CancellationContext,
} from "./utils";
/** /**
* *
* TUS服务器支持的各种HTTP方法对应的处理器实例类型 * TUS服务器支持的各种HTTP方法对应的处理器实例类型
*/ */
type Handlers = { type Handlers = {
GET: InstanceType<typeof GetHandler> // GET请求处理器 GET: InstanceType<typeof GetHandler>; // GET请求处理器
HEAD: InstanceType<typeof HeadHandler> // HEAD请求处理器 HEAD: InstanceType<typeof HeadHandler>; // HEAD请求处理器
OPTIONS: InstanceType<typeof OptionsHandler> // OPTIONS请求处理器 OPTIONS: InstanceType<typeof OptionsHandler>; // OPTIONS请求处理器
PATCH: InstanceType<typeof PatchHandler> // PATCH请求处理器 PATCH: InstanceType<typeof PatchHandler>; // PATCH请求处理器
POST: InstanceType<typeof PostHandler> // POST请求处理器 POST: InstanceType<typeof PostHandler>; // POST请求处理器
DELETE: InstanceType<typeof DeleteHandler> // DELETE请求处理器 DELETE: InstanceType<typeof DeleteHandler>; // DELETE请求处理器
} };
/** /**
* TUS服务器事件接口定义 * TUS服务器事件接口定义
@ -44,7 +52,7 @@ interface TusEvents {
res: http.ServerResponse, res: http.ServerResponse,
upload: Upload, upload: Upload,
url: string url: string
) => void ) => void;
/** /**
* @deprecated () * @deprecated ()
@ -54,14 +62,17 @@ interface TusEvents {
req: http.IncomingMessage, req: http.IncomingMessage,
res: http.ServerResponse, res: http.ServerResponse,
upload: Upload upload: Upload
) => void ) => void;
/** /**
* V2版本 * V2版本
* @param req HTTP请求对象 * @param req HTTP请求对象
* @param upload * @param upload
*/ */
[EVENTS.POST_RECEIVE_V2]: (req: http.IncomingMessage, upload: Upload) => void [EVENTS.POST_RECEIVE_V2]: (
req: http.IncomingMessage,
upload: Upload
) => void;
/** /**
* *
@ -73,7 +84,7 @@ interface TusEvents {
req: http.IncomingMessage, req: http.IncomingMessage,
res: http.ServerResponse, res: http.ServerResponse,
upload: Upload upload: Upload
) => void ) => void;
/** /**
* *
@ -85,14 +96,14 @@ interface TusEvents {
req: http.IncomingMessage, req: http.IncomingMessage,
res: http.ServerResponse, res: http.ServerResponse,
id: string id: string
) => void ) => void;
} }
/** /**
* EventEmitter事件处理器类型别名 * EventEmitter事件处理器类型别名
*/ */
type on = EventEmitter['on'] type on = EventEmitter["on"];
type emit = EventEmitter['emit'] type emit = EventEmitter["emit"];
/** /**
* TUS服务器接口声明 * TUS服务器接口声明
@ -105,14 +116,17 @@ export declare interface Server {
* @param listener * @param listener
* @returns Server实例以支持链式调用 * @returns Server实例以支持链式调用
*/ */
on<Event extends keyof TusEvents>(event: Event, listener: TusEvents[Event]): this on<Event extends keyof TusEvents>(
event: Event,
listener: TusEvents[Event]
): this;
/** /**
* *
* @param eventName * @param eventName
* @param listener * @param listener
* @returns Server实例以支持链式调用 * @returns Server实例以支持链式调用
*/ */
on(eventName: Parameters<on>[0], listener: Parameters<on>[1]): this on(eventName: Parameters<on>[0], listener: Parameters<on>[1]): this;
/** /**
* *
* @param event TusEvents的键之一 * @param event TusEvents的键之一
@ -122,61 +136,70 @@ export declare interface Server {
emit<Event extends keyof TusEvents>( emit<Event extends keyof TusEvents>(
event: Event, event: Event,
listener: TusEvents[Event] listener: TusEvents[Event]
): ReturnType<emit> ): ReturnType<emit>;
/** /**
* *
* @param eventName * @param eventName
* @param listener * @param listener
* @returns emit函数的返回值 * @returns emit函数的返回值
*/ */
emit(eventName: Parameters<emit>[0], listener: Parameters<emit>[1]): ReturnType<emit> emit(
eventName: Parameters<emit>[0],
listener: Parameters<emit>[1]
): ReturnType<emit>;
} }
/** /**
* *
*/ */
const log = debug('tus-node-server') const log = debug("tus-node-server");
// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: it's fine // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: it's fine
export class Server extends EventEmitter { export class Server extends EventEmitter {
datastore: DataStore datastore: DataStore;
handlers: Handlers handlers: Handlers;
options: ServerOptions options: ServerOptions;
/** /**
* Server * Server
* @param options - * @param options -
* @throws optionspath datastore * @throws optionspath datastore
*/ */
constructor(options: WithOptional<ServerOptions, 'locker'> & { datastore: DataStore }) { constructor(
super() options: WithOptional<ServerOptions, "locker"> & {
datastore: DataStore;
}
) {
super();
if (!options) { if (!options) {
throw new Error("'options' must be defined") throw new Error("'options' must be defined");
} }
if (!options.path) { if (!options.path) {
throw new Error("'path' is not defined; must have a path") throw new Error("'path' is not defined; must have a path");
} }
if (!options.datastore) { if (!options.datastore) {
throw new Error("'datastore' is not defined; must have a datastore") throw new Error(
"'datastore' is not defined; must have a datastore"
);
} }
if (!options.locker) { if (!options.locker) {
options.locker = new MemoryLocker() options.locker = new MemoryLocker();
} }
if (!options.lockDrainTimeout) { if (!options.lockDrainTimeout) {
options.lockDrainTimeout = 3000 options.lockDrainTimeout = 3000;
} }
if (!options.postReceiveInterval) { if (!options.postReceiveInterval) {
options.postReceiveInterval = 1000 options.postReceiveInterval = 1000;
} }
const { datastore, ...rest } = options const { datastore, ...rest } = options;
this.options = rest as ServerOptions this.options = rest as ServerOptions;
this.datastore = datastore this.datastore = datastore;
this.handlers = { this.handlers = {
// GET 请求处理器应在具体实现中编写 // GET 请求处理器应在具体实现中编写
GET: new GetHandler(this.datastore, this.options), GET: new GetHandler(this.datastore, this.options),
@ -186,24 +209,24 @@ export class Server extends EventEmitter {
PATCH: new PatchHandler(this.datastore, this.options), PATCH: new PatchHandler(this.datastore, this.options),
POST: new PostHandler(this.datastore, this.options), POST: new PostHandler(this.datastore, this.options),
DELETE: new DeleteHandler(this.datastore, this.options), DELETE: new DeleteHandler(this.datastore, this.options),
} };
// 任何以方法为键分配给此对象的处理器将用于响应这些请求。 // 任何以方法为键分配给此对象的处理器将用于响应这些请求。
// 当数据存储分配给服务器时,它们会被设置/重置。 // 当数据存储分配给服务器时,它们会被设置/重置。
// 从服务器中移除任何事件监听器时,必须先从每个处理器中移除监听器。 // 从服务器中移除任何事件监听器时,必须先从每个处理器中移除监听器。
// 这必须在添加 'newListener' 监听器之前完成,以避免为所有请求处理器添加 'removeListener' 事件监听器。 // 这必须在添加 'newListener' 监听器之前完成,以避免为所有请求处理器添加 'removeListener' 事件监听器。
this.on('removeListener', (event: string, listener) => { this.on("removeListener", (event: string, listener) => {
this.datastore.removeListener(event, listener) this.datastore.removeListener(event, listener);
for (const method of REQUEST_METHODS) { for (const method of REQUEST_METHODS) {
this.handlers[method].removeListener(event, listener) this.handlers[method].removeListener(event, listener);
} }
}) });
// 当事件监听器被添加到服务器时,确保它们从请求处理器冒泡到服务器级别。 // 当事件监听器被添加到服务器时,确保它们从请求处理器冒泡到服务器级别。
this.on('newListener', (event: string, listener) => { this.on("newListener", (event: string, listener) => {
this.datastore.on(event, listener) this.datastore.on(event, listener);
for (const method of REQUEST_METHODS) { for (const method of REQUEST_METHODS) {
this.handlers[method].on(event, listener) this.handlers[method].on(event, listener);
} }
}) });
} }
/** /**
@ -212,7 +235,7 @@ export class Server extends EventEmitter {
* @param handler - * @param handler -
*/ */
get(path: string, handler: RouteHandler) { get(path: string, handler: RouteHandler) {
this.handlers.GET.registerPath(path, handler) this.handlers.GET.registerPath(path, handler);
} }
/** /**
@ -226,76 +249,107 @@ export class Server extends EventEmitter {
res: http.ServerResponse res: http.ServerResponse
// biome-ignore lint/suspicious/noConfusingVoidType: it's fine // biome-ignore lint/suspicious/noConfusingVoidType: it's fine
): Promise<http.ServerResponse | stream.Writable | void> { ): Promise<http.ServerResponse | stream.Writable | void> {
const context = this.createContext(req);
const context = this.createContext(req) log(`[TusServer] handle: ${req.method} ${req.url}`);
log(`[TusServer] handle: ${req.method} ${req.url}`)
// 允许覆盖 HTTP 方法。这样做的原因是某些库/环境不支持 PATCH 和 DELETE 请求,例如浏览器中的 Flash 和 Java 部分环境 // 允许覆盖 HTTP 方法。这样做的原因是某些库/环境不支持 PATCH 和 DELETE 请求,例如浏览器中的 Flash 和 Java 部分环境
if (req.headers['x-http-method-override']) { if (req.headers["x-http-method-override"]) {
req.method = (req.headers['x-http-method-override'] as string).toUpperCase() req.method = (
req.headers["x-http-method-override"] as string
).toUpperCase();
} }
const onError = async (error: { const onError = async (error: {
status_code?: number status_code?: number;
body?: string body?: string;
message: string message: string;
}) => { }) => {
let status_code =
let status_code = error.status_code || ERRORS.UNKNOWN_ERROR.status_code error.status_code || ERRORS.UNKNOWN_ERROR.status_code;
let body = error.body || `${ERRORS.UNKNOWN_ERROR.body}${error.message || ''}\n` let body =
error.body ||
`${ERRORS.UNKNOWN_ERROR.body}${error.message || ""}\n`;
if (this.options.onResponseError) { if (this.options.onResponseError) {
const errorMapping = await this.options.onResponseError(req, res, error as Error) const errorMapping = await this.options.onResponseError(
req,
res,
error as Error
);
if (errorMapping) { if (errorMapping) {
status_code = errorMapping.status_code status_code = errorMapping.status_code;
body = errorMapping.body body = errorMapping.body;
} }
} }
return this.write(context, req, res, status_code, body) return this.write(context, req, res, status_code, body);
} };
if (req.method === 'GET') { if (req.method === "GET") {
const handler = this.handlers.GET const handler = this.handlers.GET;
return handler.send(req, res).catch(onError) return handler.send(req, res).catch(onError);
} }
// Tus-Resumable 头部必须包含在每个请求和响应中,除了 OPTIONS 请求。其值必须是客户端或服务器使用的协议版本。 // Tus-Resumable 头部必须包含在每个请求和响应中,除了 OPTIONS 请求。其值必须是客户端或服务器使用的协议版本。
res.setHeader('Tus-Resumable', TUS_RESUMABLE) res.setHeader("Tus-Resumable", TUS_RESUMABLE);
if (req.method !== 'OPTIONS' && req.headers['tus-resumable'] === undefined) { if (
return this.write(context, req, res, 412, 'Tus-Resumable Required\n') req.method !== "OPTIONS" &&
req.headers["tus-resumable"] === undefined
) {
return this.write(
context,
req,
res,
412,
"Tus-Resumable Required\n"
);
} }
// 验证所有必需的头部以符合 tus 协议 // 验证所有必需的头部以符合 tus 协议
const invalid_headers = [] const invalid_headers = [];
for (const header_name in req.headers) { for (const header_name in req.headers) {
if (req.method === 'OPTIONS') { if (req.method === "OPTIONS") {
continue continue;
} }
// 内容类型仅对 PATCH 请求进行检查。对于所有其他请求方法,它将被忽略并视为未设置内容类型, // 内容类型仅对 PATCH 请求进行检查。对于所有其他请求方法,它将被忽略并视为未设置内容类型,
// 因为某些 HTTP 客户端可能会为此头部强制执行默认值。 // 因为某些 HTTP 客户端可能会为此头部强制执行默认值。
// 参见 https://github.com/tus/tus-node-server/pull/116 // 参见 https://github.com/tus/tus-node-server/pull/116
if (header_name.toLowerCase() === 'content-type' && req.method !== 'PATCH') { if (
continue header_name.toLowerCase() === "content-type" &&
req.method !== "PATCH"
) {
continue;
} }
if (!validateHeader(header_name, req.headers[header_name] as string | undefined)) { if (
log(`Invalid ${header_name} header: ${req.headers[header_name]}`) !validateHeader(
invalid_headers.push(header_name) header_name,
req.headers[header_name] as string | undefined
)
) {
log(
`Invalid ${header_name} header: ${req.headers[header_name]}`
);
invalid_headers.push(header_name);
} }
} }
if (invalid_headers.length > 0) { if (invalid_headers.length > 0) {
return this.write(context, req, res, 400, `Invalid ${invalid_headers.join(' ')}\n`) return this.write(
context,
req,
res,
400,
`Invalid ${invalid_headers.join(" ")}\n`
);
} }
// 启用 CORS // 启用 CORS
res.setHeader('Access-Control-Allow-Origin', this.getCorsOrigin(req)) res.setHeader("Access-Control-Allow-Origin", this.getCorsOrigin(req));
res.setHeader('Access-Control-Expose-Headers', EXPOSED_HEADERS) res.setHeader("Access-Control-Expose-Headers", EXPOSED_HEADERS);
if (this.options.allowedCredentials === true) { if (this.options.allowedCredentials === true) {
res.setHeader('Access-Control-Allow-Credentials', 'true') res.setHeader("Access-Control-Allow-Credentials", "true");
} }
// 调用请求方法的处理器 // 调用请求方法的处理器
const handler = this.handlers[req.method as keyof Handlers] const handler = this.handlers[req.method as keyof Handlers];
if (handler) { if (handler) {
return handler.send(req, res, context).catch(onError);
return handler.send(req, res, context).catch(onError)
} }
return this.write(context, req, res, 404, 'Not found\n') return this.write(context, req, res, 404, "Not found\n");
} }
/** /**
@ -313,22 +367,26 @@ export class Server extends EventEmitter {
* - `*`CORS配置 * - `*`CORS配置
*/ */
private getCorsOrigin(req: http.IncomingMessage): string { private getCorsOrigin(req: http.IncomingMessage): string {
const origin = req.headers.origin const origin = req.headers.origin;
// 检查请求头中的`origin`是否在允许的源列表中 // 检查请求头中的`origin`是否在允许的源列表中
const isOriginAllowed = const isOriginAllowed =
this.options.allowedOrigins?.some((allowedOrigin) => allowedOrigin === origin) ?? this.options.allowedOrigins?.some(
true (allowedOrigin) => allowedOrigin === origin
) ?? true;
// 如果`origin`存在且在允许的源列表中,则返回该`origin` // 如果`origin`存在且在允许的源列表中,则返回该`origin`
if (origin && isOriginAllowed) { if (origin && isOriginAllowed) {
return origin return origin;
} }
// 如果允许的源列表不为空,则返回列表中的第一个源地址 // 如果允许的源列表不为空,则返回列表中的第一个源地址
if (this.options.allowedOrigins && this.options.allowedOrigins.length > 0) { if (
return this.options.allowedOrigins[0] this.options.allowedOrigins &&
this.options.allowedOrigins.length > 0
) {
return this.options.allowedOrigins[0];
} }
// 如果允许的源列表为空,则返回通配符`*`,表示允许所有源地址 // 如果允许的源列表为空,则返回通配符`*`,表示允许所有源地址
return '*' return "*";
} }
/** /**
@ -346,14 +404,14 @@ export class Server extends EventEmitter {
req: http.IncomingMessage, req: http.IncomingMessage,
res: http.ServerResponse, res: http.ServerResponse,
status: number, status: number,
body = '', body = "",
headers = {} headers = {}
) { ) {
const isAborted = context.signal.aborted const isAborted = context.signal.aborted;
if (status !== 204) { if (status !== 204) {
// @ts-expect-error not explicitly typed but possible // @ts-expect-error not explicitly typed but possible
headers['Content-Length'] = Buffer.byteLength(body, 'utf8') headers["Content-Length"] = Buffer.byteLength(body, "utf8");
} }
if (isAborted) { if (isAborted) {
@ -363,20 +421,20 @@ export class Server extends EventEmitter {
// 这一步对于防止服务器继续处理不再需要的请求至关重要,从而节省资源。 // 这一步对于防止服务器继续处理不再需要的请求至关重要,从而节省资源。
// @ts-expect-error not explicitly typed but possible // @ts-expect-error not explicitly typed but possible
headers.Connection = 'close' headers.Connection = "close";
// 为响应 ('res') 添加 'finish' 事件的事件监听器。 // 为响应 ('res') 添加 'finish' 事件的事件监听器。
// 'finish' 事件在响应已发送给客户端时触发。 // 'finish' 事件在响应已发送给客户端时触发。
// 一旦响应完成,请求 ('req') 对象将被销毁。 // 一旦响应完成,请求 ('req') 对象将被销毁。
// 销毁请求对象是释放与此请求相关的任何资源的关键步骤,因为它已经被中止。 // 销毁请求对象是释放与此请求相关的任何资源的关键步骤,因为它已经被中止。
res.on('finish', () => { res.on("finish", () => {
req.destroy() req.destroy();
}) });
} }
res.writeHead(status, headers) res.writeHead(status, headers);
res.write(body) res.write(body);
return res.end() return res.end();
} }
/** /**
@ -386,7 +444,7 @@ export class Server extends EventEmitter {
*/ */
// biome-ignore lint/suspicious/noExplicitAny: todo // biome-ignore lint/suspicious/noExplicitAny: todo
listen(...args: any[]): http.Server { listen(...args: any[]): http.Server {
return http.createServer(this.handle.bind(this)).listen(...args) return http.createServer(this.handle.bind(this)).listen(...args);
} }
/** /**
@ -395,11 +453,11 @@ export class Server extends EventEmitter {
* @throws * @throws
*/ */
cleanUpExpiredUploads(): Promise<number> { cleanUpExpiredUploads(): Promise<number> {
if (!this.datastore.hasExtension('expiration')) { if (!this.datastore.hasExtension("expiration")) {
throw ERRORS.UNSUPPORTED_EXPIRATION_EXTENSION throw ERRORS.UNSUPPORTED_EXPIRATION_EXTENSION;
} }
return this.datastore.deleteExpired() return this.datastore.deleteExpired();
} }
/** /**
@ -412,22 +470,31 @@ export class Server extends EventEmitter {
// 1. `requestAbortController` 用于即时请求终止,特别适用于在发生错误时停止客户端上传。 // 1. `requestAbortController` 用于即时请求终止,特别适用于在发生错误时停止客户端上传。
// 2. `abortWithDelayController` 用于在终止前引入延迟,允许服务器有时间完成正在进行的操作。 // 2. `abortWithDelayController` 用于在终止前引入延迟,允许服务器有时间完成正在进行的操作。
// 这在未来的请求可能需要获取当前请求持有的锁时特别有用。 // 这在未来的请求可能需要获取当前请求持有的锁时特别有用。
const requestAbortController = new AbortController() const requestAbortController = new AbortController();
const abortWithDelayController = new AbortController() const abortWithDelayController = new AbortController();
// 当 `abortWithDelayController` 被触发时调用此函数,以在指定延迟后中止请求。 // 当 `abortWithDelayController` 被触发时调用此函数,以在指定延迟后中止请求。
const onDelayedAbort = (err: unknown) => { const onDelayedAbort = (err: unknown) => {
abortWithDelayController.signal.removeEventListener('abort', onDelayedAbort) abortWithDelayController.signal.removeEventListener(
"abort",
onDelayedAbort
);
setTimeout(() => { setTimeout(() => {
requestAbortController.abort(err) requestAbortController.abort(err);
}, this.options.lockDrainTimeout) }, this.options.lockDrainTimeout);
} };
abortWithDelayController.signal.addEventListener('abort', onDelayedAbort) abortWithDelayController.signal.addEventListener(
"abort",
onDelayedAbort
);
// 当请求关闭时,移除监听器以避免内存泄漏。 // 当请求关闭时,移除监听器以避免内存泄漏。
req.on('close', () => { req.on("close", () => {
abortWithDelayController.signal.removeEventListener('abort', onDelayedAbort) abortWithDelayController.signal.removeEventListener(
}) "abort",
onDelayedAbort
);
});
// 返回一个对象,包含信号和两个中止请求的方法。 // 返回一个对象,包含信号和两个中止请求的方法。
// `signal` 用于监听请求中止事件。 // `signal` 用于监听请求中止事件。
@ -438,15 +505,15 @@ export class Server extends EventEmitter {
abort: () => { abort: () => {
// 立即中止请求 // 立即中止请求
if (!requestAbortController.signal.aborted) { if (!requestAbortController.signal.aborted) {
requestAbortController.abort(ERRORS.ABORTED) requestAbortController.abort(ERRORS.ABORTED);
} }
}, },
cancel: () => { cancel: () => {
// 启动延迟中止序列,除非它已经在进行中。 // 启动延迟中止序列,除非它已经在进行中。
if (!abortWithDelayController.signal.aborted) { if (!abortWithDelayController.signal.aborted) {
abortWithDelayController.abort(ERRORS.ABORTED) abortWithDelayController.abort(ERRORS.ABORTED);
} }
}, },
} };
} }
} }