@streetjs/storage 1.0.0

package/dist/multipart.js

@@ -0,0 +1,200 @@
+/**
+ * @streetjs/storage — the multipart upload manager.
+ *
+ * A {@link Multipart_Upload} splits a large object into independently uploaded
+ * parts that are later assembled into a single object whose content equals the
+ * concatenation of those parts in order (Requirement 6). {@link MultipartManager}
+ * provides this capability in a **provider-agnostic** way:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `multipart` capability, the manager delegates each operation to the driver
+ *   so a provider that has first-class multipart support (e.g. S3) is used
+ *   directly.
+ * - Otherwise the manager **simulates** multipart over the mandatory driver
+ *   primitives (`put`/`get`/`putStream`/`delete`). Each `uploadPart` persists
+ *   the part bytes under a reserved key derived from `(uploadId, partNumber)`
+ *   (mirroring the design's `.multipart/<uploadId>/<partNumber>` layout), and
+ *   `complete` streams the persisted parts back in the supplied order into the
+ *   final object. Because completion assembles the object by reading one part at
+ *   a time into a `Readable` and piping it through `driver.putStream`, the whole
+ *   object is never required to be materialized in a single buffer by this
+ *   layer — the design streams the concatenation and therefore imposes **no
+ *   artificial size cap** (objects of a gigabyte or more are supported,
+ *   Requirement 6.5).
+ *
+ * Semantics (Requirement 6):
+ * - {@link MultipartManager.create} mints and returns an upload identifier.
+ * - {@link MultipartManager.uploadPart} persists a part keyed by
+ *   `(uploadId, partNumber)` and returns a {@link StoredPart} descriptor.
+ * - {@link MultipartManager.complete} concatenates the parts in the supplied
+ *   order into the final object — equivalent to a single `put` of the
+ *   concatenation — and returns the resulting metadata.
+ * - {@link MultipartManager.abort} discards every persisted part and creates no
+ *   object.
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * error hierarchy, and the metadata layer, keeping the dependency direction
+ * acyclic.
+ *
+ * _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
+ */
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } from "node:crypto";
+import { Readable } from "node:stream";
+import { NotFoundError, StorageError } from "./errors.js";
+import { normalizeMetadata } from "./metadata.js";
+/**
+ * Reserved key prefix under which simulated multipart parts are persisted via
+ * the driver primitives. Parts live at `${PART_KEY_PREFIX}<uploadId>/<partNumber>`
+ * and are removed on `complete`/`abort`, so they never remain visible after a
+ * multipart upload finalizes.
+ */
+const PART_KEY_PREFIX = ".multipart/";
+/** Write metadata used when persisting an individual (transient) part. */
+const PART_WRITE_METADATA = { contentType: "application/octet-stream" };
+/**
+ * Provider-agnostic multipart upload manager built on the driver contract.
+ *
+ * A single instance is held by the facade and bound to one {@link StorageDriver}
+ * for its lifetime, so the native-vs-simulated decision (based on whether the
+ * driver exposes a `multipart` capability) is stable across every call for a
+ * given upload identifier.
+ */
+export class MultipartManager {
+    /** The driver every operation is delegated to or simulated over. */
+    driver;
+    /**
+     * In-progress simulated sessions keyed by upload id. Empty when the driver
+     * provides a native `multipart` capability (that path keeps no local state).
+     */
+    sessions = new Map();
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /** The driver's native multipart capability, when present. */
+    get native() {
+        return this.driver.multipart;
+    }
+    /**
+     * Begin a multipart upload for `key` and return its upload identifier
+     * (Requirement 6.1). When the driver has a native capability the driver mints
+     * the id; otherwise a fresh id is generated and a local session records the
+     * target key and its write-time metadata for assembly at completion.
+     */
+    async create(key, metadata) {
+        if (this.native !== undefined) {
+            return this.native.create(key, metadata);
+        }
+        const uploadId = randomUUID();
+        this.sessions.set(uploadId, { key, metadata, partNumbers: new Set() });
+        return uploadId;
+    }
+    /**
+     * Persist a single part for `uploadId` and return its {@link StoredPart}
+     * descriptor (Requirement 6.2). The part bytes are copied defensively before
+     * persistence so later mutation of the caller's buffer cannot corrupt a stored
+     * part. The returned `etag` is the sha-256 hex digest of the part bytes,
+     * matching the checksum scheme the drivers use elsewhere.
+     */
+    async uploadPart(uploadId, partNumber, bytes) {
+        if (this.native !== undefined) {
+            return this.native.uploadPart(uploadId, partNumber, bytes);
+        }
+        const session = this.requireSession(uploadId);
+        assertValidPartNumber(partNumber);
+        const stored = bytes.slice();
+        await this.driver.put(this.partKey(uploadId, partNumber), stored, PART_WRITE_METADATA);
+        session.partNumbers.add(partNumber);
+        return { partNumber, etag: sha256Hex(stored), size: stored.byteLength };
+    }
+    /**
+     * Assemble the supplied `parts` in order into the final object and return its
+     * metadata (Requirement 6.3). The assembled content equals the concatenation
+     * of the parts in the given order — equivalent to a single `put` of that
+     * concatenation.
+     *
+     * For the simulated path the parts are streamed back one at a time from the
+     * driver into a `Readable` piped through `driver.putStream`, so this layer
+     * never buffers the full object at once (Requirement 6.5). Every persisted
+     * part (whether or not it appears in `parts`) is discarded afterward and the
+     * session is closed.
+     */
+    async complete(uploadId, parts) {
+        if (this.native !== undefined) {
+            return normalizeMetadata(await this.native.complete(uploadId, parts));
+        }
+        const session = this.requireSession(uploadId);
+        const driver = this.driver;
+        const partKey = (partNumber) => this.partKey(uploadId, partNumber);
+        // Stream the parts in the supplied order so the concatenation is assembled
+        // incrementally rather than materialized in a single buffer here.
+        async function* assembleParts() {
+            for (const part of parts) {
+                const result = await driver.get(partKey(part.partNumber));
+                if (!result.found) {
+                    throw new NotFoundError(partKey(part.partNumber), `Multipart part ${part.partNumber} for upload "${uploadId}" was not found.`);
+                }
+                yield Buffer.from(result.bytes);
+            }
+        }
+        const metadata = await driver.putStream(session.key, Readable.from(assembleParts()), session.metadata);
+        await this.discardParts(uploadId, session.partNumbers);
+        this.sessions.delete(uploadId);
+        return normalizeMetadata(metadata);
+    }
+    /**
+     * Discard every persisted part for `uploadId` and create no completed object
+     * (Requirement 6.4). Delegates to the native capability when present; for the
+     * simulated path it deletes all recorded part keys and closes the session. An
+     * unknown/already-finalized upload id is treated as an idempotent no-op.
+     */
+    async abort(uploadId) {
+        if (this.native !== undefined) {
+            await this.native.abort(uploadId);
+            return;
+        }
+        const session = this.sessions.get(uploadId);
+        if (session === undefined) {
+            return;
+        }
+        await this.discardParts(uploadId, session.partNumbers);
+        this.sessions.delete(uploadId);
+    }
+    /** Delete every persisted part for a simulated upload id. */
+    async discardParts(uploadId, partNumbers) {
+        for (const partNumber of partNumbers) {
+            await this.driver.delete(this.partKey(uploadId, partNumber));
+        }
+    }
+    /** The reserved driver key a simulated part is persisted under. */
+    partKey(uploadId, partNumber) {
+        return `${PART_KEY_PREFIX}${uploadId}/${partNumber}`;
+    }
+    /**
+     * Resolve the simulated session for `uploadId`, throwing a descriptive
+     * {@link StorageError} when the id is unknown or the upload has already been
+     * finalized.
+     */
+    requireSession(uploadId) {
+        const session = this.sessions.get(uploadId);
+        if (session === undefined) {
+            throw new StorageError(`Unknown or already-finalized multipart upload id "${uploadId}".`);
+        }
+        return session;
+    }
+}
+/** Compute the lowercase sha-256 hex digest of `bytes`. */
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Guard that a part number is a positive integer. Part numbers identify the
+ * ordinal position of a part and must be well-formed for the reserved part key
+ * to be stable and for ordering to be meaningful.
+ */
+function assertValidPartNumber(partNumber) {
+    if (!Number.isInteger(partNumber) || partNumber < 1) {
+        throw new StorageError(`Invalid multipart part number ${partNumber}; expected a positive integer.`);
+    }
+}
+//# sourceMappingURL=multipart.js.map

