@blamejs/core 0.4.1

package/lib/object-store/index.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Object-store dispatcher — protocol-agnostic remote (and local) storage.
+ *
+ * The framework's storage abstraction (lib/storage.js) routes per-classification
+ * requests to one or more configured backends. Each backend is constructed
+ * here from a config object that picks a protocol and provides its options:
+ *
+ *   protocol: 'local'                   → lib/object-store/local.js
+ *   protocol: 'http-put'                → lib/object-store/http-put.js
+ *   protocol: 'sigv4'  (S3 / R2 / B2 / MinIO / Wasabi / Tigris / DO Spaces /
+ *                       IDrive e2 / Linode Object Storage / Storj / etc.)
+ *                                       → lib/object-store/sigv4.js
+ *   protocol: 'gcs'    (Google Cloud Storage native — HMAC + native API)
+ *                                       → lib/object-store/gcs.js
+ *   protocol: 'azure-blob'              → lib/object-store/azure-blob.js
+ *
+ * Every backend is wrapped with retry + circuit-breaker so transient
+ * failures don't surface as call-site errors and persistent failures
+ * don't pile up retry storms.
+ *
+ * Common API across protocols:
+ *   put(key, body, opts?)       → { size, etag? }
+ *   get(key)                    → Buffer
+ *   getStream(key)              → Readable
+ *   head(key)                   → { size, etag?, lastModified? }
+ *   delete(key)                 → boolean (true if deleted, false if missing)
+ *   list(prefix, opts?)         → { items: [{ key, size, lastModified }], truncated }
+ */
+var localProto      = require("./local");
+var httpPutProto    = require("./http-put");
+var sigv4Proto      = require("./sigv4");
+var gcsProto        = require("./gcs");
+var azureBlobProto  = require("./azure-blob");
+var retryHelper     = require("./retry");
+var protocolDispatcher = require("../protocol-dispatcher");
+var { ObjectStoreError } = require("../framework-error");
+
+// All currently advertised protocols are bundled. The dispatcher's
+// `deferred` slot is the hook for adding deferred ones later.
+var dispatcher = protocolDispatcher.create({
+  name:       "object-store",
+  errorClass: ObjectStoreError,
+  protocols: {
+    "local":      localProto,
+    "http-put":   httpPutProto,
+    "sigv4":      sigv4Proto,
+    "gcs":        gcsProto,
+    "azure-blob": azureBlobProto,
+  },
+  deferred:         {},
+  fallbackProtocol: "local",
+});
+
+var _err = ObjectStoreError.factory;
+
+/**
+ * Build a backend instance from a backend config block.
+ *
+ * config:
+ *   {
+ *     protocol:        'local' | 'http-put' | 'sigv4' | 'gcs' | 'azure-blob',
+ *     // protocol-specific config (rootDir for local, baseUrl for http-put, etc.)
+ *     classifications: ['personal' | 'operational' | 'public' | <custom>],
+ *     residencyTag:    'EU' | 'US' | 'UK' | 'CA' | 'unrestricted' | <custom>,
+ *     retry:           { maxAttempts, baseDelayMs, maxDelayMs, jitterFactor },
+ *     breaker:         { failureThreshold, cooldownMs, successThreshold },
+ *     name:            <stable-id-for-circuit-breaker>,
+ *   }
+ */
+function buildBackend(config) {
+  if (!config) {
+    throw new Error("object-store backend requires { protocol }");
+  }
+  var proto = dispatcher.resolve(config.protocol);
+  var raw = proto.create(config);
+
+  // Validate classifications + residencyTag
+  var classifications = Array.isArray(config.classifications) && config.classifications.length > 0
+    ? config.classifications.slice()
+    : ["*"];   // wildcard: backend serves any classification
+  var residencyTag = config.residencyTag || "unrestricted";
+
+  // Wrap protocol calls with retry + circuit breaker
+  var breaker = new retryHelper.CircuitBreaker(
+    config.name || (config.protocol + ":" + (raw.rootDir || raw.baseUrl || "anonymous")),
+    config.breaker
+  );
+
+  function wrap(name) {
+    var inner = raw[name];
+    if (typeof inner !== "function") return inner;
+    return function () {
+      var args = Array.prototype.slice.call(arguments);
+      // For sync methods (getStream returns a Readable directly, not a Promise):
+      if (name === "getStream") {
+        // Apply circuit breaker only — getStream is sync, retry doesn't apply.
+        // The Readable will surface its own errors as the consumer reads it.
+        return inner.apply(raw, args);
+      }
+      return retryHelper.withRetry(function () {
+        return breaker.wrap(function () {
+          return inner.apply(raw, args);
+        });
+      }, config.retry);
+    };
+  }
+
+  return {
+    name:            config.name || config.protocol,
+    protocol:        config.protocol,
+    classifications: classifications,
+    residencyTag:    residencyTag,
+    breaker:         breaker,
+    raw:             raw,
+    put:             wrap("put"),
+    get:             wrap("get"),
+    getStream:       wrap("getStream"),
+    head:            wrap("head"),
+    delete:          wrap("delete"),
+    list:            wrap("list"),
+    // presigned*Url are sync URL-builders (no network call), so they
+    // bypass retry + circuit-breaker — propagate any throw directly.
+    presignedUploadUrl: typeof raw.presignedUploadUrl === "function"
+      ? raw.presignedUploadUrl.bind(raw) : null,
+    presignedDownloadUrl: typeof raw.presignedDownloadUrl === "function"
+      ? raw.presignedDownloadUrl.bind(raw) : null,
+    presignedUploadPolicy: typeof raw.presignedUploadPolicy === "function"
+      ? raw.presignedUploadPolicy.bind(raw) : null,
+    servesClassification: function (cls) {
+      return classifications.indexOf("*") !== -1 || classifications.indexOf(cls) !== -1;
+    },
+  };
+}
+
+module.exports = {
+  buildBackend:        buildBackend,
+  PROTOCOLS:           dispatcher.protocols,
+  DEFERRED_PROTOCOLS:  dispatcher.deferred,
+};

