async-background 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 851bdc350f52df868547200fe10a0d93b06b692b605c6e761b28262e2691a4df
-  data.tar.gz: 8eccc004e5250df5349135a979a59e52f7450ee356245e8cab17b4b6e2a9a9f6
+  metadata.gz: a8f8593628f08094cc53b6c69eff34e3a4be9e8c12de5bd72f1447857aab2682
+  data.tar.gz: e9e441eb2b6f775cd52d2704c8a2b24d9ac771a24beb07d33f78d81285d41f1c
 SHA512:
-  metadata.gz: 7ce63c6e58d96670add9cbfc438ab5cb33d2472c3ef6d4484cde4682f3416749f946cadc1fe00333e1e6e68b1b861df8d6d9cb88a7e520f48f73ecc9b4c86265
-  data.tar.gz: e4f7fc4fb560dba97580f0bd1ea446ade22edb219e1fba7d725ecb4b798b2feddf76b5266f3e408516b33d880046c481ca7b0746ae08accd70a1665466143019
+  metadata.gz: 194c82e280d24821e756849cc9f3f74db8cbadc424d4984fb3a58d10d21864cbe13b1adfa84aa3bf1bd6b9996d59e1d423d5c865c2d1ec33846679ed2ab936f0
+  data.tar.gz: 518bc2a692d0ade6ea02ff18ebca2a3078e02365ffd77fe9850d8bccc64b7243ea871efeec2913f33fe7ecdaeb8fa6a56067e57f36d5852adf59302cc656416e

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.7.1
+
+### Features
+- **Tunable `Store` options via `StoreOptions`** — three knobs exposed for SQLite tuning, validated at construction time so misconfigurations fail fast at boot:
+  - `mmap` (`true`/`false`, default `true`) — toggle memory-mapped I/O
+  - `synchronous` (`:normal`/`:full`/`:extra`, default `:normal`) — durability vs throughput
+  - `wal_autocheckpoint` (`Integer` in `100..10_000`, default `1_000`) — WAL checkpoint frequency in pages
+
+  Range and enum validation prevent foot-guns (e.g. `wal_autocheckpoint: 100_000` would bloat WAL beyond `journal_size_limit`). See [Get Started → Store tuning](docs/GET_STARTED.md) for trade-offs of each knob
+
+### Breaking changes
+- `Store.new(path:, mmap:)` → `Store.new(path:, options: { mmap: ... })`. Direct `mmap:` keyword argument removed in favor of the unified `options:` hash. Users who construct `Store` manually (e.g. for web-worker enqueue) need to update the call site
+
 ## 0.6.2
 
 ### Features

data/lib/async/background/queue/store.rb

@@ -6,6 +6,49 @@ require_relative '../clock'
 module Async
   module Background
     module Queue
+      SYNCHRONOUS_LEVELS = { normal: 'NORMAL', full: 'FULL', extra: 'EXTRA' }.freeze
+      WAL_AUTOCHECKPOINT_RANGE = 100..10_000
+      DEFAULTS = { mmap: true, synchronous: :normal, wal_autocheckpoint: 1_000 }.freeze
+      MMAP_SIZE = 268_435_456
+
+      StoreOptions = Data.define(:mmap, :synchronous, :wal_autocheckpoint) do
+        def self.build(value = {}) = value.is_a?(self) ? value : new(**DEFAULTS, **value)
+
+        def initialize(mmap:, synchronous:, wal_autocheckpoint:)
+          unless mmap == true || mmap == false
+            raise ArgumentError, "mmap must be true or false, got #{mmap.inspect}"
+          end
+
+          unless SYNCHRONOUS_LEVELS.key?(synchronous)
+            raise ArgumentError,
+              "synchronous must be one of #{SYNCHRONOUS_LEVELS.keys.inspect}, got #{synchronous.inspect}"
+          end
+
+          unless wal_autocheckpoint.is_a?(Integer) && WAL_AUTOCHECKPOINT_RANGE.cover?(wal_autocheckpoint)
+            raise ArgumentError,
+              "wal_autocheckpoint must be an Integer in #{WAL_AUTOCHECKPOINT_RANGE}, " \
+              "got #{wal_autocheckpoint.inspect}"
+          end
+
+          super
+        end
+
+        def synchronous_pragma = SYNCHRONOUS_LEVELS.fetch(synchronous)
+        def mmap_size = mmap ? MMAP_SIZE : 0
+
+        def pragma_sql
+          <<~SQL
+            PRAGMA journal_mode       = WAL;
+            PRAGMA synchronous        = #{synchronous_pragma};
+            PRAGMA mmap_size          = #{mmap_size};
+            PRAGMA cache_size         = -16000;
+            PRAGMA temp_store         = MEMORY;
+            PRAGMA journal_size_limit = 67108864;
+            PRAGMA wal_autocheckpoint = #{wal_autocheckpoint};
+          SQL
+        end
+      end
+
       class Store
         include Clock
 
@@ -25,29 +68,17 @@ module Async
           CREATE INDEX IF NOT EXISTS idx_jobs_pending ON jobs(run_at, id) WHERE status = 'pending';
         SQL
 
-        MMAP_SIZE = 268_435_456
-        PRAGMAS = ->(mmap_size) {
-          <<~SQL
-            PRAGMA journal_mode       = WAL;
-            PRAGMA synchronous        = NORMAL;
-            PRAGMA mmap_size          = #{mmap_size};
-            PRAGMA cache_size         = -16000;
-            PRAGMA temp_store         = MEMORY;
-            PRAGMA busy_timeout       = 5000;
-            PRAGMA journal_size_limit = 67108864;
-          SQL
-        }.freeze
-
         CLEANUP_INTERVAL = 300
         CLEANUP_AGE      = 3600
 
-        attr_reader :path
+        attr_reader :path, :options
 
-        def initialize(path: self.class.default_path, mmap: true)
-          @path            = path
-          @pragma_sql      = PRAGMAS.call(mmap ? MMAP_SIZE : 0).freeze
-          @db              = nil
-          @schema_checked  = false
+        def initialize(path: self.class.default_path, options: {})
+          @path           = path
+          @options        = StoreOptions.build(options)
+          @pragma_sql     = @options.pragma_sql.freeze
+          @db             = nil
+          @schema_checked = false
           @last_cleanup_at = nil
         end
 

data/lib/async/background/runner.rb

@@ -78,8 +78,8 @@ module Async
 
         @listen_queue = true
         @queue_store  = Queue::Store.new(
-          path: queue_db_path || Queue::Store.default_path,
-          mmap: queue_mmap
+          path:    queue_db_path || Queue::Store.default_path,
+          options: { mmap: queue_mmap }
         )
 
         socket_path = File.join(queue_socket_dir, "async_bg_worker_#{worker_index}.sock")

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '0.7.0'
+    VERSION = '0.7.1'
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Roman Hajdarov
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-23 00:00:00.000000000 Z
+date: 2026-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -113,6 +114,7 @@ metadata:
   source_code_uri: https://github.com/roman-haidarov/async-background
   changelog_uri: https://github.com/roman-haidarov/async-background/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/roman-haidarov/async-background/issues
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -127,7 +129,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: Lightweight heap-based cron/interval scheduler for Async.
 test_files: []