@southwind-ai/storage 0.1.0

package/src/upload-streams.ts

@@ -0,0 +1,123 @@
+import type { ArtifactRef, BlobStore } from "./blob-store.js";
+import { UploadError } from "./upload-types.js";
+
+export function concatBlobStreams(
+  store: BlobStore,
+  refs: readonly ArtifactRef[],
+): ReadableStream<Uint8Array> {
+  let current: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let index = 0;
+  return new ReadableStream({
+    async pull(controller) {
+      while (true) {
+        if (!current) {
+          const ref = refs[index++];
+          if (!ref) return controller.close();
+          const blob = await store.open(ref);
+          if (!blob) {
+            return controller.error(
+              new UploadError("UPLOAD_INCOMPLETE", "上传分片内容不存在"),
+            );
+          }
+          current = blob.body.getReader();
+        }
+        const result = await current.read();
+        if (result.done) {
+          current.releaseLock();
+          current = undefined;
+          continue;
+        }
+        controller.enqueue(result.value);
+        return;
+      }
+    },
+    async cancel(reason) {
+      await current?.cancel(reason);
+    },
+  });
+}
+
+export function guardFileSignature(
+  body: ReadableStream<Uint8Array>,
+  mimeType: string,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  const requiredBytes = signatureByteCount(mimeType);
+  const pending: Uint8Array[] = [];
+  const prefix = new Uint8Array(requiredBytes);
+  let prefixSize = 0;
+  let checked = false;
+  return new ReadableStream({
+    async pull(controller) {
+      if (!checked) {
+        while (prefixSize < requiredBytes) {
+          const result = await reader.read();
+          if (result.done) {
+            controller.error(signatureError());
+            return;
+          }
+          pending.push(result.value);
+          const needed = requiredBytes - prefixSize;
+          const slice = result.value.subarray(0, needed);
+          prefix.set(slice, prefixSize);
+          prefixSize += slice.byteLength;
+        }
+        checked = true;
+        if (!matchesSignature(prefix, mimeType)) {
+          await reader.cancel();
+          controller.error(signatureError());
+          return;
+        }
+      }
+      const buffered = pending.shift();
+      if (buffered) {
+        controller.enqueue(buffered);
+        return;
+      }
+      const result = await reader.read();
+      if (result.done) controller.close();
+      else controller.enqueue(result.value);
+    },
+    async cancel(reason) {
+      await reader.cancel(reason);
+    },
+  });
+}
+
+function signatureByteCount(mimeType: string) {
+  if (mimeType === "image/png") return 8;
+  if (mimeType === "image/jpeg") return 3;
+  if (mimeType === "image/webp") return 12;
+  return 1;
+}
+
+function matchesSignature(prefix: Uint8Array, mimeType: string): boolean {
+  if (mimeType === "image/png") {
+    return startsWith(prefix, [137, 80, 78, 71, 13, 10, 26, 10]);
+  }
+  if (mimeType === "image/jpeg") {
+    return startsWith(prefix, [255, 216, 255]);
+  }
+  if (mimeType === "image/webp") {
+    return text(prefix, 0, 4) === "RIFF" && text(prefix, 8, 12) === "WEBP";
+  }
+  return true;
+}
+
+function startsWith(value: Uint8Array, expected: number[]) {
+  return (
+    value.length >= expected.length &&
+    expected.every((byte, index) => value[index] === byte)
+  );
+}
+
+function text(value: Uint8Array, start: number, end: number) {
+  return new TextDecoder().decode(value.subarray(start, end));
+}
+
+function signatureError() {
+  return new UploadError(
+    "FILE_SIGNATURE_MISMATCH",
+    "文件内容与声明的 MIME 类型不一致",
+  );
+}

package/src/upload-types.ts

@@ -0,0 +1,110 @@
+import type { ArtifactRef, ContentHash } from "./blob-store.js";
+
+export type UploadSessionStatus =
+  | "uploading"
+  | "completed"
+  | "aborted"
+  | "expired";
+
+export interface UploadSession {
+  id: string;
+  ownerId: string;
+  purpose: string;
+  filename: string;
+  extension: string;
+  mimeType: string;
+  expectedByteSize: number;
+  expectedContentHash?: ContentHash;
+  receivedByteSize: number;
+  nextPartNumber: number;
+  status: UploadSessionStatus;
+  expiresAt: string;
+  fileExpiresAt?: string;
+  fileId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface UploadPart {
+  sessionId: string;
+  partNumber: number;
+  byteOffset: number;
+  artifactRef: ArtifactRef;
+  byteSize: number;
+  contentHash: ContentHash;
+  createdAt: string;
+}
+
+export interface FileMetadata {
+  id: string;
+  ownerId: string;
+  purpose: string;
+  filename: string;
+  extension: string;
+  mimeType: string;
+  artifactRef: ArtifactRef;
+  byteSize: number;
+  contentHash: ContentHash;
+  expiresAt?: string;
+  createdAt: string;
+}
+
+export interface OpenedFile extends FileMetadata {
+  body: ReadableStream<Uint8Array>;
+}
+
+export interface UploadPolicy {
+  purpose: string;
+  maxByteSize: number;
+  maxPartByteSize: number;
+  sessionTtlMs: number;
+  allowedTypes: Readonly<Record<string, readonly string[]>>;
+  signature?: "image" | "none";
+}
+
+export interface CreateUploadInput {
+  ownerId: string;
+  purpose: string;
+  filename: string;
+  mimeType: string;
+  expectedByteSize: number;
+  expectedSha256?: string;
+  fileExpiresAt?: Date;
+}
+
+export interface UploadPartInput {
+  sessionId: string;
+  ownerId: string;
+  partNumber: number;
+  byteOffset: number;
+  byteSize: number;
+  sha256: string;
+  body: ReadableStream<Uint8Array>;
+}
+
+export type UploadErrorCode =
+  | "INVALID_UPLOAD"
+  | "UNSUPPORTED_FILE_TYPE"
+  | "UPLOAD_TOO_LARGE"
+  | "PART_TOO_LARGE"
+  | "UPLOAD_NOT_FOUND"
+  | "UPLOAD_FORBIDDEN"
+  | "UPLOAD_NOT_ACTIVE"
+  | "UPLOAD_EXPIRED"
+  | "UPLOAD_OFFSET_CONFLICT"
+  | "UPLOAD_INCOMPLETE"
+  | "FILE_SIGNATURE_MISMATCH"
+  | "CONCURRENT_UPLOAD"
+  | "FILE_NOT_FOUND"
+  | "FILE_EXPIRED"
+  | "FILE_CONTENT_MISSING";
+
+export class UploadError extends Error {
+  constructor(
+    readonly code: UploadErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "UploadError";
+  }
+}