package/lib/object-store/local.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Local-filesystem protocol adapter for object-store.
+ *
+ * Implements the uniform protocol surface (put / get / getStream / delete /
+ * head / list) against a directory tree. Streaming is via Node's native
+ * fs.createReadStream / createWriteStream — no in-memory buffering of
+ * full files.
+ *
+ * Path safety: every key resolves under the configured rootDir, with an
+ * alphanumeric + `_-./` charset whitelist and explicit rejection of any
+ * path that escapes rootDir after resolution.
+ */
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var cluster = require("../cluster");
+var { ObjectStoreError } = require("../framework-error");
+
+var SAFE_KEY = /^[A-Za-z0-9_\-./]+$/;
+
+function _resolveSafe(rootDir, key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw _err("INVALID_KEY", "key must be a non-empty string", true);
+  }
+  if (key.includes("\0")) throw _err("INVALID_KEY", "null byte in key", true);
+  if (path.isAbsolute(key)) throw _err("INVALID_KEY", "absolute key not allowed", true);
+  if (!SAFE_KEY.test(key)) throw _err("INVALID_KEY", "invalid characters in key", true);
+  var full = path.resolve(rootDir, key);
+  var withSep = rootDir.endsWith(path.sep) ? rootDir : rootDir + path.sep;
+  if (full !== rootDir && !full.startsWith(withSep)) {
+    throw _err("INVALID_KEY", "key escapes rootDir", true);
+  }
+  return full;
+}
+
+var _err = ObjectStoreError.factory;
+
+function create(config) {
+  if (!config || !config.rootDir) {
+    throw new Error("local protocol requires { rootDir }");
+  }
+  var rootDir = path.resolve(config.rootDir);
+  if (!fs.existsSync(rootDir)) fs.mkdirSync(rootDir, { recursive: true });
+
+  function put(key, body, _opts) {
+    cluster.requireLeader();
+    var full = _resolveSafe(rootDir, key);
+    var dir = path.dirname(full);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    if (Buffer.isBuffer(body)) {
+      atomicFile.writeSync(full, body);
+      return Promise.resolve({ size: body.length });
+    }
+    if (body && typeof body.pipe === "function") {
+      // Streaming put — pipe directly to disk
+      return new Promise(function (resolve, reject) {
+        var ws = fs.createWriteStream(full);
+        var bytes = 0;
+        body.on("data", function (chunk) { bytes += chunk.length; });
+        body.pipe(ws);
+        ws.on("finish", function () { resolve({ size: bytes }); });
+        ws.on("error", reject);
+        body.on("error", reject);
+      });
+    }
+    if (typeof body === "string") {
+      var buf = Buffer.from(body, "utf8");
+      atomicFile.writeSync(full, buf);
+      return Promise.resolve({ size: buf.length });
+    }
+    return Promise.reject(_err("INVALID_BODY", "put body must be Buffer, Readable, or string", true));
+  }
+
+  function get(key) {
+    var full = _resolveSafe(rootDir, key);
+    if (!fs.existsSync(full)) {
+      return Promise.reject(_err("NOT_FOUND", "key not found: " + key, true));
+    }
+    return Promise.resolve(fs.readFileSync(full));
+  }
+
+  function getStream(key) {
+    var full = _resolveSafe(rootDir, key);
+    if (!fs.existsSync(full)) {
+      throw _err("NOT_FOUND", "key not found: " + key, true);
+    }
+    return fs.createReadStream(full);
+  }
+
+  function head(key) {
+    var full = _resolveSafe(rootDir, key);
+    if (!fs.existsSync(full)) {
+      return Promise.reject(_err("NOT_FOUND", "key not found: " + key, true));
+    }
+    var stat = fs.statSync(full);
+    return Promise.resolve({
+      size:         stat.size,
+      lastModified: stat.mtimeMs,
+    });
+  }
+
+  function deleteKey(key) {
+    cluster.requireLeader();
+    var full = _resolveSafe(rootDir, key);
+    if (!fs.existsSync(full)) return Promise.resolve(false);
+    fs.unlinkSync(full);
+    return Promise.resolve(true);
+  }
+
+  function list(prefix, opts) {
+    opts = opts || {};
+    var max = opts.maxResults || 1000;
+    var prefixDir = prefix ? _resolveSafe(rootDir, prefix.replace(/\/$/, "")) : rootDir;
+    var results = [];
+    function walk(dir, base) {
+      if (results.length >= max) return;
+      var entries = atomicFile.listDir(dir, { includeStat: true });
+      for (var i = 0; i < entries.length; i++) {
+        if (results.length >= max) break;
+        var entry = entries[i];
+        var rel = base ? base + "/" + entry.name : entry.name;
+        if (entry.isDirectory) walk(entry.fullPath, rel);
+        else results.push({ key: rel, size: entry.sizeBytes, lastModified: entry.mtimeMs });
+      }
+    }
+    var basePrefix = prefix ? prefix.replace(/\/$/, "") : "";
+    walk(prefixDir, basePrefix);
+    return Promise.resolve({ items: results, truncated: results.length >= max });
+  }
+
+  function _presignNotSupported(direction) {
+    return function (_opts) {
+      throw _err("PRESIGN_NOT_SUPPORTED",
+        "local backend does not issue presigned " + direction + " URLs — " +
+        "clients on the same host should call storage." +
+        (direction === "upload" ? "saveFile" : "getFileBuffer") + "() directly",
+        true);
+    };
+  }
+
+  return {
+    protocol:  "local",
+    rootDir:   rootDir,
+    put:       put,
+    get:       get,
+    getStream: getStream,
+    head:      head,
+    delete:    deleteKey,
+    list:      list,
+    presignedUploadUrl:    _presignNotSupported("upload"),
+    presignedDownloadUrl:  _presignNotSupported("download"),
+    presignedUploadPolicy: function () {
+      throw _err("PRESIGN_NOT_SUPPORTED",
+        "local backend does not issue presigned upload policies — " +
+        "clients on the same host should call storage.saveFile() directly " +
+        "with their own size validation", true);
+    },
+  };
+}
+
+module.exports = { create: create };

package/lib/object-store/retry.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Thin re-export of the top-level `lib/retry.js` primitive.
+ *
+ * The retry + circuit breaker primitive used to live here for historical
+ * reasons (it was built alongside the object-store dispatcher). It graduated
+ * to a top-level primitive in v0.2.24 so other framework consumers (queue,
+ * external-db, log-stream-webhook, atomic-file, handlers) and operator code
+ * via `b.retry` share one canonical implementation.
+ *
+ * This module is preserved as a re-export so existing internal requires
+ * keep working without churn.
+ */
+
+module.exports = require("../retry");