pixl-server-storage 4.2.2 → 4.3.0

package/README.md

@@ -65,6 +65,7 @@ Here is the table of contents for this current document:
 		+ [AWS RDS](#aws-rds)
 		+ [Postgres Password Plugin](#postgres-password-plugin)
 	* [Hybrid](#hybrid)
+- [Cache Buffer Copying](#cache-buffer-copying)
 - [Key Normalization](#key-normalization)
 - [Basic Functions](#basic-functions)
 	* [Storing Records](#storing-records)
@@ -417,8 +418,9 @@ The properties are as follows:
 | `enabled` | Boolean | Set this to `true` to enable the filesystem caching system. |
 | `maxItems` | Integer | This is the maximum number of objects to allow in the cache. |
 | `maxBytes` | Integer | This is the maximum number of bytes to allow in the cache. |
+| `copyBuffers` | Boolean | Defaults to `true`.  Stores independent, unpooled copies of cached Buffers.  Set to `false` to opt out.  See [Cache Buffer Copying](#cache-buffer-copying). |
 
-The cache will automatically expire objects in LRU fashion when either of the limits are exceeded (whichever is hit first).  Set the properties to `0` for no limit.
+The cache will automatically expire objects in LRU fashion when either of the limits are exceeded (whichever is hit first).  Set either limit to `0` for no limit.
 
 Note that binary records are **not** cached.  This system is for JSON records only.
 
@@ -518,8 +520,9 @@ The properties are as follows:
 | `enabled` | Boolean | Set this to `true` to enable the S3 caching system. |
 | `maxItems` | Integer | This is the maximum number of objects to allow in the cache. |
 | `maxBytes` | Integer | This is the maximum number of bytes to allow in the cache. |
+| `copyBuffers` | Boolean | Defaults to `true`.  Stores independent, unpooled copies of cached Buffers.  Set to `false` to opt out.  See [Cache Buffer Copying](#cache-buffer-copying). |
 
-The cache will automatically expire objects in LRU fashion when either of the limits are met (whichever is reached first).  Set the properties to `0` for no limit.
+The cache will automatically expire objects in LRU fashion when either of the limits are met (whichever is reached first).  Set either limit to `0` for no limit.
 
 It is recommended that you set the `maxItems` and `maxBytes` high enough to allow new data written to live for *at least* several seconds before getting expired out of the cache.  This depends on the overall storage throughput of your application, but 1,000 max items and 10 MB max bytes is probably fine for most use cases.
 
@@ -1055,6 +1058,31 @@ Note that all of the engine configuration objects are on the same level as the `
 
 When transactions are enabled, the `Hybrid` engine routes transaction commits through the configured `docEngine`, because pixl-server-storage transactions only apply to JSON records.  If the `docEngine` supports native transactions, such as Postgres, Redis or SQLite, `Hybrid` will use that native commit path automatically.  The `binaryEngine` is not involved in transactions, because binary keys are passed straight through.
 
+# Cache Buffer Copying
+
+All six engine caches (`Filesystem`, `S3`, `Redis`, `RedisCluster`, `SQLite`, and `Postgres`) default to `copyBuffers: true`.  This applies whenever the engine's cache is enabled with `cache.enabled: true`; existing cache configurations receive the new default automatically.
+
+These caches store serialized JSON records as Buffers.  A small Buffer can share a much larger memory allocation with other Buffers, and keeping it in the cache can retain that entire allocation.  Node.js 24.18.0 increased the default Buffer pool size from 8 KiB to 64 KiB, making this retention more costly.  See the [Node.js 24.18.0 release notes](https://nodejs.org/en/blog/release/v24.18.0).
+
+The Postgres report in [issue #8](https://github.com/jhuckaby/pixl-server-storage/issues/8) demonstrated how retained backing allocations could greatly exceed the cached payload size.  The same retention pattern can affect all six engines, so Buffer copying is enabled by default across their caches.  Each cached Buffer gets its own unpooled copy when added or replaced, preventing it from retaining an oversized shared allocation.  This adds an allocation and byte copy on insertion, but cache hits do not make additional Buffer copies.  The `maxBytes` setting still measures cache key and value sizes, rather than total process memory.
+
+If you need to avoid the extra copying, set `copyBuffers` to `false` inside your engine's `cache` configuration.  For example, merge this fragment into your existing `Storage` configuration for Postgres:
+
+```json
+{
+	"Postgres": {
+		"cache": {
+			"enabled": true,
+			"maxItems": 100000,
+			"maxBytes": 104857600,
+			"copyBuffers": false
+		}
+	}
+}
+```
+
+Use the same `cache.copyBuffers` property inside any of the other five engine configuration blocks.  Caching remains enabled in this example, while disabling Buffer copying restores the previous retention behavior.  Omit `copyBuffers`, or set it to `true`, to use the recommended default.
+
 # Key Normalization
 
 In order to maintain compatibility with all the various engines, keys are "normalized" on all entry points.  Specifically, they undergo the following transformations before being passed along to the engine:

package/engines/Filesystem.js

@@ -80,7 +80,7 @@ module.exports = Class.create({
 		var cache_opts = this.config.get('cache');
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/engines/Postgres.js

@@ -67,7 +67,7 @@ module.exports = Class.create({
 		var cache_opts = pg_config.cache;
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/engines/Redis.js

@@ -54,7 +54,7 @@ module.exports = Class.create({
 		var cache_opts = r_config.cache;
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/engines/RedisCluster.js

@@ -56,7 +56,7 @@ module.exports = Class.create({
 		var cache_opts = r_config.cache;
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/engines/S3.js

@@ -49,7 +49,7 @@ module.exports = Class.create({
 		var cache_opts = s3_config.cache;
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/engines/SQLite.js

@@ -68,7 +68,7 @@ module.exports = Class.create({
 		var cache_opts = this.config.get('cache');
 		if (cache_opts && cache_opts.enabled) {
 			this.logDebug(3, "Setting up LRU cache", cache_opts);
-			this.cache = new Cache( Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) );
+			this.cache = new Cache({ copyBuffers: true, ...Tools.copyHashRemoveKeys(cache_opts, { enabled: 1 }) });
 			this.cache.on('expire', function(item, reason) {
 				self.logDebug(9, "Expiring LRU cache object: " + item.key + " due to: " + reason, {
 					key: item.key,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-server-storage",
-	"version": "4.2.2",
+	"version": "4.3.0",
 	"description": "A key/value/list storage component for the pixl-server framework.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-server-storage",
@@ -30,7 +30,7 @@
 		"he": "1.1.1",
 		"moo": "0.4.3",
 		"nearley": "2.20.1",
-		"pixl-cache": "^1.0.6",
+		"pixl-cache": "^1.1.2",
 		"pixl-class": "^1.0.3",
 		"pixl-perf": "^1.0.9",
 		"pixl-server": "^1.0.39",

package/transaction.js

@@ -575,7 +575,8 @@ module.exports = Class.create({
 		trans.aborting = true;
 		
 		var num_actions = Tools.numKeys(trans.keys || {});
-		this.logError('rollback', "Aborting transaction: " + trans.id, { path: path, actions: num_actions });
+		if (num_actions) this.logError('rollback', "Aborting transaction: " + trans.id, { path: path, actions: num_actions });
+		else this.logDebug(6, "Aborting empty transaction (no-op): " + trans.id, { path: path, actions: num_actions });
 		
 		// read in file line by line
 		// (file may not exist, which is fine, hence 'ignore_not_found')