@cloudbitmaps/core 0.8.2 → 0.10.0

package/dist/testing/fuzz-core.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal surface for the coverage-guided fuzz harness, CORE half.
+ *
+ * Exposes the untrusted-bytes entry points the fuzz targets drive — including `parseIndex`, which is
+ * deliberately **NOT public API**. Built by a dedicated `tsup` entry to the git-ignored repo-root `fuzz/build/`,
+ * so it never enters `dist/` or the published package. Keeping it here (rather than widening
+ * `packages/core/src/index.ts`) is the point: a test harness must not expand the published surface.
+ * The codec half lives in the flavor package (`packages/roaring/src/testing/fuzz-codec.ts`), because a concrete
+ * bitmap codec is exactly what core does not have.
+ */
+export { CrbmReader, parseIndex } from '../core/crbm/reader.js';
+export { BufferReader } from '../core/blob.js';
+export { CloudRoaringError, isCloudRoaringError } from '../core/errors.js';
+export { DEFAULT_MAX_PAYLOAD_BYTES } from '../core/crbm/format.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudbitmaps/core",
-  "version": "0.8.2",
-  "description": "The codec-agnostic cloud engine behind the @cloudbitmaps family: tiered storage (RAM → warm KV → cold object store), chunk-skipping intersection, the .crbm format, crash-safe compaction, encryption-at-rest, and every storage driver.",
+  "version": "0.10.0",
+  "description": "Codec-agnostic engine for CloudBitmaps: the .crbm format, the write-once load/publish path, generation GC, encryption-at-rest, and the driver ports. No cloud SDK.",
   "keywords": [
     "roaring",
     "bitmap",
@@ -15,18 +15,8 @@
     "typescript",
     "set",
     "set-intersection",
-    "s3",
-    "dynamodb",
-    "gcs",
-    "azure",
-    "postgres",
-    "redis",
-    "mongodb",
-    "cassandra",
-    "mysql",
-    "mariadb",
     "serverless",
-    "tiered-storage",
+    "object-storage",
     "scale-to-zero",
     "segmentation",
     "audience",
@@ -36,7 +26,8 @@
   "author": "Sharvil Kadam",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git"
+    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git",
+    "directory": "packages/core"
   },
   "homepage": "https://github.com/cloudbitmaps/cloudbitmaps#readme",
   "bugs": {
@@ -44,62 +35,19 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     },
-    "./s3": {
-      "types": "./dist/s3/index.d.ts",
-      "import": "./dist/s3/index.js",
-      "require": "./dist/s3/index.cjs"
-    },
-    "./dynamodb": {
-      "types": "./dist/dynamodb/index.d.ts",
-      "import": "./dist/dynamodb/index.js",
-      "require": "./dist/dynamodb/index.cjs"
-    },
-    "./gcs": {
-      "types": "./dist/gcs/index.d.ts",
-      "import": "./dist/gcs/index.js",
-      "require": "./dist/gcs/index.cjs"
-    },
-    "./azure": {
-      "types": "./dist/azure/index.d.ts",
-      "import": "./dist/azure/index.js",
-      "require": "./dist/azure/index.cjs"
-    },
-    "./postgres": {
-      "types": "./dist/postgres/index.d.ts",
-      "import": "./dist/postgres/index.js",
-      "require": "./dist/postgres/index.cjs"
-    },
-    "./redis": {
-      "types": "./dist/redis/index.d.ts",
-      "import": "./dist/redis/index.js",
-      "require": "./dist/redis/index.cjs"
-    },
-    "./mongodb": {
-      "types": "./dist/mongodb/index.d.ts",
-      "import": "./dist/mongodb/index.js",
-      "require": "./dist/mongodb/index.cjs"
-    },
-    "./cassandra": {
-      "types": "./dist/cassandra/index.d.ts",
-      "import": "./dist/cassandra/index.js",
-      "require": "./dist/cassandra/index.cjs"
-    },
-    "./mysql": {
-      "types": "./dist/mysql/index.d.ts",
-      "import": "./dist/mysql/index.js",
-      "require": "./dist/mysql/index.cjs"
+    "./driver-kit": {
+      "types": "./dist/driver-kit.d.ts",
+      "default": "./dist/driver-kit.js"
     }
   },
   "files": [
@@ -111,62 +59,18 @@
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3",
-    "@aws-sdk/client-s3": "^3",
-    "@azure/storage-blob": "^12",
-    "@google-cloud/storage": "^7",
-    "cassandra-driver": "^4",
-    "ioredis": "^5",
-    "mongodb": "^6",
-    "mysql2": "^3",
-    "pg": "^8"
-  },
-  "peerDependenciesMeta": {
-    "@aws-sdk/client-dynamodb": {
-      "optional": true
-    },
-    "@aws-sdk/client-s3": {
-      "optional": true
-    },
-    "@azure/storage-blob": {
-      "optional": true
-    },
-    "@google-cloud/storage": {
-      "optional": true
-    },
-    "cassandra-driver": {
-      "optional": true
-    },
-    "ioredis": {
-      "optional": true
-    },
-    "mongodb": {
-      "optional": true
-    },
-    "mysql2": {
-      "optional": true
-    },
-    "pg": {
-      "optional": true
-    }
-  },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1075.0",
-    "@aws-sdk/client-s3": "^3.1075.0",
-    "@azure/storage-blob": "^12",
-    "@google-cloud/storage": "^7.0.0",
-    "cassandra-driver": "^4",
-    "ioredis": "^5",
-    "mongodb": "^6",
-    "mysql2": "^3.23.1",
-    "pg": "^8",
-    "@types/pg": "^8",
     "@types/node": "^22.0.0",
