Add opaque byte storage to mod API

src/mods/Loader.lua

@@ -1069,7 +1069,8 @@ function Loader:_api(mod)
         bucket[key] = value
       end,
     },
-    -- Data-only state independent of the vanilla progress checkpoint. The
+    -- Data-only and opaque-byte state independent of the vanilla progress
+    -- checkpoint. The
     -- engine binds version/playthrough/mod scope and portable persistence;
     -- callers never receive paths or a raw filesystem handle.
     storage = {
@@ -1077,6 +1078,10 @@ function Loader:_api(mod)
       selected = function(_, game) return storage:selected(game) end,
       write = function(_, game, key, value) return storage:write(game, key, value) end,
       read = function(_, game, key) return storage:read(game, key) end,
+      writeBytes = function(_, game, key, bytes)
+        return storage:writeBytes(game, key, bytes)
+      end,
+      readBytes = function(_, game, key) return storage:readBytes(game, key) end,
       list = function(_, game, prefix) return storage:list(game, prefix) end,
       delete = function(_, game, key) return storage:delete(game, key) end,
     },

src/mods/Storage.lua

@@ -1,4 +1,5 @@
--- Data-only per-mod persistence, scoped by game version and opaque playthrough.
+-- Data-only and opaque-byte per-mod persistence, scoped by game version and
+-- opaque playthrough.
 -- This module is engine-private; Loader exposes only the bound facade methods.
 
 local SaveData = require("src.core.SaveData")
@@ -7,6 +8,7 @@ local Version = require("src.core.Version")
 
 local Storage = {}
 Storage.__index = Storage
+Storage.MAX_BYTES = 512 * 1024 * 1024
 
 local ROOT = "mod_storage"
 
@@ -49,6 +51,20 @@ local function decodeAt(fs, path)
   return data, body
 end
 
+local function readOpaqueAt(fs, path)
+  if not (fs.getInfo and fs.getInfo(path)) then return nil end
+  local body = fs.read and fs.read(path)
+  if type(body) ~= "string" then return nil end
+  return body
+end
+
+local function hasAny(fs, paths)
+  for _, path in ipairs(paths) do
+    if fs.getInfo(path) then return true end
+  end
+  return false
+end
+
 function Storage.new(modId, fs)
   assert(validSegment(modId), "Storage.new needs a safe mod id")
   return setmetatable({ modId = modId, injectedFs = fs }, Storage)
@@ -132,6 +148,10 @@ function Storage:selected(game)
     end,
     read = function(_, key) return self:read(selectedGame, key) end,
     write = function(_, key, value) return self:write(selectedGame, key, value) end,
+    readBytes = function(_, key) return self:readBytes(selectedGame, key) end,
+    writeBytes = function(_, key, bytes)
+      return self:writeBytes(selectedGame, key, bytes)
+    end,
     list = function(_, prefix) return self:list(selectedGame, prefix) end,
     delete = function(_, key) return self:delete(selectedGame, key) end,
   }
@@ -147,7 +167,7 @@ function Storage:context(game)
   }
 end
 
-function Storage:_names(game, key, allowEmpty)
+function Storage:_names(game, key, allowEmpty, extension)
   if not validKey(key, allowEmpty) then
     return failure("invalid_key",
       "Storage keys use nonempty letters, numbers, underscore, dash and slash segments.")
@@ -155,12 +175,19 @@ function Storage:_names(game, key, allowEmpty)
   local scope, code, message = self:_scope(game)
   if not scope then return nil, code, message end
   local path = scope.base .. (key ~= "" and ("/" .. key) or "")
-  return scope, path .. ".lua", path .. ".lua.bak", path .. ".lua.tmp"
+  extension = extension or ".lua"
+  return scope, path .. extension, path .. extension .. ".bak",
+    path .. extension .. ".tmp", path
 end
 
 function Storage:write(game, key, value)
-  local scope, main, bak, tmp = self:_names(game, key, false)
+  local scope, main, bak, tmp, path = self:_names(game, key, false)
   if not scope then return false, main, bak end
+  local fs = scope.fs
+  if hasAny(fs, { path .. ".bin", path .. ".bin.bak", path .. ".bin.tmp" }) then
+    return false, "type_conflict",
+      "A byte value already exists for this storage key; delete it first."
+  end
   if type(value) ~= "table" then
     return false, "encode_failed", "Storage values must be data-only tables."
   end
@@ -170,7 +197,6 @@ function Storage:write(game, key, value)
       .. tostring(encoded)
   end
 
-  local fs = scope.fs
   ensureParent(fs, main)
   local _, previous = decodeAt(fs, main)
   if not previous then _, previous = decodeAt(fs, bak) end
@@ -206,9 +232,13 @@ function Storage:write(game, key, value)
 end
 
 function Storage:read(game, key)
-  local scope, main, bak, tmp = self:_names(game, key, false)
+  local scope, main, bak, tmp, path = self:_names(game, key, false)
   if not scope then return nil, main, bak end
   local fs = scope.fs
+  if hasAny(fs, { path .. ".bin", path .. ".bin.bak", path .. ".bin.tmp" }) then
+    return failure("type_mismatch",
+      "This storage key contains opaque bytes; use readBytes instead.")
+  end
   local data, body = decodeAt(fs, main)
   if data then return data end
 
