@objectstack/service-storage 4.2.0 → 5.1.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { Plugin, PluginContext } from '@objectstack/core';
+import { MetricsRegistry } from '@objectstack/observability';
 import { IStorageService, StorageUploadOptions, StorageFileInfo, PresignedUploadDescriptor, PresignedDownloadDescriptor, IDataEngine, IHttpServer } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
@@ -28,6 +29,8 @@ interface LocalStorageAdapterOptions {
      * Auto-generated if omitted (suitable for single-process dev usage).
      */
     signingSecret?: string;
+    /** Optional MetricsRegistry for instrumentation. Defaults to NoopMetricsRegistry. */
+    metrics?: MetricsRegistry;
 }
 interface PresignTokenPayload {
     k: string;
@@ -52,7 +55,13 @@ declare class LocalStorageAdapter implements IStorageService {
     private readonly baseUrl;
     private readonly basePath;
     private readonly signingSecret;
+    private readonly metrics;
     constructor(options: LocalStorageAdapterOptions);
+    /**
+     * Wrap a storage operation with metrics instrumentation. Never swallows
+     * the underlying error; instrumentation failures are silently ignored.
+     */
+    private track;
     private resolvePath;
     private resolvePartPath;
     upload(key: string, data: Buffer | ReadableStream, _options?: StorageUploadOptions): Promise<void>;
@@ -238,6 +247,8 @@ interface S3StorageAdapterOptions {
     secretAccessKey?: string;
     /** Force path-style URLs (needed for MinIO / self-hosted) */
     forcePathStyle?: boolean;
+    /** Optional MetricsRegistry for instrumentation. Defaults to NoopMetricsRegistry. */
+    metrics?: MetricsRegistry;
 }
 /**
  * S3 storage adapter implementing IStorageService.
@@ -261,8 +272,15 @@ declare class S3StorageAdapter implements IStorageService {
     private readonly region;
     private readonly endpoint?;
     private readonly forcePathStyle;
+    private readonly metrics;
     private clientPromise;
     constructor(options: S3StorageAdapterOptions);
+    /**
+     * 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.
+     */
+    private track;
     /**
      * Lazily resolve the AWS S3 client to avoid crashing at import time when
      * `@aws-sdk/client-s3` isn't installed.
@@ -711,7 +729,7 @@ declare const SystemFile: Omit<{
     } | undefined;
     partitioning?: {
         enabled: boolean;
-        strategy: "hash" | "list" | "range";
+        strategy: "list" | "hash" | "range";
         key: string;
         interval?: string | undefined;
     } | undefined;
@@ -1025,11 +1043,17 @@ declare const SystemFile: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("get" | "search" | "upsert" | "create" | "import" | "delete" | "list" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("get" | "delete" | "list" | "search" | "upsert" | "create" | "import" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;
@@ -3841,7 +3865,7 @@ declare const SystemUploadSession: Omit<{
     } | undefined;
     partitioning?: {
         enabled: boolean;
-        strategy: "hash" | "list" | "range";
+        strategy: "list" | "hash" | "range";
         key: string;
         interval?: string | undefined;
     } | undefined;
@@ -4155,11 +4179,17 @@ declare const SystemUploadSession: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("get" | "search" | "upsert" | "create" | "import" | "delete" | "list" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("get" | "delete" | "list" | "search" | "upsert" | "create" | "import" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Plugin, PluginContext } from '@objectstack/core';
+import { MetricsRegistry } from '@objectstack/observability';
 import { IStorageService, StorageUploadOptions, StorageFileInfo, PresignedUploadDescriptor, PresignedDownloadDescriptor, IDataEngine, IHttpServer } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
@@ -28,6 +29,8 @@ interface LocalStorageAdapterOptions {
      * Auto-generated if omitted (suitable for single-process dev usage).
      */
     signingSecret?: string;
+    /** Optional MetricsRegistry for instrumentation. Defaults to NoopMetricsRegistry. */
+    metrics?: MetricsRegistry;
 }
 interface PresignTokenPayload {
     k: string;
@@ -52,7 +55,13 @@ declare class LocalStorageAdapter implements IStorageService {
     private readonly baseUrl;
     private readonly basePath;
     private readonly signingSecret;
+    private readonly metrics;
     constructor(options: LocalStorageAdapterOptions);
+    /**
+     * Wrap a storage operation with metrics instrumentation. Never swallows
+     * the underlying error; instrumentation failures are silently ignored.
+     */
+    private track;
     private resolvePath;
     private resolvePartPath;
     upload(key: string, data: Buffer | ReadableStream, _options?: StorageUploadOptions): Promise<void>;
@@ -238,6 +247,8 @@ interface S3StorageAdapterOptions {
     secretAccessKey?: string;
     /** Force path-style URLs (needed for MinIO / self-hosted) */
     forcePathStyle?: boolean;
+    /** Optional MetricsRegistry for instrumentation. Defaults to NoopMetricsRegistry. */
+    metrics?: MetricsRegistry;
 }
 /**
  * S3 storage adapter implementing IStorageService.
@@ -261,8 +272,15 @@ declare class S3StorageAdapter implements IStorageService {
     private readonly region;
     private readonly endpoint?;
     private readonly forcePathStyle;
+    private readonly metrics;
     private clientPromise;
     constructor(options: S3StorageAdapterOptions);
+    /**
+     * 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.
+     */
+    private track;
     /**
      * Lazily resolve the AWS S3 client to avoid crashing at import time when
      * `@aws-sdk/client-s3` isn't installed.
@@ -711,7 +729,7 @@ declare const SystemFile: Omit<{
     } | undefined;
     partitioning?: {
         enabled: boolean;
-        strategy: "hash" | "list" | "range";
+        strategy: "list" | "hash" | "range";
         key: string;
         interval?: string | undefined;
     } | undefined;
@@ -1025,11 +1043,17 @@ declare const SystemFile: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("get" | "search" | "upsert" | "create" | "import" | "delete" | "list" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("get" | "delete" | "list" | "search" | "upsert" | "create" | "import" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;
@@ -3841,7 +3865,7 @@ declare const SystemUploadSession: Omit<{
     } | undefined;
     partitioning?: {
         enabled: boolean;
-        strategy: "hash" | "list" | "range";
+        strategy: "list" | "hash" | "range";
         key: string;
         interval?: string | undefined;
     } | undefined;
@@ -4155,11 +4179,17 @@ declare const SystemUploadSession: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("get" | "search" | "upsert" | "create" | "import" | "delete" | "list" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("get" | "delete" | "list" | "search" | "upsert" | "create" | "import" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
     keyPrefix?: string | undefined;
+    detail?: {
+        [x: string]: unknown;
+        renderViaSchema?: boolean | undefined;
+        hideReferenceRail?: boolean | undefined;
+        hideRelatedTab?: boolean | undefined;
+    } | undefined;
     actions?: {
         name: string;
         label: string;

package/dist/index.js

@@ -13,6 +13,10 @@ var s3_storage_adapter_exports = {};
 __export(s3_storage_adapter_exports, {
   S3StorageAdapter: () => S3StorageAdapter
 });
+import {
+  NoopMetricsRegistry as NoopMetricsRegistry2,
+  SEMCONV as SEMCONV2
+} from "@objectstack/observability";
 async function streamToBuffer(stream) {
   if (Buffer.isBuffer(stream)) return stream;
   if (stream instanceof Uint8Array) return Buffer.from(stream);
@@ -50,6 +54,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 NoopMetricsRegistry2();
+      }
+      /**
+       * 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(SEMCONV2.storageOperationsTotal, { ...baseLabels, result: "ok" });
+            this.metrics.histogram(SEMCONV2.storageOperationDurationMs, Date.now() - started, baseLabels);
+          } catch {
+          }
+          return out;
+        } catch (err) {
+          try {
+            this.metrics.counter(SEMCONV2.storageOperationsTotal, { ...baseLabels, result: "error" });
+            this.metrics.histogram(SEMCONV2.storageOperationDurationMs, Date.now() - started, baseLabels);
+            const errorClass = err?.name || err?.constructor?.name || "Error";
+            this.metrics.counter(SEMCONV2.storageErrorsTotal, { ...baseLabels, errorClass });
+          } catch {
+          }
+          throw err;
+        }
       }
       /**
        * Lazily resolve the AWS S3 client to avoid crashing at import time when
@@ -99,67 +131,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
@@ -276,6 +320,10 @@ var init_s3_storage_adapter = __esm({
 import { promises as fs, createReadStream, createWriteStream } from "fs";
 import { join, dirname } from "path";
 import { createHmac, randomUUID } from "crypto";
+import {
+  NoopMetricsRegistry,
+  SEMCONV
+} from "@objectstack/observability";
 var LocalStorageAdapter = class {
   constructor(options) {
     this.rootDir = options.rootDir;
@@ -283,6 +331,33 @@ var LocalStorageAdapter = class {
     this.baseUrl = options.baseUrl ?? "";
     this.basePath = options.basePath ?? "/api/v1/storage";
     this.signingSecret = options.signingSecret ?? randomUUID();
+    this.metrics = options.metrics ?? new 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(SEMCONV.storageOperationsTotal, { ...baseLabels, result: "ok" });
+        this.metrics.histogram(SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+      } catch {
+      }
+      return out;
+    } catch (err) {
+      try {
+        this.metrics.counter(SEMCONV.storageOperationsTotal, { ...baseLabels, result: "error" });
+        this.metrics.histogram(SEMCONV.storageOperationDurationMs, Date.now() - started, baseLabels);
+        const errorClass = err?.name || err?.constructor?.name || "Error";
+        this.metrics.counter(SEMCONV.storageErrorsTotal, { ...baseLabels, errorClass });
+      } catch {
+      }
+      throw err;
+    }
   }
   // ---------------------------------------------------------------------------
   // Path helpers
@@ -303,61 +378,72 @@ var LocalStorageAdapter = class {
   // Basic file operations
   // ---------------------------------------------------------------------------
   async upload(key, data, _options) {
-    const filePath = this.resolvePath(key);
-    await fs.mkdir(dirname(filePath), { recursive: true });
-    if (data instanceof Buffer) {
-      await fs.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 fs.writeFile(filePath, Buffer.concat(chunks));
+    return this.track("put", async () => {
+      const filePath = this.resolvePath(key);
+      await fs.mkdir(dirname(filePath), { recursive: true });
+      if (data instanceof Buffer) {
+        await fs.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 fs.writeFile(filePath, Buffer.concat(chunks));
+    });
   }
   async download(key) {
-    return fs.readFile(this.resolvePath(key));
+    return this.track("get", async () => fs.readFile(this.resolvePath(key)));
   }
   async delete(key) {
-    await fs.unlink(this.resolvePath(key)).catch((err) => {
-      if (err && err.code === "ENOENT") return;
-      throw err;
+    return this.track("delete", async () => {
+      await fs.unlink(this.resolvePath(key)).catch((err) => {
+        if (err && err.code === "ENOENT") return;
+        throw err;
+      });
     });
   }
   async exists(key) {
-    try {
-      await fs.access(this.resolvePath(key));
-      return true;
-    } catch {
-      return false;
-    }
+    return this.track("head", async () => {
+      try {
+        await fs.access(this.resolvePath(key));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   }
   async getInfo(key) {
-    const filePath = this.resolvePath(key);
-    const stat = await fs.stat(filePath);
-    return { key, size: stat.size, lastModified: stat.mtime };
+    return this.track("head", async () => {
+      const filePath = this.resolvePath(key);
+      const stat = await fs.stat(filePath);
+      return { key, size: stat.size, lastModified: stat.mtime };
+    });
   }
   async list(prefix) {
-    const dirPath = this.resolvePath(prefix);
-    try {
-      const entries = await fs.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 fs.readdir(dirPath);
+        const results = [];
+        for (const entry of entries) {
+          if (entry.startsWith(".")) continue;
+          const fullKey = prefix ? `${prefix}/${entry}` : entry;
+          try {
+            const stat = await fs.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