-    "tsup": "^8.0.0",
     "typescript": "^5.5.0"
   },
+  "typesVersions": {
+    "*": {
+      "driver-kit": [
+        "./dist/driver-kit.d.ts"
+      ]
+    }
+  },
   "scripts": {
-    "build": "tsup"
+    "build": "node ../../scripts/build.mjs"
   }
 }

package/dist/azure/index.cjs

@@ -1,368 +0,0 @@
-'use strict';
-
-var crypto = require('crypto');
-
-// src/drivers/azure/cold.ts
-
-// src/core/errors.ts
-var ERROR_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error");
-var TRANSIENT_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error.transient");
-var CloudRoaringError = class extends Error {
-  /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
-  [ERROR_BRAND] = true;
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var ValidationError = class extends CloudRoaringError {
-};
-var WriteConflictError = class extends CloudRoaringError {
-};
-var NotFoundError = class extends CloudRoaringError {
-};
-var TransientError = class extends CloudRoaringError {
-  /** A second brand so the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
-  [TRANSIENT_BRAND] = true;
-  constructor(message, options) {
-    super(message);
-    if (options && "cause" in options) this.cause = options.cause;
-  }
-};
-function hasBrand(err, brand) {
-  return typeof err === "object" && err !== null && err[brand] === true;
-}
-function isCloudRoaringError(err) {
-  return hasBrand(err, ERROR_BRAND);
-}
-function isWriteConflictError(err) {
-  return isCloudRoaringError(err) && err.name === "WriteConflictError";
-}
-function isNotFoundError(err) {
-  return isCloudRoaringError(err) && err.name === "NotFoundError";
-}
-function isValidationError(err) {
-  return isCloudRoaringError(err) && err.name === "ValidationError";
-}
-
-// src/core/validate.ts
-var NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
-function validatePart(value, field) {
-  if (typeof value !== "string" || !NAME.test(value) || value.includes("..")) {
-    throw new ValidationError(
-      `${field} must match ${String(NAME)} and contain no "..": got ${JSON.stringify(value)}`
-    );
-  }
-}
-function validateSegmentRef(ref) {
-  validatePart(ref.segment, "segment");
-  if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
-}
-
-// src/drivers/_shared/keys.ts
-var DEFAULT_NAMESPACE = "_default";
-function namespacePart(namespace) {
-  return namespace ?? DEFAULT_NAMESPACE;
-}
-
-// src/drivers/azure/keys.ts
-var SUFFIX = ".crbm";
-function prefixPart(prefix) {
-  if (prefix === void 0) return "";
-  const trimmed = prefix.replace(/^\/+|\/+$/g, "");
-  return trimmed === "" ? "" : `${trimmed}/`;
-}
-function normalizeAzurePrefix(prefix) {
-  if (prefix === void 0) return void 0;
-  for (const ch of prefix) {
-    if (ch.charCodeAt(0) < 32) {
-      throw new ValidationError("prefix must not contain control characters");
-    }
-  }
-  for (const segment of prefix.split("/")) {
-    if (segment === "." || segment === "..") {
-      throw new ValidationError(
-        `prefix must not contain "." or ".." path segments: ${JSON.stringify(prefix)}`
-      );
-    }
-  }
-  return prefix;
-}
-function segmentObjectPrefix(prefix, ref) {
-  validateSegmentRef(ref);
-  return `${prefixPart(prefix)}${namespacePart(ref.namespace)}/segments/${ref.segment}.`;
-}
-function coldObjectName(prefix, key) {
-  if (!Number.isInteger(key.generation) || key.generation < 0) {
-    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
-  }
-  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
-}
-function parseGenerationFromName(segmentPrefix, objectName) {
-  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
-  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
-
-// src/drivers/azure/azure-errors.ts
-function httpStatus(err) {
-  const code = err?.statusCode;
-  return typeof code === "number" ? code : void 0;
-}
-function azureCode(err) {
-  const e = err;
-  if (typeof e?.code === "string") return e.code;
-  if (typeof e?.details?.errorCode === "string") return e.details.errorCode;
-  return void 0;
-}
-function networkCode(err) {
-  const code = err?.code;
-  return typeof code === "string" ? code : void 0;
-}
-function isConditionalConflict(err) {
-  const status = httpStatus(err);
-  if (status === 409 || status === 412) return true;
-  const code = azureCode(err);
-  return code === "BlobAlreadyExists" || code === "ConditionNotMet";
-}
-function isNotFound(err) {
-  return httpStatus(err) === 404 || azureCode(err) === "BlobNotFound";
-}
-function isInvalidRange(err) {
-  return httpStatus(err) === 416 || azureCode(err) === "InvalidRange";
-}
-function isTransient(err) {
-  if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
-  const status = httpStatus(err);
-  if (status === 429 || status !== void 0 && status >= 500 && status < 600) return true;
-  const code = azureCode(err);
-  if (code === "ServerBusy" || code === "OperationTimedOut" || code === "InternalError")
-    return true;
-  const net = networkCode(err);
-  return net === "ECONNRESET" || net === "ECONNABORTED" || net === "ETIMEDOUT" || net === "ESOCKETTIMEDOUT" || net === "ECONNREFUSED" || net === "EHOSTUNREACH" || net === "ENETUNREACH" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND";
-}
-
-// src/drivers/azure/cold.ts
-var AZURE_BLOCK_BYTES = 8 * 1024 * 1024;
-var AZURE_MAX_BLOCKS = 5e4;
-var OCTET_STREAM = { blobContentType: "application/octet-stream" };
-var IF_ABSENT = { conditions: { ifNoneMatch: "*" }, blobHTTPHeaders: OCTET_STREAM };
-var AzureBlobColdDriver = class {
-  container;
-  prefix;
-  maxObjectBytes;
-  blockBytes;
-  constructor(options) {
-    this.container = options.containerClient;
-    this.prefix = normalizeAzurePrefix(options.prefix);
-    const requestedBlock = options.blockBytes ?? AZURE_BLOCK_BYTES;
-    if (!Number.isSafeInteger(requestedBlock) || requestedBlock < 1) {
-      throw new ValidationError(
-        `blockBytes must be a positive safe integer; got ${requestedBlock}`
-      );
-    }
-    if (options.maxObjectBytes !== void 0 && (!Number.isSafeInteger(options.maxObjectBytes) || options.maxObjectBytes < 1)) {
-      throw new ValidationError(
-        `maxObjectBytes must be a positive safe integer; got ${options.maxObjectBytes}`
-      );
-    }
-    this.maxObjectBytes = options.maxObjectBytes ?? requestedBlock * AZURE_MAX_BLOCKS;
-    this.blockBytes = Math.max(requestedBlock, Math.ceil(this.maxObjectBytes / AZURE_MAX_BLOCKS));
-  }
-  capabilities() {
-    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
-  }
-  blob(name) {
-    return this.container.getBlockBlobClient(name);
-  }
-  async putImmutable(key, write) {
-    const objectName = coldObjectName(this.prefix, key);
-    const sink = new AzureBlockBlobSink(
-      this.blob(objectName),
-      this.blockBytes,
-      this.maxObjectBytes
-    );
-    try {
-      await write(sink);
-      return await sink.finish();
-    } catch (err) {
-      if (isConditionalConflict(err)) {
-        throw new WriteConflictError(
-          `generation already exists (write-once): ${key.segment}.${key.generation}`
-        );
-      }
-      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) throw err;
-      throw this.mapError(err);
-    }
-  }
-  async getRange(key, offset, length) {
-    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
-      throw new ValidationError(`invalid range offset=${offset} length=${length}`);
-    }
-    if (length === 0) return new Uint8Array(0);
-    const objectName = coldObjectName(this.prefix, key);
-    try {
-      const res = await this.blob(objectName).download(offset, length);
-      const bytes = await collect(res.readableStreamBody);
-      if (bytes.length !== length) {
-        throw new ValidationError(
-          `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`
-        );
-      }
-      return bytes;
-    } catch (err) {
-      throw this.mapReadError(err, key);
-    }
-  }
-  async getTail(key, maxBytes) {
-    const objectName = coldObjectName(this.prefix, key);
-    try {
-      const props = await this.blob(objectName).getProperties();
-      const size = props.contentLength ?? 0;
-      if (!Number.isSafeInteger(size) || size < 0) {
-        throw new ValidationError(`Azure returned an invalid blob size: ${String(size)}`);
-      }
-      if (maxBytes <= 0 || size === 0) return { bytes: new Uint8Array(0), size };
-      const take = Math.min(maxBytes, size);
-      const res = await this.blob(objectName).download(size - take, take);
-      return { bytes: await collect(res.readableStreamBody), size };
-    } catch (err) {
-      throw this.mapReadError(err, key);
-    }
-  }
-  async delete(key) {
-    try {
-      await this.blob(coldObjectName(this.prefix, key)).deleteIfExists();
-    } catch (err) {
-      throw this.mapError(err);
-    }
-  }
-  async *list(ref) {
-    const prefix = segmentObjectPrefix(this.prefix, ref);
-    try {
-      for await (const item of this.container.listBlobsFlat({ prefix })) {
-        const generation = parseGenerationFromName(prefix, item.name);
-        if (generation !== null) {
-          yield { namespace: ref.namespace, segment: ref.segment, generation };
-        }
-      }
-    } catch (err) {
-      throw this.mapError(err);
-    }
-  }
-  /** Map Azure read errors to the driver vocabulary; pass everything else through {@link mapError}. */
-  mapReadError(err, key) {
-    if (isValidationError(err)) return err;
-    if (isNotFound(err))
-      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
-    if (isInvalidRange(err)) {
-      return new ValidationError(`range out of bounds for ${key.segment}.${key.generation}`);
-    }
-    return this.mapError(err);
-  }
-  /**
-   * Reclassify a transient Azure fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}
-   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every
-   * client-call site, so callers + the decorator only ever see typed errors.
-   */
-  mapError(err) {
-    if (isTransient(err)) {
-      return new TransientError(
-        `transient Azure fault: ${err?.code ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
-  }
-};
-function concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const p of parts) {
-    out.set(p, offset);
-    offset += p.length;
-  }
-  return out;
-}
-var AzureBlockBlobSink = class {
-  constructor(blob, blockBytes, maxObjectBytes) {
-    this.blob = blob;
-    this.blockBytes = blockBytes;
-    this.maxObjectBytes = maxObjectBytes;
-  }
-  blob;
-  blockBytes;
-  maxObjectBytes;
-  hash = crypto.createHash("sha256");
-  pending = [];
-  pendingLen = 0;
-  total = 0;
-  blockIds = [];
-  /**
-   * A random per-sink nonce folded into every block id. Azure pools **uncommitted** blocks per *blob name*,
-   * keyed by id — so two writers racing the same generation key on the staged path MUST use disjoint id spaces,
-   * else one would overwrite the other's staged blocks and a commit could reference an interleaved mix of both
-   * writers' bytes (a corrupt blob whose committed content wouldn't match the returned SHA-256). A per-instance
-   * nonce makes each writer's ids unique, so the winner commits only its own blocks and the loser cleanly 409s.
-   * 6 random bytes → 12 fixed hex chars, keeping every id equal-length (Azure's within-blob id requirement).
-   */
-  uploadNonce = crypto.randomBytes(6).toString("hex");
-  /** Fixed-width (constant length within a blob) AND per-sink-unique block id: `<nonce>-<zero-padded index>`. */
-  blockId(n) {
-    return Buffer.from(`${this.uploadNonce}-${String(n).padStart(6, "0")}`).toString("base64");
-  }
-  async write(bytes) {
-    if (bytes.length === 0) return;
-    this.total += bytes.length;
-    if (this.total > this.maxObjectBytes) {
-      throw new ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
-    }
-    this.hash.update(bytes);
-    this.pending.push(new Uint8Array(bytes));
-    this.pendingLen += bytes.length;
-    if (this.pendingLen >= this.blockBytes) await this.flushBlock();
-  }
-  /** Stage the buffered bytes (≥ one block) as a single block, freeing them. */
-  async flushBlock() {
-    if (this.blockIds.length >= AZURE_MAX_BLOCKS) {
-      throw new ValidationError(`upload exceeded the Azure ${AZURE_MAX_BLOCKS}-block limit`);
-    }
-    const body = concatBytes(this.pending, this.pendingLen);
-    this.pending.length = 0;
-    this.pendingLen = 0;
-    const id = this.blockId(this.blockIds.length);
-    await this.blob.stageBlock(id, body, body.length);
-    this.blockIds.push(id);
-  }
-  /** Commit the blob: a single conditional `upload` if it fit in one block, else commit the staged block list. */
-  async finish() {
-    const sha256 = this.hash.digest("hex");
-    if (this.blockIds.length === 0) {
-      const body = concatBytes(this.pending, this.pendingLen);
-      await this.blob.upload(body, body.length, IF_ABSENT);
-      return { size: this.total, sha256 };
-    }
-    if (this.pendingLen > 0) await this.flushBlock();
-    await this.blob.commitBlockList(this.blockIds, IF_ABSENT);
-    return { size: this.total, sha256 };
-  }
-};
-async function collect(body) {
-  if (body === void 0) {
-    throw new NotFoundError("Azure download returned no body");
-  }
-  const chunks = [];
-  let total = 0;
-  for await (const chunk of body) {
-    const u8 = typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk);
-    chunks.push(u8);
-    total += u8.length;
-  }
-  return concatBytes(chunks, total);
-}
-
-exports.AzureBlobColdDriver = AzureBlobColdDriver;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map