lithos 0.1.0

data/lib/lithos/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lithos
+  VERSION = "0.1.0"
+end

data/lib/lithos.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "lithos/version"
+require "lithos/lithos" # native extension: defines Lithos::DB + Lithos::Error
+
+# lithos — a small embedded, ordered, crash-safe key-value store.
+#
+#   Lithos.open("data/db") do |db|
+#     db["alpha"] = "1"
+#     db.put("\x00bin\xff", "raw")           # binary keys/values welcome
+#     db["alpha"]                            # => "1"
+#     db.scan(gte: "a", lt: "m") { |k, v| }  # ordered range
+#   end                                      # auto-closed (flushes + fsyncs)
+module Lithos
+  # Open a store at `path` (a directory, created if missing). Options:
+  #   sync:           durably fsync each write before it returns (default true)
+  #   memtable_bytes: flush the in-memory table to an SSTable past this size
+  #
+  # With a block: yields the store, closes it when the block returns (even on
+  # error), and returns the block's value. Without a block: returns the store,
+  # and the caller must #close it.
+  def self.open(path, **opts)
+    db = DB.new(path, **opts)
+    return db unless block_given?
+
+    begin
+      yield db
+    ensure
+      db.close
+    end
+  end
+
+  class DB
+    include Enumerable
+
+    # --- mutators (forbidden while an each/scan is in progress) --------------
+    # The merge iterator holds raw pointers into memory-mapped SSTables and live
+    # memtable iterators; mutating mid-scan would free them underneath it. We
+    # refuse here with a plain Ruby exception (which unwinds safely), rather than
+    # let it reach the C engine during iteration.
+
+    def put(key, value)
+      forbid_during_iteration!
+      _put(key, value)
+    end
+
+    def delete(key)
+      forbid_during_iteration!
+      _delete(key)
+    end
+
+    def flush
+      forbid_during_iteration!
+      _flush
+    end
+
+    def compact
+      forbid_during_iteration!
+      _compact
+    end
+
+    def close
+      forbid_during_iteration!
+      _close
+    end
+
+    # Hash-like access. `db[k]` => value or nil; `db[k] = v` stores v.
+    def [](key)
+      get(key)
+    end
+
+    def []=(key, value)
+      put(key, value)
+      value
+    end
+
+    # Like Hash#fetch: return the value, else the block result, else the default,
+    # else raise KeyError. (Stored values are never nil, so nil == absent.)
+    def fetch(key, *default)
+      if default.size > 1
+        raise ArgumentError, "wrong number of arguments (given #{default.size + 1}, expected 1..2)"
+      end
+
+      value = get(key)
+      return value unless value.nil?
+      return yield(key) if block_given?
+      return default.first unless default.empty?
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    alias include? key?
+    alias has_key? key?
+    alias member? key?
+
+    # Iterate all pairs in ascending (unsigned-byte) key order.
+    def each(&block)
+      return enum_for(:each) unless block
+
+      bounded_each(nil, false, nil, false, &block)
+    end
+    alias each_pair each
+
+    # Iterate keys only, ascending.
+    def each_key
+      return enum_for(:each_key) unless block_given?
+
+      bounded_each(nil, false, nil, false) { |k, _| yield k }
+    end
+
+    # Ordered range scan. Bounds are optional; gt/lt are exclusive, gte/lte
+    # inclusive. Returns an Enumerator without a block.
+    def scan(gte: nil, gt: nil, lte: nil, lt: nil, &block)
+      lower, lower_incl = gt ? [gt, false] : (gte ? [gte, true] : [nil, false])
+      upper, upper_incl = lt ? [lt, false] : (lte ? [lte, true] : [nil, false])
+      bounded_each(lower, lower_incl, upper, upper_incl, &block)
+    end
+
+    # Half-open range [from, to) in ascending order.
+    def range(from, to, &block)
+      bounded_each(from, true, to, false, &block)
+    end
+
+    # Number of live keys. O(n) — counts via an ordered scan.
+    def size
+      n = 0
+      each_key { n += 1 }
+      n
+    end
+    alias length size
+
+    def empty?
+      each { return false }
+      true
+    end
+
+    def to_h
+      h = {}
+      each { |k, v| h[k] = v }
+      h
+    end
+
+    def inspect
+      "#<Lithos::DB path=#{path.inspect}#{closed? ? ' (closed)' : ''}>"
+    end
+
+    private
+
+    def forbid_during_iteration!
+      return unless (@iterating || 0).positive?
+
+      raise Error, "lithos: cannot modify the store during iteration"
+    end
+
+    # Shared range driver; positional args so enum_for forwards cleanly. The
+    # @iterating depth lets reads nest while mutations are blocked, and the
+    # ensure guarantees the count is restored even on break/exception.
+    def bounded_each(lower, lower_incl, upper, upper_incl, &block)
+      return enum_for(:bounded_each, lower, lower_incl, upper, upper_incl) unless block
+
+      @iterating = (@iterating || 0) + 1
+      begin
+        _each_range(lower, lower_incl, upper, upper_incl, &block)
+      ensure
+        @iterating -= 1
+      end
+      self
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: lithos
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  lithos is a self-contained embedded key-value store written from scratch as a
+  native extension — no external database dependency. It uses a log-structured
+  merge (LSM) tree: a write-ahead log makes every write durable, an in-memory
+  sorted memtable flushes to immutable SSTables (with bloom filters), and
+  compaction merges them. Keys and values are arbitrary binary strings; keys
+  are kept in sorted order so you get ordered iteration and range scans, plus
+  crash recovery via WAL replay. Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/lithos/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/lithos/extconf.rb
+- ext/lithos/lithos.cpp
+- lib/lithos.rb
+- lib/lithos/version.rb
+homepage: https://github.com/main-path/lithos
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/lithos
+  changelog_uri: https://github.com/main-path/lithos/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/lithos/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A small embedded, ordered, crash-safe key-value store (LSM-tree) for Ruby.
+test_files: []