257 lines
8.7 KiB
TypeScript
257 lines
8.7 KiB
TypeScript
import debug from 'debug'
|
||
|
||
import { BaseHandler } from './BaseHandler'
|
||
|
||
import { validateHeader } from '../validators/HeaderValidator'
|
||
|
||
import type http from 'node:http'
|
||
import type { ServerOptions, WithRequired } from '../types'
|
||
import { DataStore, Uid, CancellationContext, ERRORS, Metadata, Upload, EVENTS } from '../utils'
|
||
|
||
const log = debug('tus-node-server:handlers:post')
|
||
|
||
/**
|
||
* PostHandler 类用于处理 HTTP POST 请求，主要用于在 DataStore 中创建文件。
|
||
* 该类继承自 BaseHandler，并重写了部分方法以实现特定的功能。
|
||
*/
|
||
export class PostHandler extends BaseHandler {
|
||
// 重写 BaseHandler 中的 options 类型，确保在构造函数中设置了 namingFunction
|
||
declare options: WithRequired<ServerOptions, 'namingFunction'>
|
||
|
||
/**
|
||
* 构造函数，初始化 PostHandler 实例。
|
||
* @param store - DataStore 实例，用于存储上传的文件。
|
||
* @param options - 服务器配置选项，包含 namingFunction 等。
|
||
* @throws 如果 namingFunction 不是函数，则抛出错误。
|
||
*/
|
||
constructor(store: DataStore, options: ServerOptions) {
|
||
if (options.namingFunction && typeof options.namingFunction !== 'function') {
|
||
throw new Error("'namingFunction' must be a function")
|
||
}
|
||
|
||
if (!options.namingFunction) {
|
||
options.namingFunction = Uid.rand
|
||
}
|
||
|
||
super(store, options)
|
||
}
|
||
|
||
/**
|
||
* 在 DataStore 中创建文件。
|
||
* @param req - HTTP 请求对象。
|
||
* @param res - HTTP 响应对象。
|
||
* @param context - 取消操作的上下文。
|
||
* @returns 返回处理后的 HTTP 响应对象。
|
||
* @throws 如果请求头中包含 'upload-concat' 但 DataStore 不支持 'concatentation' 扩展，则抛出错误。
|
||
* @throws 如果请求头中 'upload-length' 和 'upload-defer-length' 同时存在或同时不存在，则抛出错误。
|
||
* @throws 如果 'upload-metadata' 解析失败，则抛出错误。
|
||
* @throws 如果文件大小超过配置的最大值，则抛出错误。
|
||
*/
|
||
async send(
|
||
req: http.IncomingMessage,
|
||
res: http.ServerResponse,
|
||
context: CancellationContext
|
||
) {
|
||
if ('upload-concat' in req.headers && !this.store.hasExtension('concatentation')) {
|
||
throw ERRORS.UNSUPPORTED_CONCATENATION_EXTENSION
|
||
}
|
||
|
||
const upload_length = req.headers['upload-length'] as string | undefined
|
||
const upload_defer_length = req.headers['upload-defer-length'] as string | undefined
|
||
const upload_metadata = req.headers['upload-metadata'] as string | undefined
|
||
|
||
if (
|
||
upload_defer_length !== undefined && // 如果扩展不支持，则抛出错误
|
||
!this.store.hasExtension('creation-defer-length')
|
||
) {
|
||
throw ERRORS.UNSUPPORTED_CREATION_DEFER_LENGTH_EXTENSION
|
||
}
|
||
|
||
if ((upload_length === undefined) === (upload_defer_length === undefined)) {
|
||
throw ERRORS.INVALID_LENGTH
|
||
}
|
||
|
||
let metadata: ReturnType<(typeof Metadata)['parse']> | undefined
|
||
if ('upload-metadata' in req.headers) {
|
||
try {
|
||
metadata = Metadata.parse(upload_metadata)
|
||
} catch {
|
||
throw ERRORS.INVALID_METADATA
|
||
}
|
||
}
|
||
|
||
let id: string
|
||
try {
|
||
id = await this.options.namingFunction(req, metadata)
|
||
} catch (error) {
|
||
log('create: check your `namingFunction`. Error', error)
|
||
throw error
|
||
}
|
||
|
||
const maxFileSize = await this.getConfiguredMaxSize(req, id)
|
||
|
||
if (
|
||
upload_length &&
|
||
maxFileSize > 0 &&
|
||
Number.parseInt(upload_length, 10) > maxFileSize
|
||
) {
|
||
throw ERRORS.ERR_MAX_SIZE_EXCEEDED
|
||
}
|
||
|
||
if (this.options.onIncomingRequest) {
|
||
await this.options.onIncomingRequest(req, res, id)
|
||
}
|
||
|
||
const upload = new Upload({
|
||
id,
|
||
size: upload_length ? Number.parseInt(upload_length, 10) : undefined,
|
||
offset: 0,
|
||
metadata,
|
||
})
|
||
|
||
if (this.options.onUploadCreate) {
|
||
try {
|
||
const resOrObject = await this.options.onUploadCreate(req, res, upload)
|
||
// 向后兼容，将在下一个主要版本中移除
|
||
// 由于在测试中模拟了实例，因此无法使用 `instanceof` 进行检查
|
||
if (
|
||
typeof (resOrObject as http.ServerResponse).write === 'function' &&
|
||
typeof (resOrObject as http.ServerResponse).writeHead === 'function'
|
||
) {
|
||
res = resOrObject as http.ServerResponse
|
||
} else {
|
||
// 由于 TS 只理解 instanceof，因此类型定义较为丑陋
|
||
type ExcludeServerResponse<T> = T extends http.ServerResponse ? never : T
|
||
const obj = resOrObject as ExcludeServerResponse<typeof resOrObject>
|
||
res = obj.res
|
||
if (obj.metadata) {
|
||
upload.metadata = obj.metadata
|
||
}
|
||
}
|
||
} catch (error: any) {
|
||
log(`onUploadCreate error: ${error.body}`)
|
||
throw error
|
||
}
|
||
}
|
||
|
||
const lock = await this.acquireLock(req, id, context)
|
||
|
||
let isFinal: boolean
|
||
let url: string
|
||
|
||
// 推荐的响应默认值
|
||
const responseData = {
|
||
status: 201,
|
||
headers: {} as Record<string, string | number>,
|
||
body: '',
|
||
}
|
||
|
||
try {
|
||
await this.store.create(upload)
|
||
url = this.generateUrl(req, upload.id)
|
||
|
||
this.emit(EVENTS.POST_CREATE, req, res, upload, url)
|
||
|
||
isFinal = upload.size === 0 && !upload.sizeIsDeferred
|
||
|
||
// 如果请求中包含 Content-Type 头，并且使用了 creation-with-upload 扩展
|
||
if (validateHeader('content-type', req.headers['content-type'])) {
|
||
const bodyMaxSize = await this.calculateMaxBodySize(req, upload, maxFileSize)
|
||
const newOffset = await this.writeToStore(req, upload, bodyMaxSize, context)
|
||
|
||
responseData.headers['Upload-Offset'] = newOffset.toString()
|
||
isFinal = newOffset === Number.parseInt(upload_length as string, 10)
|
||
upload.offset = newOffset
|
||
}
|
||
} catch (e) {
|
||
context.abort()
|
||
throw e
|
||
} finally {
|
||
await lock.unlock()
|
||
}
|
||
// 上传完成后的处理逻辑
|
||
if (isFinal && this.options.onUploadFinish) {
|
||
try {
|
||
// 调用自定义的上传完成回调函数，传入请求、响应和上传对象
|
||
// 允许用户自定义上传完成后的处理逻辑
|
||
const resOrObject = await this.options.onUploadFinish(req, res, upload)
|
||
|
||
// 兼容性处理：检查返回值是否为 HTTP 响应对象
|
||
// 通过检查对象是否具有 write 和 writeHead 方法来判断
|
||
if (
|
||
typeof (resOrObject as http.ServerResponse).write === 'function' &&
|
||
typeof (resOrObject as http.ServerResponse).writeHead === 'function'
|
||
) {
|
||
// 如果直接返回 HTTP 响应对象，直接覆盖原响应对象
|
||
res = resOrObject as http.ServerResponse
|
||
} else {
|
||
// 处理自定义返回对象的情况
|
||
// 使用复杂的类型定义排除 ServerResponse 类型
|
||
type ExcludeServerResponse<T> = T extends http.ServerResponse ? never : T
|
||
|
||
// 将返回对象转换为非 ServerResponse 类型
|
||
const obj = resOrObject as ExcludeServerResponse<typeof resOrObject>
|
||
|
||
// 更新响应对象
|
||
res = obj.res
|
||
|
||
// 根据返回对象更新响应状态码
|
||
if (obj.status_code) responseData.status = obj.status_code
|
||
|
||
// 更新响应体
|
||
if (obj.body) responseData.body = obj.body
|
||
|
||
// 合并响应头，允许覆盖默认头
|
||
if (obj.headers)
|
||
responseData.headers = Object.assign(obj.headers, responseData.headers)
|
||
}
|
||
} catch (error: any) {
|
||
// 记录上传完成回调中的错误
|
||
log(`onUploadFinish: ${error.body}`)
|
||
|
||
// 抛出错误，中断上传流程
|
||
throw error
|
||
}
|
||
}
|
||
|
||
|
||
// Upload-Expires 响应头指示未完成的上传何时过期。
|
||
// 如果在创建时已知过期时间，则必须在响应中包含 Upload-Expires 头
|
||
if (
|
||
this.store.hasExtension('expiration') &&
|
||
this.store.getExpiration() > 0 &&
|
||
upload.creation_date
|
||
) {
|
||
const created = await this.store.getUpload(upload.id)
|
||
|
||
if (created.offset !== Number.parseInt(upload_length as string, 10)) {
|
||
const creation = new Date(upload.creation_date)
|
||
// 值必须为 RFC 7231 日期时间格式
|
||
responseData.headers['Upload-Expires'] = new Date(
|
||
creation.getTime() + this.store.getExpiration()
|
||
).toUTCString()
|
||
}
|
||
}
|
||
|
||
// 仅在最终的 HTTP 状态码为 201 或 3xx 时附加 Location 头
|
||
if (
|
||
responseData.status === 201 ||
|
||
(responseData.status >= 300 && responseData.status < 400)
|
||
) {
|
||
responseData.headers.Location = url
|
||
}
|
||
|
||
const writtenRes = this.write(
|
||
res,
|
||
responseData.status,
|
||
responseData.headers,
|
||
responseData.body
|
||
)
|
||
|
||
if (isFinal) {
|
||
this.emit(EVENTS.POST_FINISH, req, writtenRes, upload)
|
||
}
|
||
|
||
return writtenRes
|
||
}
|
||
} |