@lhy-meta-server/meta-oss 0.0.0-stage → 0.0.2

package/dist/core/storage.d.ts

@@ -0,0 +1,344 @@
+import type { StorageDriver } from './driver';
+import { type StorageRetryOptions } from './execution';
+import { StorageMetrics, type StorageMetricsSnapshot, type StorageObserver } from './observability';
+import { type UploadPolicy } from './policy';
+import type { DeleteObjectsResult, GetObjectOptions, ListObjectsOptions, ListObjectsResult, MultipartUpload, MultipartUploadOptions, MultipartUploadPart, ObjectBody, ObjectInfo, ObjectStream, PutObjectOptions, SignedUrlOptions, StorageOperationOptions, VerifiedUrl, VerifyUrlRequest } from './types';
+/**
+ * 对象存储服务配置。
+ */
+export interface ObjectStorageOptions {
+    /**
+     * 实际执行存储操作的适配器。
+     */
+    driver: StorageDriver;
+    /**
+     * 自动添加到所有对象键前的目录前缀，例如 `tenant-a`；对业务透明。
+     */
+    prefix?: string;
+    /**
+     * 单次尝试的默认超时毫秒数，默认为 30000；`0` 表示不限制。
+     */
+    timeout?: number;
+    /**
+     * 重试退避配置。只会重试幂等或可重复读取内容的操作。
+     */
+    retry?: StorageRetryOptions;
+    /**
+     * 对后端的最大并发请求数，默认为 32。
+     *
+     * 超时或取消后，许可会一直占用到适配器的底层操作真正结束（最长 `abortGrace`），
+     * 因此该值能够限制实际在途的后端请求数。
+     */
+    concurrency?: number;
+    /**
+     * 超时或取消后等待适配器底层操作结束的最长毫秒数，默认为 5000；`0` 表示不等待。
+     *
+     * 适配器应响应 `signal` 尽快结束；超过宽限期仍未结束的操作会被放弃追踪并释放许可，
+     * 防止不响应取消的 SDK 永久占用并发额度。
+     */
+    abortGrace?: number;
+    /**
+     * 上传限制策略。
+     */
+    upload?: UploadPolicy;
+    /**
+     * 单次 `put` 的内容超过该字节数时自动改用分片上传，默认为 64 MiB；
+     * 仅在适配器支持分片上传时生效，设为 `0` 可禁用。
+     *
+     * 自动分片以流方式切片，内存占用约为 `partSize × partConcurrency`。
+     */
+    multipartThreshold?: number;
+    /**
+     * 同名对象存在时是否默认覆盖，默认为 `true`。
+     */
+    overwrite?: boolean;
+    /**
+     * 自定义扩展名到 MIME 类型的映射，键为不含点号的小写扩展名。
+     */
+    contentTypes?: Readonly<Record<string, string>>;
+    /**
+     * 分片上传默认分片字节数，默认为 8 MiB，不得小于 100 KiB。
+     */
+    partSize?: number;
+    /**
+     * 分片上传默认并行数，默认为 4。
+     */
+    partConcurrency?: number;
+    /**
+     * 结构化事件观察器。
+     */
+    observer?: StorageObserver;
+    /**
+     * 指标收集器，可在多个实例间共享；默认创建私有实例。
+     */
+    metrics?: StorageMetrics;
+}
+/**
+ * 与框架和具体后端无关的对象存储服务。
+ *
+ * 服务统一负责对象键校验、前缀隔离、上传限制、MIME 推断、超时、取消、
+ * 指数退避重试、并发控制与可观测性；适配器只需实现 {@link StorageDriver}。
+ *
+ * @example
+ * ```ts
+ * import { ObjectStorage } from '@lhy-meta-server/meta-oss'
+ * import { FileSystemDriver } from '@lhy-meta-server/meta-oss/filesystem'
+ *
+ * const storage = new ObjectStorage({
+ *   driver: new FileSystemDriver({ root: './storage' }),
+ *   upload: { maxSize: 10 * 1024 * 1024, allowedContentTypes: ['image/*'] },
+ * })
+ * await storage.put('avatars/1.png', file)
+ * ```
+ */
+export declare class ObjectStorage {
+    /**
+     * 当前使用的适配器名称。
+     */
+    readonly driverName: string;
+    private readonly driver;
+    private readonly prefix;
+    private readonly timeout;
+    private readonly retries;
+    private readonly baseDelay;
+    private readonly maxDelay;
+    private readonly jitter;
+    private readonly shouldRetry;
+    private readonly semaphore;
+    private readonly concurrency;
+    private readonly policy;
+    private readonly maxSize;
+    private readonly overwrite;
+    private readonly contentTypes;
+    private readonly partSize;
+    private readonly partConcurrency;
+    private readonly abortGrace;
+    private readonly multipartThreshold;
+    private readonly observer?;
+    private readonly metrics;
+    private closing?;
+    /**
+     * 创建对象存储服务并校验全部配置。
+     *
+     * @param options 适配器、可靠性、上传策略与可观测性配置。
+     * @throws {@link StorageError} 配置非法时抛出 `INVALID_OPTION`。
+     */
+    constructor(options: ObjectStorageOptions);
+    /**
+     * 写入对象。
+     *
+     * 可重复读取的内容（字符串、二进制、`Blob`）在可重试错误时会自动重试；
+     * 流式内容只尝试一次。已知大小超过 `multipartThreshold` 且适配器支持分片上传时，
+     * 自动改用流式分片上传，避免把大文件整体读入内存。
+     *
+     * @param key 业务对象键。
+     * @param body 对象内容。
+     * @param options HTTP 属性、元数据、覆盖策略与执行控制。
+     * @returns 写入后的对象描述信息。
+     * @throws {@link StorageError} `INVALID_KEY`、`UPLOAD_REJECTED`、`ALREADY_EXISTS` 等。
+     */
+    put(key: string, body: ObjectBody, options?: PutObjectOptions): Promise<ObjectInfo>;
+    /**
+     * 以流方式读取对象。
+     *
+     * 超时与重试只作用于“打开对象”阶段；返回的流由调用方负责消费或取消。
+     *
+     * @param key 业务对象键。
+     * @param options 读取范围与执行控制。
+     * @returns 对象描述信息与 Web 可读流。
+     * @throws {@link StorageError} 对象不存在时抛出 `NOT_FOUND`。
+     */
+    get(key: string, options?: GetObjectOptions): Promise<ObjectStream>;
+    /**
+     * 读取对象全部内容为字节数组。
+     *
+     * @param key 业务对象键。
+     * @param options 读取范围与执行控制。
+     * @returns 对象内容。
+     */
+    getBytes(key: string, options?: GetObjectOptions): Promise<Uint8Array>;
+    /**
+     * 以 UTF-8 解码读取对象全部内容。
+     *
+     * @param key 业务对象键。
+     * @param options 读取范围与执行控制。
+     * @returns 对象文本内容。
+     */
+    getText(key: string, options?: GetObjectOptions): Promise<string>;
+    /**
+     * 读取对象描述信息。
+     *
+     * @param key 业务对象键。
+     * @param options 执行控制。
+     * @returns 对象描述信息。
+     * @throws {@link StorageError} 对象不存在时抛出 `NOT_FOUND`。
+     */
+    head(key: string, options?: StorageOperationOptions): Promise<ObjectInfo>;
+    /**
+     * 判断对象是否存在。
+     *
+     * @param key 业务对象键。
+     * @param options 执行控制。
+     * @returns 对象是否存在。
+     */
+    exists(key: string, options?: StorageOperationOptions): Promise<boolean>;
+    /**
+     * 删除对象；对象不存在时静默成功。
+     *
+     * @param key 业务对象键。
+     * @param options 执行控制。
+     */
+    delete(key: string, options?: StorageOperationOptions): Promise<void>;
+    /**
+     * 批量删除对象。
+     *
+     * 适配器支持原生批量删除时一次提交（每批最多 1000 个），否则以受控并发逐个删除。
+     * 单个对象失败不会中断其他对象，失败项记录在结果的 `failed` 中；降级路径下结果
+     * 顺序与输入顺序一致。
+     *
+     * @param keys 业务对象键列表，重复键会被去重。
+     * @param options 执行控制。
+     * @returns 成功与失败的对象键。
+     * @throws {@link StorageError} 任一键非法时抛出 `INVALID_KEY`，此时不会删除任何对象。
+     */
+    deleteMany(keys: readonly string[], options?: StorageOperationOptions): Promise<DeleteObjectsResult>;
+    /**
+     * 分页列举对象。
+     *
+     * @param options 前缀、分隔符、游标与页大小。
+     * @returns 当前页对象、公共前缀与下一页游标。
+     * @throws {@link StorageError} 适配器不支持列举时抛出 `UNSUPPORTED`。
+     */
+    list(options?: ListObjectsOptions): Promise<ListObjectsResult>;
+    /**
+     * 遍历前缀下的全部对象，自动处理分页。
+     *
+     * @param options 前缀与页大小；游标与分隔符会被忽略。
+     * @returns 逐个产生对象描述信息的异步迭代器。
+     */
+    listAll(options?: Omit<ListObjectsOptions, 'cursor' | 'delimiter'>): AsyncGenerator<ObjectInfo>;
+    /**
+     * 复制对象。
+     *
+     * 适配器支持服务端复制时直接使用，否则读取源对象后流式写入目标，并保留
+     * HTTP 属性与元数据。
+     *
+     * @param source 源对象键。
+     * @param destination 目标对象键。
+     * @param options 覆盖策略与执行控制。
+     * @returns 目标对象描述信息。
+     */
+    copy(source: string, destination: string, options?: StorageOperationOptions & {
+        overwrite?: boolean;
+    }): Promise<ObjectInfo>;
+    /**
+     * 移动对象：先复制到目标，成功后删除源对象。
+     *
+     * @param source 源对象键。
+     * @param destination 目标对象键。
+     * @param options 覆盖策略与执行控制。
+     * @returns 目标对象描述信息。
+     */
+    move(source: string, destination: string, options?: StorageOperationOptions & {
+        overwrite?: boolean;
+    }): Promise<ObjectInfo>;
+    private copyObject;
+    /**
+     * 生成限时签名 URL，供客户端直接下载或上传。
+     *
+     * `PUT` 签名会校验扩展名与 MIME 策略，但无法在服务端限制客户端上传的字节数。
+     * 签名 URL 属于凭据，不会出现在可观测事件中。
+     *
+     * @param key 业务对象键。
+     * @param options HTTP 方法、有效期与响应头覆盖。
+     * @returns 签名 URL。
+     * @throws {@link StorageError} 适配器不支持签名时抛出 `UNSUPPORTED`。
+     */
+    signUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * 校验由本服务签发的签名 URL，供业务自建的下载或上传路由鉴权使用。
+     *
+     * 第三方 OSS 的签名由其服务端校验，因此通常只有自签名后端支持该方法。
+     * 返回的 `key` 已去除服务级前缀；签名对象不属于当前前缀时视为拒绝。
+     *
+     * @param request 请求 URL、方法与 `Content-Type`。
+     * @returns 授权信息。
+     * @throws {@link StorageError} 校验失败时抛出 `ACCESS_DENIED`；适配器不支持时抛出 `UNSUPPORTED`。
+     */
+    verifyUrl(request: VerifyUrlRequest): VerifiedUrl;
+    /**
+     * 创建分片上传会话，适用于断点续传或客户端分片场景。
+     *
+     * @param key 业务对象键。
+     * @param options HTTP 属性、元数据与执行控制。
+     * @returns 上传会话。
+     * @throws {@link StorageError} 适配器不支持分片上传时抛出 `UNSUPPORTED`。
+     */
+    createMultipart(key: string, options?: PutObjectOptions): Promise<MultipartUpload>;
+    /**
+     * 上传单个分片；分片内容会先读入内存，以便失败时安全重试。
+     *
+     * @param upload 上传会话。
+     * @param partNumber 分片序号，1 到 10000。
+     * @param body 分片内容。
+     * @param options 执行控制。
+     * @returns 已上传分片。
+     */
+    uploadPart(upload: MultipartUpload, partNumber: number, body: ObjectBody, options?: StorageOperationOptions): Promise<MultipartUploadPart>;
+    /**
+     * 合并分片完成上传；分片会按序号排序，重复序号以最后一次为准。
+     *
+     * @param upload 上传会话。
+     * @param parts 已上传分片。
+     * @param options 执行控制。
+     * @returns 合并后的对象描述信息。
+     */
+    completeMultipart(upload: MultipartUpload, parts: readonly MultipartUploadPart[], options?: StorageOperationOptions): Promise<ObjectInfo>;
+    /**
+     * 放弃分片上传并清理已上传的分片。
+     *
+     * @param upload 上传会话。
+     * @param options 执行控制。
+     */
+    abortMultipart(upload: MultipartUpload, options?: StorageOperationOptions): Promise<void>;
+    /**
+     * 自动分片上传大对象。
+     *
+     * 内容以流方式切片，内存占用约为 `partSize × concurrency`；任一分片失败时会
+     * 中止会话并清理已上传分片。空内容会退化为普通写入。
+     *
+     * @param key 业务对象键。
+     * @param body 对象内容。
+     * @param options 分片大小、并行数、HTTP 属性与执行控制。
+     * @returns 合并后的对象描述信息。
+     */
+    uploadMultipart(key: string, body: ObjectBody, options?: MultipartUploadOptions): Promise<ObjectInfo>;
+    private shouldUseMultipart;
+    private uploadMultipartPayload;
+    /**
+     * 返回累计指标的冻结快照。
+     *
+     * @returns 指标快照。
+     */
+    getMetrics(): StorageMetricsSnapshot;
+    /**
+     * 将累计指标清零。
+     */
+    resetMetrics(): void;
+    /**
+     * 关闭服务并释放适配器资源；重复调用返回同一结果。关闭后的所有操作都会抛出 `CLOSED`。
+     */
+    close(): Promise<void>;
+    private putOptions;
+    private capability;
+    private multipartDriver;
+    private assertUpload;
+    private driverUpload;
+    private fullKey;
+    private publicKey;
+    private publicInfo;
+    private run;
+    private emit;
+    private notify;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/core/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/core/storage.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -0,0 +1,301 @@
+import type { Readable } from 'node:stream';
+/**
+ * 可作为对象内容写入的数据来源。
+ *
+ * 同时兼容 Web 标准、Bun 与 Node.js：`Bun.file()` 与 `File` 都属于 `Blob`，
+ * Node.js `Buffer` 属于 `Uint8Array`。
+ */
+export type ObjectBody = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array> | Readable | AsyncIterable<Uint8Array | string>;
+/**
+ * 对象自定义元数据。
+ *
+ * 键仅允许小写字母、数字与连字符；值不允许包含控制字符。
+ */
+export type ObjectMetadata = Record<string, string>;
+/**
+ * 对象的 HTTP 语义属性。
+ */
+export interface ObjectHttpOptions {
+    /**
+     * 内容 MIME 类型；省略时按对象键扩展名推断。
+     */
+    contentType?: string;
+    /**
+     * HTTP `Cache-Control` 值。
+     */
+    cacheControl?: string;
+    /**
+     * HTTP `Content-Disposition` 值。
+     */
+    contentDisposition?: string;
+    /**
+     * 自定义元数据。
+     */
+    metadata?: ObjectMetadata;
+}
+/**
+ * 对象描述信息。
+ */
+export interface ObjectInfo {
+    /**
+     * 对业务可见的对象键，不包含服务级前缀。
+     */
+    key: string;
+    /**
+     * 对象字节数。
+     */
+    size: number;
+    /**
+     * 后端提供的实体标签，已去除两侧引号。
+     */
+    etag?: string;
+    /**
+     * 最后修改时间。
+     */
+    lastModified?: Date;
+    /**
+     * 内容 MIME 类型。
+     */
+    contentType?: string;
+    /**
+     * HTTP `Cache-Control` 值。
+     */
+    cacheControl?: string;
+    /**
+     * HTTP `Content-Disposition` 值。
+     */
+    contentDisposition?: string;
+    /**
+     * 自定义元数据。
+     */
+    metadata: ObjectMetadata;
+}
+/**
+ * 所有操作共享的执行控制选项。
+ */
+export interface StorageOperationOptions {
+    /**
+     * 调用方取消信号。
+     */
+    signal?: AbortSignal;
+    /**
+     * 单次尝试的超时毫秒数，覆盖服务默认值；`0` 表示不限制。
+     */
+    timeout?: number;
+    /**
+     * 最大重试次数，覆盖服务默认值。
+     */
+    retries?: number;
+}
+/**
+ * 写入对象的选项。
+ */
+export interface PutObjectOptions extends ObjectHttpOptions, StorageOperationOptions {
+    /**
+     * 同名对象存在时是否覆盖，覆盖服务默认值。
+     */
+    overwrite?: boolean;
+}
+/**
+ * 读取范围，`start` 与 `end` 均为包含在内的字节偏移。
+ */
+export interface ObjectRange {
+    /**
+     * 起始字节偏移，从 `0` 开始。
+     */
+    start: number;
+    /**
+     * 结束字节偏移；省略时读取到对象末尾。
+     */
+    end?: number;
+}
+/**
+ * 读取对象的选项。
+ */
+export interface GetObjectOptions extends StorageOperationOptions {
+    /**
+     * 只读取指定字节范围。
+     */
+    range?: ObjectRange;
+}
+/**
+ * 流式读取结果。
+ */
+export interface ObjectStream {
+    /**
+     * 对象描述信息。
+     */
+    info: ObjectInfo;
+    /**
+     * 对象内容的 Web 标准可读流。
+     */
+    body: ReadableStream<Uint8Array>;
+    /**
+     * 实际返回的字节范围（均包含在内）；完整读取时省略。
+     */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * 列举对象的选项。
+ */
+export interface ListObjectsOptions extends StorageOperationOptions {
+    /**
+     * 只返回以该前缀开头的对象。
+     */
+    prefix?: string;
+    /**
+     * 目录分隔符；设置后，分隔符之后的层级会合并到 `prefixes`。
+     */
+    delimiter?: string;
+    /**
+     * 上一页返回的游标。
+     */
+    cursor?: string;
+    /**
+     * 单页最大条目数，取值范围 1 到 1000，默认为 1000。
+     */
+    limit?: number;
+}
+/**
+ * 分页列举结果。
+ */
+export interface ListObjectsResult {
+    /**
+     * 当前页对象。
+     */
+    objects: ObjectInfo[];
+    /**
+     * 按分隔符折叠出的公共前缀。
+     */
+    prefixes: string[];
+    /**
+     * 下一页游标；不存在时表示已到最后一页。
+     */
+    cursor?: string;
+}
+/**
+ * 批量删除结果。
+ */
+export interface DeleteObjectsResult {
+    /**
+     * 删除成功的对象键。
+     */
+    deleted: string[];
+    /**
+     * 删除失败的对象键及原因。
+     */
+    failed: Array<{
+        key: string;
+        error: unknown;
+    }>;
+}
+/**
+ * 签名 URL 的 HTTP 方法。
+ */
+export type SignedUrlMethod = 'GET' | 'PUT';
+/**
+ * 生成签名 URL 的选项。
+ */
+export interface SignedUrlOptions extends StorageOperationOptions {
+    /**
+     * 允许的 HTTP 方法，默认为 `GET`。
+     */
+    method?: SignedUrlMethod;
+    /**
+     * 有效期秒数，取值范围 1 到 604800，默认为 900。
+     */
+    expiresIn?: number;
+    /**
+     * `PUT` 签名要求客户端使用的 MIME 类型。
+     */
+    contentType?: string;
+    /**
+     * `GET` 下载时覆盖的 `Content-Disposition` 响应头。
+     */
+    responseContentDisposition?: string;
+}
+/**
+ * 分片上传会话。
+ */
+export interface MultipartUpload {
+    /**
+     * 对业务可见的对象键。
+     */
+    key: string;
+    /**
+     * 后端分配的上传会话标识。
+     */
+    uploadId: string;
+}
+/**
+ * 已上传的分片。
+ */
+export interface MultipartUploadPart {
+    /**
+     * 分片序号，取值范围 1 到 10000。
+     */
+    partNumber: number;
+    /**
+     * 分片实体标签。
+     */
+    etag: string;
+}
+/**
+ * 自动分片上传的选项。
+ */
+export interface MultipartUploadOptions extends PutObjectOptions {
+    /**
+     * 分片字节数，不得小于 100 KiB，默认为服务配置。
+     */
+    partSize?: number;
+    /**
+     * 并行上传的分片数，默认为服务配置。
+     */
+    concurrency?: number;
+}
+/**
+ * 校验签名 URL 时提供的请求信息。
+ */
+export interface VerifyUrlRequest {
+    /**
+     * 完整请求 URL。
+     */
+    url: string | URL;
+    /**
+     * 实际请求的 HTTP 方法，默认为 `GET`。
+     */
+    method?: string;
+    /**
+     * 实际请求的 `Content-Type`，用于校验 `PUT` 签名。
+     */
+    contentType?: string;
+}
+/**
+ * 签名 URL 校验通过后的授权信息。
+ */
+export interface VerifiedUrl {
+    /**
+     * 签名所授权的对象键。
+     */
+    key: string;
+    /**
+     * 签名所授权的 HTTP 方法。
+     */
+    method: SignedUrlMethod;
+    /**
+     * 过期时间的 Unix 秒时间戳。
+     */
+    expires: number;
+    /**
+     * 签名要求的 PUT `Content-Type`。
+     */
+    contentType?: string;
+    /**
+     * 签名要求的 `Content-Disposition` 响应头。
+     */
+    responseContentDisposition?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}