feat(zipatch): support virtual filesystem

Author: zhyupe

packages/zipatch/src/chunks/sqpk.ts

@@ -1,7 +1,7 @@
 import { inflateRawSync } from 'node:zlib'
 import $debug from 'debug'
 import { SmartBuffer } from 'smart-buffer'
-import type { FileSystem } from '../fs'
+import type { ZipatchFileSystem } from '../fs'
 import type { ZipatchChunkHandler } from '../interface'
 import {
   type FileHeader,
@@ -27,7 +27,7 @@ const debug = $debug('zipatch:sqpk')
  * Handles SqPack-based game install operations
  */
 
-type SqpkHandler = (buffer: SmartBuffer, fs: FileSystem) => Promise<void>
+type SqpkHandler = (buffer: SmartBuffer, fs: ZipatchFileSystem) => Promise<void>
 
 const eraseHandler: SqpkHandler = async (buffer, fs) => {
   const payload = readSqpkDataHeader(buffer)
@@ -55,10 +55,9 @@ const blockHeaderSize = 16
 const addFileHandler = async (
   fileHeader: FileHeader,
   buffer: SmartBuffer,
-  fs: FileSystem,
+  fs: ZipatchFileSystem,
 ) => {
-  const handle = await fs.getFileHandle(fileHeader.filePath)
-  if (!handle) {
+  if (!fs.isPathAllowed(fileHeader.filePath)) {
     return
   }
 
@@ -95,10 +94,10 @@ const addFileHandler = async (
     const data = buffer.readBuffer(blockHeader.blockSize)
     if (blockHeader.isBlockCompressed) {
       const inflated = inflateRawSync(data)
-      await handle.write(inflated, 0, inflated.length, offset)
+      await fs.write(fileHeader.filePath, inflated, offset)
       bytesWritten += inflated.length
     } else {
-      await handle.write(data, 0, data.length, offset)
+      await fs.write(fileHeader.filePath, data, offset)
       bytesWritten += data.length
     }
 

packages/zipatch/src/fs.ts

@@ -6,14 +6,33 @@ import $debug from 'debug'
 const debug = $debug('zipatch:fs')
 
 const zeroBuffer = Buffer.alloc(1024, 0)
-export class FileSystem {
+export interface FileRange {
+  start: number
+  end: number
+}
+
+export interface ZipatchFileSystem {
+  workspace: string
+  close(): Promise<void>
+  isPathAllowed(path: string): boolean
+  write(path: string, buf: Buffer, offset?: number): Promise<boolean>
+  erase(path: string, length: number, offset: number): Promise<boolean>
+  createDirectory(path: string): Promise<void>
+  removeDirectory(path: string): Promise<void>
+}
+
+export class FileSystem implements ZipatchFileSystem {
   private fileHandles = new Map<string, FileHandle>()
 
   constructor(
     private root: string,
     private allowList: string[] = [],
   ) {}
 
+  get workspace(): string {
+    return this.root
+  }
+
   /**
    * Close all open file handles
    */
@@ -35,7 +54,14 @@ export class FileSystem {
    * Check if a path is allowed based on the allowlist
    */
   isPathAllowed(path: string): boolean {
-    return !this.allowList.length || this.allowList.includes(path)
+    return (
+      !this.allowList.length ||
+      this.allowList.some((pattern) =>
+        pattern.endsWith('*')
+          ? path.startsWith(pattern.slice(0, -1))
+          : pattern === path,
+      )
+    )
   }
 
   /**
@@ -128,3 +154,81 @@ export class FileSystem {
     return handle
   }
 }
+
+export class VirtualFileSystem implements ZipatchFileSystem {
+  private ranges = new Map<string, FileRange[]>()
+
+  constructor(
+    private root: string,
+    private allowList: string[] = [],
+  ) {}
+
+  get workspace(): string {
+    return this.root
+  }
+
+  async close(): Promise<void> {
+    // do nothing
+  }
+
+  isPathAllowed(path: string): boolean {
+    return (
+      !this.allowList.length ||
+      this.allowList.some((pattern) =>
+        pattern.endsWith('*')
+          ? path.startsWith(pattern.slice(0, -1))
+          : pattern === path,
+      )
+    )
+  }
+
+  async write(path: string, buf: Buffer, offset: number = 0): Promise<boolean> {
+    this.recordRange(path, offset, offset + buf.length)
+    return true
+  }
+
+  async erase(path: string, length: number, offset: number): Promise<boolean> {
+    this.recordRange(path, offset, offset + length)
+    return true
+  }
+
+  async createDirectory(path: string): Promise<void> {
+    // do nothing
+  }
+
+  async removeDirectory(path: string): Promise<void> {
+    // do nothing
+  }
+
+  getRecordedRanges(): Map<string, FileRange[]> {
+    return new Map(
+      [...this.ranges.entries()].map(([path, ranges]) => [
+        path,
+        ranges.map((range) => ({ ...range })),
+      ]),
+    )
+  }
+
+  private recordRange(path: string, start: number, end: number) {
+    if (!this.isPathAllowed(path)) {
+      return
+    }
+
+    const ranges = this.ranges.get(path) ?? []
+    ranges.push({ start, end })
+    ranges.sort((left, right) => left.start - right.start)
+
+    const merged: FileRange[] = []
+    for (const range of ranges) {
+      const current = merged.at(-1)
+      if (!current || range.start > current.end) {
+        merged.push({ ...range })
+        continue
+      }
+
+      current.end = Math.max(current.end, range.end)
+    }
+
+    this.ranges.set(path, merged)
+  }
+}

packages/zipatch/src/index.ts

@@ -9,7 +9,7 @@ import {
   type ZipatchPreloadData,
   type ZipatchPreloadedChunk,
 } from './datasource'
-import { FileSystem } from './fs'
+import { FileSystem, VirtualFileSystem, type ZipatchFileSystem } from './fs'
 import type { ZipatchChunk, ZipatchContext } from './interface'
 
 const zipatchMagic = [
@@ -25,6 +25,12 @@ export type {
   ZipatchPreloadData,
   ZipatchPreloadedChunk,
 } from './datasource'
+export {
+  type FileRange,
+  FileSystem,
+  VirtualFileSystem,
+  type ZipatchFileSystem,
+} from './fs'
 
 export class ZipatchReader {
   private source!: ZipatchDataSource
@@ -127,12 +133,15 @@ export class ZipatchReader {
    * Extract the zipatch file to a directory.
    */
   async applyTo(path: string, allowList: string[] = []) {
-    // Ensure the extraction directory exists
     const fs = new FileSystem(path, allowList)
+    await this.apply(fs, allowList)
+  }
+
+  async apply(fs: ZipatchFileSystem, allowList: string[] = []) {
     await fs.createDirectory('/')
     const context: ZipatchContext = {
       platform: 'win32',
-      workspace: path,
+      workspace: fs.workspace,
       allowList,
       fs,
     }

packages/zipatch/src/interface.ts

@@ -1,10 +1,10 @@
-import type { FileSystem } from './fs'
+import type { ZipatchFileSystem } from './fs'
 
 export interface ZipatchContext {
   platform: 'win32'
   workspace: string
   allowList: string[]
-  fs: FileSystem
+  fs: ZipatchFileSystem
 }
 
 export interface ZipatchChunk {