@objectstack/service-storage 4.0.5 → 4.1.0

package/README.md

@@ -7,7 +7,7 @@ Storage Service for ObjectStack — implements `IStorageService` with local file
 - **Multiple Adapters**: Local filesystem (development) and S3-compatible storage (production)
 - **Presigned Uploads**: Browser-direct upload via presigned URLs (S3 native, local HMAC-signed tokens)
 - **Chunked / Multipart Upload**: Resumable large file uploads with progress tracking
-- **File Metadata Store**: `system_file` object tracks fileId → key mapping and lifecycle status
+- **File Metadata Store**: `sys_file` object tracks fileId → key mapping and lifecycle status
 - **REST Routes**: Auto-mounted `/api/v1/storage/*` endpoints consumed by `@objectstack/client`
 - **Type-Safe**: Full TypeScript support with Zod-validated API contracts
 
@@ -125,7 +125,7 @@ const completed = await client.storage.resumeUpload(
                               ▼                         ▼
                      ┌─────────────────┐      ┌─────────────────┐
                      │ MetadataStore   │      │ Filesystem / S3  │
-                     │ (system_file)   │      │ (actual bytes)   │
+                     │ (sys_file)      │      │ (actual bytes)   │
                      └─────────────────┘      └─────────────────┘
 ```
 
@@ -133,9 +133,41 @@ const completed = await client.storage.resumeUpload(
 
 The plugin registers two system objects via the manifest service:
 
-- **`system_file`** — File metadata (fileId, key, name, mimeType, size, scope, status)
-- **`system_upload_session`** — Chunked upload state (progress, parts, resumeToken)
+- **`sys_file`** — File metadata (fileId, key, name, mimeType, size, scope, status)
+- **`sys_upload_session`** — Chunked upload state (progress, parts, resumeToken)
 
 ## License
 
 Apache-2.0
+
+## UI-driven configuration
+
+`StorageServicePlugin` registers a `storage` Settings namespace (mail-style)
+so administrators can switch adapter, configure S3 credentials, and tune
+TTL / max-upload limits from the Settings hub instead of restarting the
+process.
+
+- Service key in the kernel: `file-storage` — registered as a
+  `SwappableStorageService` proxy at `init` time. The inner adapter
+  (local FS or S3) is rebuilt and swapped in on every `settings:changed`
+  event for `namespace=storage`.
+- The S3 secret key is stored encrypted in `sys_secret` via the
+  CryptoAdapter / KMS chain set up by `service-settings`.
+- A `storage/test` action handler uploads → downloads → deletes a small
+  probe blob to validate the configuration end-to-end. The handler is
+  registered on `kernel:ready`; the `service-settings` package ships a
+  validation-only fallback for kernels that mount Settings but not
+  Storage.
+
+### ⚠ Switching adapters does not migrate files
+
+Files uploaded under the previous adapter remain on that backend and
+become unreachable through the new one. The plugin logs a warning on
+every swap. Migrate data out-of-band (e.g. `aws s3 sync` from the local
+root to the new bucket) before flipping the toggle in production.
+
+### Disabling the live-wire
+
+Pass `bindToSettings: false` to keep the constructor-supplied adapter
+frozen — useful in tests and in deployments where storage config must
+come from env vars only.

package/dist/index.cjs

@@ -301,6 +301,7 @@ __export(index_exports, {
   S3StorageAdapter: () => S3StorageAdapter,
   StorageMetadataStore: () => StorageMetadataStore,
   StorageServicePlugin: () => StorageServicePlugin,
+  SwappableStorageService: () => SwappableStorageService,
   SystemFile: () => SystemFile,
   SystemUploadSession: () => SystemUploadSession,
   registerStorageRoutes: () => registerStorageRoutes
@@ -515,6 +516,9 @@ var LocalStorageAdapter = class {
   }
 };
 
+// src/storage-service-plugin.ts
+init_s3_storage_adapter();
+
 // src/metadata-store.ts
 var StorageMetadataStore = class {
   constructor(engine) {
@@ -531,7 +535,7 @@ var StorageMetadataStore = class {
     this.files.set(full.id, full);
     if (this.engine) {
       try {
-        await this.engine.insert("system_file", full);
+        await this.engine.insert("sys_file", full);
       } catch {
       }
     }
@@ -540,7 +544,7 @@ var StorageMetadataStore = class {
   async getFile(id) {
     if (this.engine) {
       try {
-        const found = await this.engine.findOne("system_file", { where: { id } });
+        const found = await this.engine.findOne("sys_file", { where: { id } });
         if (found) return found;
       } catch {
       }
@@ -554,7 +558,7 @@ var StorageMetadataStore = class {
     this.files.set(id, merged);
     if (this.engine) {
       try {
-        await this.engine.update("system_file", merged, { where: { id } });
+        await this.engine.update("sys_file", merged, { where: { id } });
       } catch {
       }
     }
@@ -564,7 +568,7 @@ var StorageMetadataStore = class {
     this.files.delete(id);
     if (this.engine) {
       try {
-        await this.engine.delete("system_file", { where: { id } });
+        await this.engine.delete("sys_file", { where: { id } });
       } catch {
       }
     }
@@ -585,7 +589,7 @@ var StorageMetadataStore = class {
     this.sessions.set(full.id, full);
     if (this.engine) {
       try {
-        await this.engine.insert("system_upload_session", full);
+        await this.engine.insert("sys_upload_session", full);
       } catch {
       }
     }
@@ -594,7 +598,7 @@ var StorageMetadataStore = class {
   async getSession(id) {
     if (this.engine) {
       try {
-        const found = await this.engine.findOne("system_upload_session", { where: { id } });
+        const found = await this.engine.findOne("sys_upload_session", { where: { id } });
         if (found) return found;
       } catch {
       }
@@ -613,7 +617,7 @@ var StorageMetadataStore = class {
     this.sessions.set(id, merged);
     if (this.engine) {
       try {
-        await this.engine.update("system_upload_session", merged, { where: { id } });
+        await this.engine.update("sys_upload_session", merged, { where: { id } });
       } catch {
       }
     }
@@ -623,7 +627,7 @@ var StorageMetadataStore = class {
     this.sessions.delete(id);
     if (this.engine) {
       try {
-        await this.engine.delete("system_upload_session", { where: { id } });
+        await this.engine.delete("sys_upload_session", { where: { id } });
       } catch {
       }
     }
@@ -916,6 +920,28 @@ function registerStorageRoutes(httpServer, storage, store, opts = {}) {
       res.status(500).json({ error: err.message ?? "Internal error" });
     }
   });
+  httpServer.get(`${basePath}/files/:fileId`, async (req, res) => {
+    try {
+      const { fileId } = req.params;
+      const file = await store.getFile(fileId);
+      if (!file || file.status !== "committed") {
+        res.status(404).json({ error: "File not found or not committed" });
+        return;
+      }
+      let url;
+      if (storage.getPresignedDownload) {
+        const desc = await storage.getPresignedDownload(file.key, presignedTtl);
+        url = desc.downloadUrl;
+      } else if (storage.getSignedUrl) {
+        url = await storage.getSignedUrl(file.key, presignedTtl);
+      } else {
+        url = `${basePath}/_local/file/${encodeURIComponent(file.key)}`;
+      }
+      res.status(302).header("Location", url).send("");
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
   httpServer.put(`${basePath}/_local/raw/:token`, async (req, res) => {
     try {
       const { token } = req.params;
@@ -968,7 +994,7 @@ function buildKey(scope, fileId, filename) {
 // src/objects/system-file.object.ts
 var import_data = require("@objectstack/spec/data");
 var SystemFile = import_data.ObjectSchema.create({
-  name: "system_file",
+  name: "sys_file",
   label: "System File",
   pluralLabel: "System Files",
   icon: "file",
@@ -1014,7 +1040,7 @@ var SystemFile = import_data.ObjectSchema.create({
       label: "ACL",
       options: [
         { label: "Private", value: "private" },
-        { label: "Public Read", value: "public-read" }
+        { label: "Public Read", value: "public_read" }
       ]
     }),
     status: import_data.Field.select({
@@ -1047,7 +1073,7 @@ var SystemFile = import_data.ObjectSchema.create({
 // src/objects/system-upload-session.object.ts
 var import_data2 = require("@objectstack/spec/data");
 var SystemUploadSession = import_data2.ObjectSchema.create({
-  name: "system_upload_session",
+  name: "sys_upload_session",
   label: "System Upload Session",
   pluralLabel: "System Upload Sessions",
   icon: "upload-cloud",
@@ -1134,6 +1160,103 @@ var SystemUploadSession = import_data2.ObjectSchema.create({
   }
 });
 
+// src/swappable-storage-service.ts
+var SwappableStorageService = class {
+  constructor(initial, onSwap) {
+    this.inner = initial;
+    this.onSwap = onSwap;
+  }
+  /** Replace the inner adapter. */
+  swap(next) {
+    const previous = this.inner;
+    this.inner = next;
+    this.onSwap?.(previous, next);
+  }
+  /** Expose the active inner adapter — primarily for tests. */
+  getInner() {
+    return this.inner;
+  }
+  upload(key, data, options) {
+    return this.inner.upload(key, data, options);
+  }
+  download(key) {
+    return this.inner.download(key);
+  }
+  delete(key) {
+    return this.inner.delete(key);
+  }
+  exists(key) {
+    return this.inner.exists(key);
+  }
+  getInfo(key) {
+    return this.inner.getInfo(key);
+  }
+  list(prefix) {
+    if (typeof this.inner.list !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support list()"));
+    }
+    return this.inner.list(prefix);
+  }
+  getSignedUrl(key, expiresIn) {
+    if (typeof this.inner.getSignedUrl !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getSignedUrl()"));
+    }
+    return this.inner.getSignedUrl(key, expiresIn);
+  }
+  getPresignedUpload(key, expiresIn, options) {
+    if (typeof this.inner.getPresignedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getPresignedUpload()"));
+    }
+    return this.inner.getPresignedUpload(key, expiresIn, options);
+  }
+  getPresignedDownload(key, expiresIn) {
+    if (typeof this.inner.getPresignedDownload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getPresignedDownload()"));
+    }
+    return this.inner.getPresignedDownload(key, expiresIn);
+  }
+  initiateChunkedUpload(key, options) {
+    if (typeof this.inner.initiateChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support initiateChunkedUpload()"));
+    }
+    return this.inner.initiateChunkedUpload(key, options);
+  }
+  uploadChunk(uploadId, partNumber, data) {
+    if (typeof this.inner.uploadChunk !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support uploadChunk()"));
+    }
+    return this.inner.uploadChunk(uploadId, partNumber, data);
+  }
+  completeChunkedUpload(uploadId, parts) {
+    if (typeof this.inner.completeChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support completeChunkedUpload()"));
+    }
+    return this.inner.completeChunkedUpload(uploadId, parts);
+  }
+  abortChunkedUpload(uploadId) {
+    if (typeof this.inner.abortChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support abortChunkedUpload()"));
+    }
+    return this.inner.abortChunkedUpload(uploadId);
+  }
+  /**
+   * Verify a presigned HMAC token (LocalStorageAdapter-specific).
+   *
+   * `IStorageService` does not declare this method, but `storage-routes`
+   * type-narrows the active storage to `LocalStorageAdapter` to handle the
+   * `/_local/raw/:token` PUT and GET endpoints. Without a passthrough on
+   * the swappable wrapper, the route sees `verifyToken === undefined` and
+   * returns 501 even though the underlying local adapter supports it.
+   */
+  verifyToken(token, expectedOp) {
+    const inner = this.inner;
+    if (typeof inner.verifyToken !== "function") {
+      throw new Error("Active storage adapter does not support verifyToken()");
+    }
+    return inner.verifyToken(token, expectedOp);
+  }
+};
+
 // src/storage-service-plugin.ts
 var StorageServicePlugin = class {
   constructor(options = {}) {
@@ -1144,22 +1267,57 @@ var StorageServicePlugin = class {
     this.store = null;
     this.options = { adapter: "local", ...options };
   }
+  /** Build a concrete adapter from a values map (settings-derived). */
+  async buildAdapterFromValues(values) {
+    const adapter = String(values.adapter ?? "local");
+    if (adapter === "s3") {
+      const bucket = values.s3_bucket;
+      const region = values.s3_region;
+      if (!bucket || !region) {
+        throw new Error("StorageServicePlugin: S3 adapter requires s3_bucket and s3_region");
+      }
+      const opts = {
+        bucket,
+        region,
+        endpoint: values.s3_endpoint || void 0,
+        accessKeyId: values.s3_access_key_id || void 0,
+        secretAccessKey: values.s3_secret_access_key || void 0,
+        forcePathStyle: !!values.s3_force_path_style
+      };
+      return new S3StorageAdapter(opts);
+    }
+    const rootDir = values.local_root || "./storage";
+    return new LocalStorageAdapter({
+      basePath: this.options.basePath ?? "/api/v1/storage",
+      ...this.options.local ?? {},
+      // settings value wins over any constructor-provided local.rootDir
+      rootDir
+    });
+  }
   async init(ctx) {
     const adapter = this.options.adapter;
+    let initial;
     if (adapter === "s3") {
-      const { S3StorageAdapter: S3StorageAdapter2 } = await Promise.resolve().then(() => (init_s3_storage_adapter(), s3_storage_adapter_exports));
+      const { S3StorageAdapter: S3Ctor } = await Promise.resolve().then(() => (init_s3_storage_adapter(), s3_storage_adapter_exports));
       const s3Opts = this.options.s3;
       if (!s3Opts) {
         throw new Error('StorageServicePlugin: s3 options are required when adapter is "s3"');
       }
-      this.storage = new S3StorageAdapter2(s3Opts);
+      initial = new S3Ctor(s3Opts);
     } else {
       const rootDir = this.options.local?.rootDir ?? "./storage";
       const basePath = this.options.basePath ?? "/api/v1/storage";
-      this.storage = new LocalStorageAdapter({ rootDir, basePath, ...this.options.local });
+      initial = new LocalStorageAdapter({ rootDir, basePath, ...this.options.local });
     }
+    this.storage = new SwappableStorageService(initial, (prev, next) => {
+      const prevName = prev?.constructor?.name ?? "unknown";
+      const nextName = next?.constructor?.name ?? "unknown";
+      ctx.logger.warn(
+        `StorageServicePlugin: storage adapter swapped (${prevName} \u2192 ${nextName}). Existing files were NOT migrated and may be unreachable through the new adapter.`
+      );
+    });
     ctx.registerService("file-storage", this.storage);
-    ctx.logger.info(`StorageServicePlugin: registered ${adapter} storage adapter`);
+    ctx.logger.info(`StorageServicePlugin: registered ${adapter} storage adapter (swappable)`);
     try {
       ctx.getService("manifest").register({
         id: "com.objectstack.service.storage",
@@ -1173,31 +1331,101 @@ var StorageServicePlugin = class {
     }
   }
   async start(ctx) {
-    if (this.options.registerRoutes === false) return;
     ctx.hook("kernel:ready", async () => {
-      let httpServer = null;
-      try {
-        httpServer = ctx.getService("http-server");
-      } catch {
-      }
-      if (!httpServer || !this.storage) {
-        ctx.logger.warn(
-          'StorageServicePlugin: no HTTP server available \u2014 REST routes not registered. File storage is still accessible programmatically via kernel.getService("file-storage").'
-        );
-        return;
+      if (this.options.registerRoutes !== false) {
+        let httpServer = null;
+        try {
+          httpServer = ctx.getService("http-server");
+        } catch {
+        }
+        if (httpServer && this.storage) {
+          let engine = null;
+          try {
+            engine = ctx.getService("objectql");
+          } catch {
+          }
+          this.store = new StorageMetadataStore(engine);
+          registerStorageRoutes(httpServer, this.storage, this.store, {
+            basePath: this.options.basePath ?? "/api/v1/storage",
+            presignedTtl: this.options.presignedTtl,
+            sessionTtl: this.options.sessionTtl
+          });
+          ctx.logger.info(
+            "StorageServicePlugin: REST routes registered at " + (this.options.basePath ?? "/api/v1/storage")
+          );
+        } else if (!httpServer) {
+          ctx.logger.warn(
+            'StorageServicePlugin: no HTTP server available \u2014 REST routes not registered. File storage is still accessible programmatically via kernel.getService("file-storage").'
+          );
+        }
       }
-      let engine = null;
+      if (this.options.bindToSettings === false) return;
       try {
-        engine = ctx.getService("objectql");
+        const settings = ctx.getService("settings");
+        if (!settings || typeof settings.createClient !== "function") return;
+        const applySettings = async () => {
+          if (!this.storage) return;
+          try {
+            const payload = await settings.getNamespace("storage");
+            const values = {};
+            for (const [k, v] of Object.entries(payload.values)) {
+              values[k] = v?.value;
+            }
+            const hasAny = Object.values(values).some((v) => v !== void 0 && v !== null && v !== "");
+            if (!hasAny) return;
+            const next = await this.buildAdapterFromValues(values);
+            this.storage.swap(next);
+          } catch (err) {
+            ctx.logger.warn(
+              "StorageServicePlugin: failed to apply storage settings: " + (err?.message ?? err)
+            );
+          }
+        };
+        await applySettings();
+        if (typeof settings.subscribe === "function") {
+          settings.subscribe("storage", () => {
+            void applySettings();
+          });
+          ctx.logger.info("StorageServicePlugin: bound to settings:changed for namespace=storage");
+        }
+        if (typeof settings.registerAction === "function" && this.storage) {
+          const proxy = this.storage;
+          settings.registerAction("storage", "test", async ({ values }) => {
+            const probeKey = `__objectstack_probe__/${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+            const probeBytes = Buffer.from(`probe@${(/* @__PURE__ */ new Date()).toISOString()}`, "utf-8");
+            try {
+              let target = proxy;
+              if (values && Object.keys(values).length > 0) {
+                try {
+                  target = await this.buildAdapterFromValues(values);
+                } catch (err) {
+                  return { ok: false, severity: "error", message: err?.message ?? String(err) };
+                }
+              }
+              await target.upload(probeKey, probeBytes, { contentType: "text/plain" });
+              const got = await target.download(probeKey);
+              if (!got || !Buffer.isBuffer(got) || got.toString("utf-8") !== probeBytes.toString("utf-8")) {
+                return { ok: false, severity: "error", message: "Probe download did not match upload." };
+              }
+              await target.delete(probeKey);
+              const adapter = String(values?.adapter ?? this.options.adapter ?? "local");
+              return {
+                ok: true,
+                severity: "info",
+                message: `Storage round-trip succeeded (adapter=${adapter}).`
+              };
+            } catch (err) {
+              try {
+                await proxy.delete(probeKey);
+              } catch {
+              }
+              return { ok: false, severity: "error", message: err?.message ?? String(err) };
+            }
+          });
+          ctx.logger.info("StorageServicePlugin: registered settings action storage/test");
+        }
       } catch {
       }
-      this.store = new StorageMetadataStore(engine);
-      registerStorageRoutes(httpServer, this.storage, this.store, {
-        basePath: this.options.basePath ?? "/api/v1/storage",
-        presignedTtl: this.options.presignedTtl,
-        sessionTtl: this.options.sessionTtl
-      });
-      ctx.logger.info("StorageServicePlugin: REST routes registered at " + (this.options.basePath ?? "/api/v1/storage"));
     });
   }
 };
@@ -1210,6 +1438,7 @@ init_s3_storage_adapter();
   S3StorageAdapter,
   StorageMetadataStore,
   StorageServicePlugin,
+  SwappableStorageService,
   SystemFile,
   SystemUploadSession,
   registerStorageRoutes