package/dist/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../src/multipart.ts"],"names":[],"mappings":"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"}

package/dist/observability.d.ts

@@ -0,0 +1,82 @@
+import type { HealthCheckRegistry, MetricsRegistry } from "streetjs";
+import type { StorageStats, DriverProbe } from "./types.js";
+/**
+ * The introspection slice of a {@link Storage} facade the observability layer
+ * reads: a synchronous stats snapshot and the best-effort driver probe.
+ */
+export interface StorageIntrospect {
+    stats(): StorageStats;
+    probe(): Promise<DriverProbe>;
+}
+/** The name the storage health check is registered under. */
+export declare const STORAGE_HEALTH_CHECK_NAME = "storage";
+export declare const STORAGE_UPLOADS_METRIC = "storage_uploads_total";
+export declare const STORAGE_DOWNLOADS_METRIC = "storage_downloads_total";
+export declare const STORAGE_BYTES_UPLOADED_METRIC = "storage_bytes_uploaded_total";
+export declare const STORAGE_BYTES_DOWNLOADED_METRIC = "storage_bytes_downloaded_total";
+export declare const STORAGE_ACTIVE_UPLOADS_METRIC = "storage_active_uploads";
+export declare const STORAGE_FAILED_UPLOADS_METRIC = "storage_failed_uploads_total";
+export declare const STORAGE_USAGE_METRIC = "storage_usage_bytes";
+export declare const STORAGE_LATENCY_METRIC = "storage_operation_latency_seconds";
+export declare const STORAGE_MULTIPART_METRIC = "storage_multipart_uploads_total";
+export declare const STORAGE_RESUMABLE_METRIC = "storage_resumable_sessions_total";
+/**
+ * The live telemetry sink the facade feeds as operations occur. Every hook is
+ * optional so an inert sink (no metrics registry) is a complete no-op. All
+ * hooks are isolated by the facade so observability never destabilizes an
+ * operation.
+ */
+export interface StorageTelemetry {
+    /** A successful upload persisted `bytes` in `latencySeconds`. */
+    onUpload?(bytes: number, latencySeconds: number): void;
+    /** A successful download returned `bytes` in `latencySeconds`. */
+    onDownload?(bytes: number, latencySeconds: number): void;
+    /** An upload failed (validation, authorization, or driver error). */
+    onUploadFailed?(): void;
+    /** The number of in-flight (streamed/resumable) uploads changed. */
+    onActiveUploadsChange?(active: number): void;
+    /** The tracked storage usage (bytes) changed. */
+    onStorageUsage?(bytes: number): void;
+    /** A multipart upload was created. */
+    onMultipartUpload?(): void;
+    /** A resumable upload session was started. */
+    onResumableSession?(): void;
+}
+/** Options for {@link registerStorageObservability}. */
+export interface StorageObservabilityOptions {
+    /** Registry the `storage` health check is registered with (Req 23.3). */
+    health?: HealthCheckRegistry;
+    /** Registry the storage metrics are exported through (Req 23.1, 23.2). */
+    metrics?: MetricsRegistry;
+    /** Refresh cadence for gauges when `autoRefresh` is enabled. */
+    refreshIntervalMs?: number;
+    /**
+     * When `true`, an unref'd interval keeps the gauges primed. Default `false`
+     * (pull-based: the caller drives {@link StorageObservabilityHandle.refresh}).
+     */
+    autoRefresh?: boolean;
+}
+/** Handle returned by {@link registerStorageObservability}. */
+export interface StorageObservabilityHandle {
+    /**
+     * The telemetry sink the facade feeds live. Drives the counters, gauges, and
+     * latency histogram as operations occur.
+     */
+    readonly telemetry: StorageTelemetry;
+    /**
+     * Register the `storage` health check against the created facade and prime the
+     * gauges from `storage.stats()`. Call once after `createStorage`.
+     */
+    attach(storage: StorageIntrospect): void;
+    /** Recompute the gauges from `storage.stats()` (best-effort; never throws). */
+    refresh(): void;
+    /** Stop any refresh timer and release resources. Safe to call once. */
+    close(): void;
+}
+/**
+ * Register storage observability. Returns a {@link StorageObservabilityHandle}
+ * whose `telemetry` the facade feeds live and whose `attach` wires the health
+ * check + primes the gauges from the created facade.
+ */
+export declare function registerStorageObservability(options?: StorageObservabilityOptions): StorageObservabilityHandle;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAKhB,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,YAAY,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAC9D,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAClE,eAAO,MAAM,6BAA6B,iCAAiC,CAAC;AAC5E,eAAO,MAAM,+BAA+B,mCAAmC,CAAC;AAChF,eAAO,MAAM,6BAA6B,2BAA2B,CAAC;AACtE,eAAO,MAAM,6BAA6B,iCAAiC,CAAC;AAC5E,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,sCAAsC,CAAC;AAC1E,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAC1E,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAI3E;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,kEAAkE;IAClE,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,qEAAqE;IACrE,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,oEAAoE;IACpE,qBAAqB,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iDAAiD;IACjD,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,sCAAsC;IACtC,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B,8CAA8C;IAC9C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B;AAED,wDAAwD;AACxD,MAAM,WAAW,2BAA2B;IAC1C,yEAAyE;IACzE,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACzC,+EAA+E;IAC/E,OAAO,IAAI,IAAI,CAAC;IAChB,uEAAuE;IACvE,KAAK,IAAI,IAAI,CAAC;CACf;AAKD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CAoJ5B"}

