@wangxiaocuo/dsh-session-trash 0.5.1 → 0.6.1

package/lib/store.js

@@ -2,10 +2,11 @@ import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { TrashError } from './errors.js'
-import { isInside, removePathWithRetry, renameWithRetry, samePath } from './fsops.js'
+import { isInside, isSafeMemberId, removePathWithRetry, renameWithRetry, samePath } from './fsops.js'
+import { isValidMemberList, parentMember } from './members.js'
 
 /** On-disk index schema version understood by this release. */
-export const INDEX_VERSION = 1
+export const INDEX_VERSION = 2
 
 /** A lock older than this is assumed abandoned and may be taken over. */
 export const LOCK_STALE_MS = 10 * 60 * 1000
@@ -21,6 +22,20 @@ export function emptyIndex(now = Date.now()) {
   return { version: INDEX_VERSION, updatedAt: now, entries: [] }
 }
 
+/**
+ * Coerce one durable entry to the v2 shape. A v1 entry names a single
+ * directory, which becomes the parent member of a one-member tree.
+ *
+ * @param {object} entry entry from either durable shape.
+ * @returns {object} the v2 entry.
+ */
+function normalizeEntry(entry) {
+  if (entry === null || typeof entry !== 'object') return entry
+  if (Array.isArray(entry.members) && entry.members.length > 0) return entry
+  const parent = parentMember(entry)
+  return parent === null ? entry : { ...entry, members: [parent] }
+}
+
 /**
  * Validate the persisted index shape strictly enough that a truncated or
  * hand-edited file enters protection mode instead of silently vanishing.
@@ -30,7 +45,7 @@ export function emptyIndex(now = Date.now()) {
  */
 export function isValidIndex(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
-  if (value.version !== INDEX_VERSION) return false
+  if (value.version !== INDEX_VERSION && value.version !== 1) return false
   if (typeof value.updatedAt !== 'number' || !Number.isFinite(value.updatedAt)) return false
   if (!Array.isArray(value.entries)) return false
   const seen = new Set()
@@ -42,6 +57,7 @@ export function isValidIndex(value) {
     if (typeof entry.trashedAt !== 'number' || !Number.isFinite(entry.trashedAt)) return false
     if (seen.has(entry.sessionId)) return false
     seen.add(entry.sessionId)
+    if (value.version === INDEX_VERSION && !isValidMemberList(entry)) return false
   }
   return true
 }
@@ -90,6 +106,8 @@ export class TrashStore {
     this.lockOwned = false
     this.lockTimer = null
     this.queue = Promise.resolve()
+    /** Whether the last load read an older index version that must be re-committed. */
+    this.needsUpgrade = false
   }
 
   /**
@@ -108,6 +126,10 @@ export class TrashStore {
     } else if (this.status === 'recovered') {
       this.logger.warn(`trash index recovered from backup: ${this.error}`)
     }
+    if (this.needsUpgrade) {
+      await this.writeIndex(this.index.entries)
+      this.logger.info(`upgraded the trash index to version ${INDEX_VERSION}`)
+    }
     return this.describe()
   }
 
@@ -150,12 +172,34 @@ export class TrashStore {
 
   /**
    * @param {string} trashId object identity.
-   * @returns {string} the moved session directory inside the object directory.
+   * @returns {string} the moved parent session directory inside the object directory.
    */
   sessionPath(trashId) {
     return path.join(this.objectDir(trashId), 'session')
   }
 
+  /**
+   * @param {string} trashId object identity.
+   * @param {string} sessionId descendant session identity.
+   * @returns {string} the moved descendant directory inside the object directory.
+   */
+  childPath(trashId, sessionId) {
+    if (!isSafeMemberId(sessionId)) {
+      throw new TrashError('IO_ERROR', 'Refusing an unsafe member directory name inside the trash object.')
+    }
+    return path.join(this.objectDir(trashId), 'children', sessionId)
+  }
+
+  /**
+   * @param {string} trashId object identity.
+   * @param {number} index member position; `0` is the visible parent.
+   * @param {string} sessionId member identity.
+   * @returns {string} the directory that owns this member inside the object.
+   */
+  memberPath(trashId, index, sessionId) {
+    return index === 0 ? this.sessionPath(trashId) : this.childPath(trashId, sessionId)
+  }
+
   /**
    * @param {string} trashId object identity.
    * @returns {string} the self-describing metadata path inside the object directory.
@@ -309,15 +353,17 @@ export class TrashStore {
   }
 
   /**
-   * Load the index, falling back to the previous committed backup.
+   * Load the index, falling back to the previous committed backup. An older
+   * schema is normalized in memory and re-committed by {@link init}.
    *
    * @returns {Promise<void>} resolution once `index` and `status` are set.
    */
   async load() {
+    this.needsUpgrade = false
     try {
       const data = await this.readJson(this.indexPath)
       if (!isValidIndex(data)) throw new Error('unsupported index shape or version')
-      this.index = data
+      this.index = this.normalizeIndex(data)
       this.status = 'ok'
       this.error = null
       return
@@ -332,7 +378,7 @@ export class TrashStore {
       try {
         const backup = await this.readJson(this.bakPath)
         if (!isValidIndex(backup)) throw new Error('unsupported backup shape or version')
-        this.index = backup
+        this.index = this.normalizeIndex(backup)
         this.status = 'recovered'
         this.error = primary
         return
@@ -345,6 +391,19 @@ export class TrashStore {
     }
   }
 
+  /**
+   * @param {{ version: number, updatedAt: number, entries: readonly object[] }} data parsed index document.
+   * @returns {{ version: number, updatedAt: number, entries: object[] }} the v2 document.
+   */
+  normalizeIndex(data) {
+    if (data.version !== INDEX_VERSION) this.needsUpgrade = true
+    return {
+      version: INDEX_VERSION,
+      updatedAt: data.updatedAt,
+      entries: data.entries.map((entry) => normalizeEntry(entry)),
+    }
+  }
+
   /**
    * Atomically commit the index: write a temporary file, preserve the previous
    * commit as `.bak`, then rename over the live index.
@@ -353,7 +412,8 @@ export class TrashStore {
    * @returns {Promise<{ version: number, updatedAt: number, entries: readonly object[] }>} the committed document.
    */
   async writeIndex(entries) {
-    const data = { version: INDEX_VERSION, updatedAt: Date.now(), entries }
+    const normalized = entries.map((entry) => normalizeEntry(entry))
+    const data = { version: INDEX_VERSION, updatedAt: Date.now(), entries: normalized }
     const json = `${JSON.stringify(data, null, 2)}\n`
     try {
       const handle = await fs.open(this.tmpPath, 'w', 0o600)
@@ -379,6 +439,7 @@ export class TrashStore {
     this.index = data
     this.status = 'ok'
     this.error = null
+    this.needsUpgrade = false
     return data
   }