@@ -226,6 +256,80 @@ function Storage:read(game, key)
   return data
 end
 
+function Storage:writeBytes(game, key, bytes)
+  local scope, main, bak, tmp, path = self:_names(game, key, false, ".bin")
+  if not scope then return false, main, bak end
+  if type(bytes) ~= "string" then
+    return false, "invalid_bytes", "Opaque storage values must be strings."
+  end
+  if #bytes > Storage.MAX_BYTES then
+    return false, "size_limit",
+      ("Opaque storage values cannot exceed %d bytes."):format(Storage.MAX_BYTES)
+  end
+
+  local fs = scope.fs
+  if hasAny(fs, { path .. ".lua", path .. ".lua.bak", path .. ".lua.tmp" }) then
+    return false, "type_conflict",
+      "A table value already exists for this storage key; delete it first."
+  end
+
+  ensureParent(fs, main)
+  local previous = readOpaqueAt(fs, main)
+  if previous == nil then previous = readOpaqueAt(fs, bak) end
+
+  local ok, err = fs.write(tmp, bytes)
+  if not ok then
+    return false, "write_failed", "Could not stage opaque storage data: " .. tostring(err)
+  end
+  local staged = readOpaqueAt(fs, tmp)
+  if staged == nil or staged ~= bytes then
+    remove(fs, tmp)
+    return false, "verify_failed", "Staged opaque storage data could not be verified."
+  end
+
+  if previous ~= nil then fs.write(bak, previous) end
+  ok, err = fs.write(main, bytes)
+  if not ok then
+    remove(fs, tmp)
+    return false, "write_failed",
+      "Could not replace opaque storage data: " .. tostring(err)
+  end
+  local verified = readOpaqueAt(fs, main)
+  if verified == nil or verified ~= bytes then
+    remove(fs, main)
+    remove(fs, tmp)
+    return false, "verify_failed",
+      "Replacement opaque storage data could not be verified."
+  end
+
+  fs.write(bak, bytes)
+  remove(fs, tmp)
+  return true
+end
+
+function Storage:readBytes(game, key)
+  local scope, main, bak, tmp, path = self:_names(game, key, false, ".bin")
+  if not scope then return nil, main, bak end
+  local fs = scope.fs
+  if hasAny(fs, { path .. ".lua", path .. ".lua.bak", path .. ".lua.tmp" }) then
+    return failure("type_mismatch",
+      "This storage key contains table data; use read instead.")
+  end
+
+  local bytes = readOpaqueAt(fs, main)
+  if bytes ~= nil then return bytes end
+  bytes = readOpaqueAt(fs, tmp)
+  if bytes == nil then bytes = readOpaqueAt(fs, bak) end
+  if bytes == nil then
+    return nil, "not_found", "No valid opaque value exists for this key."
+  end
+
+  ensureParent(fs, main)
+  if fs.write(main, bytes) then fs.write(bak, bytes) end
+  remove(fs, tmp)
+  return bytes
+end
+
 function Storage:list(game, prefix)
   prefix = prefix or ""
   local scope, main, codeOrBak = self:_names(game, prefix, true)
@@ -237,13 +341,23 @@ function Storage:list(game, prefix)
 
   local base = scope.base
   local start = prefix == "" and base or (base .. "/" .. prefix)
-  local out = {}
+  local out, seen = {}, {}
+
+  local function add(logical)
+    if not seen[logical] then
+      seen[logical] = true
+      out[#out + 1] = logical
+    end
+  end
 
   local function walk(path, logical)
     local info = fs.getInfo(path)
     if not info then return end
     if info.type == "file" then
-      if path:sub(-4) == ".lua" then out[#out + 1] = logical:sub(1, -5) end
+      local suffix = path:sub(-4)
+      if suffix == ".lua" or suffix == ".bin" then
+        add(logical:sub(1, -5))
+      end
       return
     end
     for _, child in ipairs(fs.getDirectoryItems(path) or {}) do
@@ -254,7 +368,9 @@ function Storage:list(game, prefix)
 
   -- A prefix may identify one exact key or a directory of keys.
   if fs.getInfo(start .. ".lua") then
-    out[#out + 1] = prefix
+    add(prefix)
+  elseif fs.getInfo(start .. ".bin") then
+    add(prefix)
   else
     walk(start, prefix)
   end
@@ -263,15 +379,20 @@ function Storage:list(game, prefix)
 end
 
 function Storage:delete(game, key)
-  local scope, main, bak, tmp = self:_names(game, key, false)
+  local scope, main, bak, tmp, path = self:_names(game, key, false)
   if not scope then return false, main, bak end
   local fs = scope.fs
-  if not (fs.getInfo(main) or fs.getInfo(bak) or fs.getInfo(tmp)) then
+  local byteMain, byteBak, byteTmp = path .. ".bin", path .. ".bin.bak", path .. ".bin.tmp"
+  if not (fs.getInfo(main) or fs.getInfo(bak) or fs.getInfo(tmp)
+      or fs.getInfo(byteMain) or fs.getInfo(byteBak) or fs.getInfo(byteTmp)) then
     return false, "not_found", "No stored value exists for this key."
   end
   remove(fs, main)
   remove(fs, bak)
   remove(fs, tmp)
+  remove(fs, byteMain)
+  remove(fs, byteBak)
+  remove(fs, byteTmp)
   return true
 end