package/dist/observability.js

@@ -0,0 +1,175 @@
+// src/observability.ts
+// @streetjs/storage — health check + metrics wiring over the reused core
+// `HealthCheckRegistry` and `MetricsRegistry`.
+//
+// Following the events package's `observability.ts` pattern, this module
+// exposes a single entry point, `registerStorageObservability`, that returns a
+// handle with:
+//
+//   1. a `telemetry` sink the facade feeds live as operations occur — it drives
+//      the upload / download / bytes / failed-upload counters, the active-uploads
+//      and storage-usage gauges, the operation-latency histogram, and the
+//      multipart / resumable counters (Requirement 23.2);
+//   2. an `attach(storage)` method that registers the `storage` health check
+//      against the `HealthCheckRegistry`, sourced from `storage.probe()` for
+//      provider connectivity, writability, readability, and quota availability
+//      (Requirement 23.3), and primes the gauges from `storage.stats()`.
+//
+// Everything is opt-in: with no `metrics` registry the telemetry is inert; with
+// no `health` registry no check is registered. Registration is idempotent
+// against a shared registry (reuses an existing metric rather than throwing —
+// `reg.has(name) ? reg.get(name) : reg.counter(...)`), so several storage
+// instances can share one registry (Requirement 23.1).
+//
+// Only the existing core primitives (`MetricsRegistry`, `HealthCheckRegistry`)
+// are reused; no separate metrics / health / scheduling / retry / event system
+// is introduced (Requirement 23.4).
+/** The name the storage health check is registered under. */
+export const STORAGE_HEALTH_CHECK_NAME = "storage";
+export const STORAGE_UPLOADS_METRIC = "storage_uploads_total";
+export const STORAGE_DOWNLOADS_METRIC = "storage_downloads_total";
+export const STORAGE_BYTES_UPLOADED_METRIC = "storage_bytes_uploaded_total";
+export const STORAGE_BYTES_DOWNLOADED_METRIC = "storage_bytes_downloaded_total";
+export const STORAGE_ACTIVE_UPLOADS_METRIC = "storage_active_uploads";
+export const STORAGE_FAILED_UPLOADS_METRIC = "storage_failed_uploads_total";
+export const STORAGE_USAGE_METRIC = "storage_usage_bytes";
+export const STORAGE_LATENCY_METRIC = "storage_operation_latency_seconds";
+export const STORAGE_MULTIPART_METRIC = "storage_multipart_uploads_total";
+export const STORAGE_RESUMABLE_METRIC = "storage_resumable_sessions_total";
+const DEFAULT_REFRESH_INTERVAL_MS = 5_000;
+/** An inert telemetry sink used when no metrics registry is provided. */
+const NOOP_TELEMETRY = {};
+/**
+ * Register storage observability. Returns a {@link StorageObservabilityHandle}
+ * whose `telemetry` the facade feeds live and whose `attach` wires the health
+ * check + primes the gauges from the created facade.
+ */
+export function registerStorageObservability(options = {}) {
+    const { metrics, health } = options;
+    let storage;
+    let timer;
+    let closed = false;
+    // ── Metrics (idempotent registration) ─────────────────────────────────────
+    let uploadsCounter;
+    let downloadsCounter;
+    let bytesUploadedCounter;
+    let bytesDownloadedCounter;
+    let failedUploadsCounter;
+    let multipartCounter;
+    let resumableCounter;
+    let activeUploadsGauge;
+    let usageGauge;
+    let latencyHistogram;
+    if (metrics) {
+        uploadsCounter = counter(metrics, STORAGE_UPLOADS_METRIC, "Total objects uploaded.");
+        downloadsCounter = counter(metrics, STORAGE_DOWNLOADS_METRIC, "Total objects downloaded.");
+        bytesUploadedCounter = counter(metrics, STORAGE_BYTES_UPLOADED_METRIC, "Total bytes uploaded.");
+        bytesDownloadedCounter = counter(metrics, STORAGE_BYTES_DOWNLOADED_METRIC, "Total bytes downloaded.");
+        failedUploadsCounter = counter(metrics, STORAGE_FAILED_UPLOADS_METRIC, "Total failed uploads.");
+        multipartCounter = counter(metrics, STORAGE_MULTIPART_METRIC, "Total multipart uploads created.");
+        resumableCounter = counter(metrics, STORAGE_RESUMABLE_METRIC, "Total resumable upload sessions started.");
+        activeUploadsGauge = gauge(metrics, STORAGE_ACTIVE_UPLOADS_METRIC, "Uploads currently in flight.");
+        usageGauge = gauge(metrics, STORAGE_USAGE_METRIC, "Tracked storage usage in bytes.");
+        latencyHistogram = histogram(metrics, STORAGE_LATENCY_METRIC, "Storage operation latency in seconds.");
+    }
+    const telemetry = metrics
+        ? {
+            onUpload: (bytes, latencySeconds) => safe(() => {
+                uploadsCounter?.inc();
+                bytesUploadedCounter?.inc({}, bytes);
+                latencyHistogram?.observe(latencySeconds);
+            }),
+            onDownload: (bytes, latencySeconds) => safe(() => {
+                downloadsCounter?.inc();
+                bytesDownloadedCounter?.inc({}, bytes);
+                latencyHistogram?.observe(latencySeconds);
+            }),
+            onUploadFailed: () => safe(() => failedUploadsCounter?.inc()),
+            onActiveUploadsChange: (active) => safe(() => activeUploadsGauge?.set(active)),
+            onStorageUsage: (bytes) => safe(() => usageGauge?.set(bytes)),
+            onMultipartUpload: () => safe(() => multipartCounter?.inc()),
+            onResumableSession: () => safe(() => resumableCounter?.inc()),
+        }
+        : NOOP_TELEMETRY;
+    const refresh = () => {
+        if (!storage) {
+            return;
+        }
+        safe(() => {
+            const stats = storage.stats();
+            activeUploadsGauge?.set(stats.activeUploads);
+            usageGauge?.set(stats.storageUsage);
+        });
+    };
+    const attach = (created) => {
+        storage = created;
+        if (health) {
+            health.addCheck(STORAGE_HEALTH_CHECK_NAME, async () => {
+                try {
+                    const probe = await created.probe();
+                    // The provider is healthy only when it is reachable and all of the
+                    // connectivity/writability/readability/quota dimensions hold
+                    // (Requirement 23.3).
+                    const status = probe.connectivity && probe.writable && probe.readable && probe.quotaAvailable
+                        ? "up"
+                        : "down";
+                    return {
+                        status,
+                        details: {
+                            connectivity: probe.connectivity,
+                            writable: probe.writable,
+                            readable: probe.readable,
+                            quotaAvailable: probe.quotaAvailable,
+                        },
+                    };
+                }
+                catch (err) {
+                    return {
+                        status: "down",
+                        details: { error: err instanceof Error ? err.message : String(err) },
+                    };
+                }
+            });
+        }
+        // Prime the gauges immediately; optionally keep them fresh via an unref'd timer.
+        refresh();
+        if (options.autoRefresh) {
+            timer = setInterval(refresh, options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS);
+            timer.unref?.();
+        }
+    };
+    return {
+        telemetry,
+        attach,
+        refresh,
+        close: () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+// ── Idempotent metric helpers ────────────────────────────────────────────────
+function counter(reg, name, help) {
+    return reg.has(name) ? reg.get(name) : reg.counter(name, help);
+}
+function gauge(reg, name, help, labels = []) {
+    return reg.has(name) ? reg.get(name) : reg.gauge(name, help, labels);
+}
+function histogram(reg, name, help) {
+    return reg.has(name) ? reg.get(name) : reg.histogram(name, help);
+}
+function safe(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // Observability must never destabilize a storage operation or a scrape.
+    }
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,82 @@
+import { PluginModule } from "streetjs";
+import type { SandboxedApp } from "streetjs";
+import { type Storage } from "./facade.js";
+import type { StorageConfig, StorageMetadataMap } from "./types.js";
+/**
+ * Options for {@link StoragePlugin}.
+ *
+ * Extends {@link StorageConfig} directly, so every configuration value the
+ * facade accepts — provider, driver, validation, versioning, signing secret,
+ * the `metrics` / `health` registries the observability layer registers
+ * against, the structural auth / image codec, and the structural
+ * events / queue / realtime `bridges` the facade wires internally — is supplied
+ * through the plugin options. Because a `SandboxedApp` exposes no registry, the
+ * registries are resolved from these options rather than from the app.
+ *
+ * @typeParam T - Optional per-application custom metadata map.
+ */
+export interface StoragePluginOptions<T extends StorageMetadataMap = StorageMetadataMap> extends StorageConfig {
+    /**
+     * Declarative, imperative bridge wiring composed on top of the constructed
+     * facade. Each entry is an attach function called with the live
+     * {@link Storage} facade; if it returns a detach function, that detach is
+     * invoked on `onUnload`. This keeps the plugin decoupled from any specific
+     * integration instance — compose custom bridges without the plugin depending
+     * on them, and have them torn down deterministically on unload:
+     *
+     * ```ts
+     * new StoragePlugin({
+     *   provider: "memory",
+     *   metrics,
+     *   health,
+     *   wireBridges: [
+     *     (storage) => attachAuditLog(storage, auditSink), // returns () => void
+     *   ],
+     * });
+     * ```
+     *
+     * Distinct from the inherited structural `bridges`
+     * (events / queue / realtime), which the facade wires internally at
+     * construction time.
+     */
+    wireBridges?: Array<(storage: Storage<T>) => (() => void) | void>;
+}
+/**
+ * Plugin entry point that constructs and wires the application storage layer.
+ *
+ * Compatible with the core {@link PluginModule} and safe to register with a
+ * `SandboxedApp` (Requirements 20.1, 20.2). Once loaded, the application
+ * retrieves the live {@link Storage} facade through the {@link storage}
+ * accessor without any existing public API being modified (Requirement 20.3).
+ *
+ * @typeParam T - Optional per-application custom metadata map.
+ */
+export declare class StoragePlugin<T extends StorageMetadataMap = StorageMetadataMap> extends PluginModule {
+    readonly name = "@streetjs/storage";
+    readonly version = "1.0.0";
+    protected readonly options: StoragePluginOptions<T>;
+    private storageInstance?;
+    private bridgeDetachers;
+    constructor(options: StoragePluginOptions<T>);
+    /**
+     * The constructed facade, or `undefined` before load / after unload. Because
+     * the `SandboxedApp` has no registry to attach to, the application retrieves
+     * the live {@link Storage} facade through this accessor after the plugin
+     * loads (Requirement 20.3).
+     */
+    get storage(): Storage<T> | undefined;
+    /**
+     * Construct the facade (which wires observability from the configured
+     * `metrics` / `health` registries and the structural bridges), apply the
+     * declarative bridge wiring collecting any detach functions, and expose the
+     * facade. Idempotent per load: a second `onLoad` without an intervening
+     * `onUnload` reuses the already-constructed facade.
+     */
+    onLoad(_app: SandboxedApp): Promise<void>;
+    /**
+     * Detach the declarative bridges and close the facade gracefully (which stops
+     * the observability refresh timer). Safe if never loaded.
+     */
+    onUnload(_app: SandboxedApp): Promise<void>;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACrF,SAAQ,aAAa;IACrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;CACnE;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa,CACxB,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACjD,SAAQ,YAAY;IACpB,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,OAAO,WAAW;IAE3B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAEpD,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,eAAe,CAAyB;gBAEpC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAK5C;;;;;OAKG;IACH,IAAI,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAEpC;IAED;;;;;;OAMG;IACY,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBxD;;;OAGG;IACY,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAiB3D"}