@objectstack/service-storage 5.0.0 → 5.2.0

package/dist/index.cjs

@@ -56,10 +56,11 @@ async function streamToBuffer(stream) {
   }
   return Buffer.concat(chunks);
 }
-var S3StorageAdapter;
+var import_observability2, S3StorageAdapter;
 var init_s3_storage_adapter = __esm({
   "src/s3-storage-adapter.ts"() {
     "use strict";
+    import_observability2 = require("@objectstack/observability");
     S3StorageAdapter = class {
       constructor(options) {
         this.options = options;
@@ -72,6 +73,34 @@ var init_s3_storage_adapter = __esm({
         this.region = options.region;
         this.endpoint = options.endpoint;
         this.forcePathStyle = options.forcePathStyle ?? false;
+        this.metrics = options.metrics ?? new import_observability2.NoopMetricsRegistry();
+      }
+      /**
+       * Wrap a storage operation with metrics instrumentation.
+       * Records ok/error counters, a duration histogram, and an error counter
+       * keyed by error class on failure. Never swallows the underlying error.
+       */
+      async track(op, fn) {
+        const started = Date.now();
+        const baseLabels = { adapter: "s3", op };
+        try {
+          const out = await fn();
+          try {
+            this.metrics.counter(import_observability2.SEMCONV.storageOperationsTotal, { ...baseLabels, result: "ok" });
+            this.metrics.histogram(import_observability2.SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+          } catch {
+          }
+          return out;
+        } catch (err) {
+          try {
+            this.metrics.counter(import_observability2.SEMCONV.storageOperationsTotal, { ...baseLabels, result: "error" });
+            this.metrics.histogram(import_observability2.SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+            const errorClass = err?.name || err?.constructor?.name || "Error";
+            this.metrics.counter(import_observability2.SEMCONV.storageErrorsTotal, { ...baseLabels, errorClass });
+          } catch {
+          }
+          throw err;
+        }
       }
       /**
        * Lazily resolve the AWS S3 client to avoid crashing at import time when
@@ -121,67 +150,79 @@ var init_s3_storage_adapter = __esm({
       // Basic operations
       // ---------------------------------------------------------------------------
       async upload(key, data, options) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        const body = data instanceof Buffer ? data : await streamToBuffer(data);
-        const cmd = new s3.PutObjectCommand({
-          Bucket: this.bucket,
-          Key: key,
-          Body: body,
-          ContentType: options?.contentType,
-          Metadata: options?.metadata,
-          ACL: options?.acl === "public-read" ? "public-read" : void 0
+        return this.track("put", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          const body = data instanceof Buffer ? data : await streamToBuffer(data);
+          const cmd = new s3.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: body,
+            ContentType: options?.contentType,
+            Metadata: options?.metadata,
+            ACL: options?.acl === "public-read" ? "public-read" : void 0
+          });
+          await client.send(cmd);
         });
-        await client.send(cmd);
       }
       async download(key) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        const cmd = new s3.GetObjectCommand({ Bucket: this.bucket, Key: key });
-        const res = await client.send(cmd);
-        return streamToBuffer(res.Body);
+        return this.track("get", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          const cmd = new s3.GetObjectCommand({ Bucket: this.bucket, Key: key });
+          const res = await client.send(cmd);
+          return streamToBuffer(res.Body);
+        });
       }
       async delete(key) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        const cmd = new s3.DeleteObjectCommand({ Bucket: this.bucket, Key: key });
-        await client.send(cmd);
+        return this.track("delete", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          const cmd = new s3.DeleteObjectCommand({ Bucket: this.bucket, Key: key });
+          await client.send(cmd);
+        });
       }
       async exists(key) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        try {
-          const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
-          await client.send(cmd);
-          return true;
-        } catch (err) {
-          if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) return false;
-          throw err;
-        }
+        return this.track("head", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          try {
+            const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
+            await client.send(cmd);
+            return true;
+          } catch (err) {
+            if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) return false;
+            throw err;
+          }
+        });
       }
       async getInfo(key) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
-        const res = await client.send(cmd);
-        return {
-          key,
-          size: res.ContentLength ?? 0,
-          contentType: res.ContentType,
-          lastModified: res.LastModified ?? /* @__PURE__ */ new Date(),
-          metadata: res.Metadata
-        };
+        return this.track("head", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
+          const res = await client.send(cmd);
+          return {
+            key,
+            size: res.ContentLength ?? 0,
+            contentType: res.ContentType,
+            lastModified: res.LastModified ?? /* @__PURE__ */ new Date(),
+            metadata: res.Metadata
+          };
+        });
       }
       async list(prefix) {
-        const client = await this.getClient();
-        const s3 = await this.s3Mod();
-        const cmd = new s3.ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix });
-        const res = await client.send(cmd);
-        return (res.Contents ?? []).map((item) => ({
-          key: item.Key,
-          size: item.Size ?? 0,
-          lastModified: item.LastModified ?? /* @__PURE__ */ new Date()
-        }));
+        return this.track("list", async () => {
+          const client = await this.getClient();
+          const s3 = await this.s3Mod();
+          const cmd = new s3.ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix });
+          const res = await client.send(cmd);
+          return (res.Contents ?? []).map((item) => ({
+            key: item.Key,
+            size: item.Size ?? 0,
+            lastModified: item.LastModified ?? /* @__PURE__ */ new Date()
+          }));
+        });
       }
       // ---------------------------------------------------------------------------
       // Presigned URLs
@@ -308,10 +349,14 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/storage-service-plugin.ts
+var import_observability3 = require("@objectstack/observability");
+
 // src/local-storage-adapter.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_crypto = require("crypto");
+var import_observability = require("@objectstack/observability");
 var LocalStorageAdapter = class {
   constructor(options) {
     this.rootDir = options.rootDir;
@@ -319,6 +364,33 @@ var LocalStorageAdapter = class {
     this.baseUrl = options.baseUrl ?? "";
     this.basePath = options.basePath ?? "/api/v1/storage";
     this.signingSecret = options.signingSecret ?? (0, import_node_crypto.randomUUID)();
+    this.metrics = options.metrics ?? new import_observability.NoopMetricsRegistry();
+  }
+  /**
+   * Wrap a storage operation with metrics instrumentation. Never swallows
+   * the underlying error; instrumentation failures are silently ignored.
+   */
+  async track(op, fn) {
+    const started = Date.now();
+    const baseLabels = { adapter: "local", op };
+    try {
+      const out = await fn();
+      try {
+        this.metrics.counter(import_observability.SEMCONV.storageOperationsTotal, { ...baseLabels, result: "ok" });
+        this.metrics.histogram(import_observability.SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+      } catch {
+      }
+      return out;
+    } catch (err) {
+      try {
+        this.metrics.counter(import_observability.SEMCONV.storageOperationsTotal, { ...baseLabels, result: "error" });
+        this.metrics.histogram(import_observability.SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+        const errorClass = err?.name || err?.constructor?.name || "Error";
+        this.metrics.counter(import_observability.SEMCONV.storageErrorsTotal, { ...baseLabels, errorClass });
+      } catch {
+      }
+      throw err;
+    }
   }
   // ---------------------------------------------------------------------------
   // Path helpers
@@ -339,61 +411,72 @@ var LocalStorageAdapter = class {
   // Basic file operations
   // ---------------------------------------------------------------------------
   async upload(key, data, _options) {
-    const filePath = this.resolvePath(key);
-    await import_node_fs.promises.mkdir((0, import_node_path.dirname)(filePath), { recursive: true });
-    if (data instanceof Buffer) {
-      await import_node_fs.promises.writeFile(filePath, data);
-      return;
-    }
-    const chunks = [];
-    const reader = data.getReader();
-    let done = false;
-    while (!done) {
-      const result = await reader.read();
-      done = result.done;
-      if (result.value) chunks.push(result.value);
-    }
-    await import_node_fs.promises.writeFile(filePath, Buffer.concat(chunks));
+    return this.track("put", async () => {
+      const filePath = this.resolvePath(key);
+      await import_node_fs.promises.mkdir((0, import_node_path.dirname)(filePath), { recursive: true });
+      if (data instanceof Buffer) {
+        await import_node_fs.promises.writeFile(filePath, data);
+        return;
+      }
+      const chunks = [];
+      const reader = data.getReader();
+      let done = false;
+      while (!done) {
+        const result = await reader.read();
+        done = result.done;
+        if (result.value) chunks.push(result.value);
+      }
+      await import_node_fs.promises.writeFile(filePath, Buffer.concat(chunks));
+    });
   }
   async download(key) {
-    return import_node_fs.promises.readFile(this.resolvePath(key));
+    return this.track("get", async () => import_node_fs.promises.readFile(this.resolvePath(key)));
   }
   async delete(key) {
-    await import_node_fs.promises.unlink(this.resolvePath(key)).catch((err) => {
-      if (err && err.code === "ENOENT") return;
-      throw err;
+    return this.track("delete", async () => {
+      await import_node_fs.promises.unlink(this.resolvePath(key)).catch((err) => {
+        if (err && err.code === "ENOENT") return;
+        throw err;
+      });
     });
   }
   async exists(key) {
-    try {
-      await import_node_fs.promises.access(this.resolvePath(key));
-      return true;
-    } catch {
-      return false;
-    }
+    return this.track("head", async () => {
+      try {
+        await import_node_fs.promises.access(this.resolvePath(key));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   }
   async getInfo(key) {
-    const filePath = this.resolvePath(key);
-    const stat = await import_node_fs.promises.stat(filePath);
-    return { key, size: stat.size, lastModified: stat.mtime };
+    return this.track("head", async () => {
+      const filePath = this.resolvePath(key);
+      const stat = await import_node_fs.promises.stat(filePath);
+      return { key, size: stat.size, lastModified: stat.mtime };
+    });
   }
   async list(prefix) {
-    const dirPath = this.resolvePath(prefix);
-    try {
-      const entries = await import_node_fs.promises.readdir(dirPath);
-      const results = [];
-      for (const entry of entries) {
-        if (entry.startsWith(".")) continue;
-        const fullKey = prefix ? `${prefix}/${entry}` : entry;
-        try {
-          results.push(await this.getInfo(fullKey));
-        } catch {
+    return this.track("list", async () => {
+      const dirPath = this.resolvePath(prefix);
+      try {
+        const entries = await import_node_fs.promises.readdir(dirPath);
+        const results = [];
+        for (const entry of entries) {
+          if (entry.startsWith(".")) continue;
+          const fullKey = prefix ? `${prefix}/${entry}` : entry;
+          try {
+            const stat = await import_node_fs.promises.stat(this.resolvePath(fullKey));
+            results.push({ key: fullKey, size: stat.size, lastModified: stat.mtime });
+          } catch {
+          }
         }
+        return results;
+      } catch {
+        return [];
       }
-      return results;
-    } catch {
-      return [];
-    }
+    });
   }
   // ---------------------------------------------------------------------------
   // Presigned URL helpers
@@ -1265,6 +1348,7 @@ var StorageServicePlugin = class {
     this.type = "standard";
     this.storage = null;
     this.store = null;
+    this.metrics = new import_observability3.NoopMetricsRegistry();
     this.options = { adapter: "local", ...options };
   }
   /** Build a concrete adapter from a values map (settings-derived). */
@@ -1282,7 +1366,8 @@ var StorageServicePlugin = class {
         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
+        forcePathStyle: !!values.s3_force_path_style,
+        metrics: this.metrics
       };
       return new S3StorageAdapter(opts);
     }
@@ -1291,10 +1376,12 @@ var StorageServicePlugin = class {
       basePath: this.options.basePath ?? "/api/v1/storage",
       ...this.options.local ?? {},
       // settings value wins over any constructor-provided local.rootDir
-      rootDir
+      rootDir,
+      metrics: this.metrics
     });
   }
   async init(ctx) {
+    this.metrics = resolveMetrics(ctx, this.options.metrics);
     const adapter = this.options.adapter;
     let initial;
     if (adapter === "s3") {
@@ -1303,11 +1390,11 @@ var StorageServicePlugin = class {
       if (!s3Opts) {
         throw new Error('StorageServicePlugin: s3 options are required when adapter is "s3"');
       }
-      initial = new S3Ctor(s3Opts);
+      initial = new S3Ctor({ ...s3Opts, metrics: this.metrics });
     } else {
       const rootDir = this.options.local?.rootDir ?? "./storage";
       const basePath = this.options.basePath ?? "/api/v1/storage";
-      initial = new LocalStorageAdapter({ rootDir, basePath, ...this.options.local });
+      initial = new LocalStorageAdapter({ rootDir, basePath, ...this.options.local, metrics: this.metrics });
     }
     this.storage = new SwappableStorageService(initial, (prev, next) => {
       const prevName = prev?.constructor?.name ?? "unknown";
@@ -1317,7 +1404,9 @@ var StorageServicePlugin = class {
       );
     });
     ctx.registerService("file-storage", this.storage);
-    ctx.logger.info(`StorageServicePlugin: registered ${adapter} storage adapter (swappable)`);
+    ctx.logger.info(
+      `StorageServicePlugin: registered ${adapter} storage adapter (swappable, metrics=${this.metrics.constructor?.name ?? "unknown"})`
+    );
     try {
       ctx.getService("manifest").register({
         id: "com.objectstack.service.storage",
@@ -1429,6 +1518,15 @@ var StorageServicePlugin = class {
     });
   }
 };
+function resolveMetrics(ctx, override) {
+  if (override) return override;
+  try {
+    const m = ctx.getService(import_observability3.OBSERVABILITY_METRICS_SERVICE);
+    if (m) return m;
+  } catch {
+  }
+  return new import_observability3.NoopMetricsRegistry();
+}
 
 // src/index.ts
 init_s3_storage_adapter();