obfs 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2651e95cf754b5588ce3890154db176634ee85ee3cf6bc869940b985787552e1
-  data.tar.gz: 32aa77c08d31978cf973acbaef8636a8f0f431f69dd372ec62ae75430944b322
+  metadata.gz: 648385c40ccd4ea5cb5f608fc7164e1c86757f5ec6c2053711ebf71eab7fa752
+  data.tar.gz: f89b3c016e0949fab62abf7187970db6e16524e927dfa5a98747a6e3d6e7bc83
 SHA512:
-  metadata.gz: 21072b9fa529f96cc73fd144691344a2fa0b3383c2b55737f36f8b597924c182cb02c6c4f041a4c4d9211d95d831e2af16bfacc953a7c15971543a2ba5826a21
-  data.tar.gz: 4de8c6e75e9a1a14aaea87095dca85296d09913fad9db69669a79e6ce4c961d27742d13e35c2c43225608ceb95ec40ba8bfd7d7674244215257b3e940098c5b4
+  metadata.gz: d6617be8b4f8d2c57f9ad353eb5954cf66604c1bfcf03dac73465d0e2854257e52efe979225a55907e75c6be1e59834fbb55f1ba80983bb638c4639f05065569
+  data.tar.gz: 02f0c229b2cff282033822c0d3502b006714ec361411f284123b971bf04ee1f8f94bbb77409bd39a7b66205adf95d2fe8f464fe8d3a24779720148457256fab2

data/lib/obfs/store.rb

@@ -1,132 +1,1017 @@
+require 'json'
+require 'fileutils'
+
 module OBFS
 
-    class Store
+  class Store
 
-            def initialize(attributes = {}) # hash argument
-                @path = (attributes.keys.include? :path) ? attributes[:path] : (File.join(Dir.home, '.obfs'))
-            end
+    def initialize(attributes = {})
+      @path = (attributes.keys.include? :path) ? attributes[:path] : File.join(Dir.home, '.obfs')
+    end
 
-            # regular methods
-
-            def method_missing(m, *args, &block)
-
-                # normalize
-                method_name = m.to_s
-                dataA = args[0]
-                dataB = args[1]
-
-                # prevent traversing out of dir
-                raise "traversal through . and .. not allowed" if ['.', '..'].include? method_name
-
-                # setter call
-                if  method_name.end_with?('=')
-
-                    # clean up name
-                    method_name = method_name.gsub('=','')
-
-                    # reassign if square bracket notation
-                    if method_name == "[]"
-                        method_name = dataA
-                        data = dataB
-                    else # make sure we load the proper method_name and data
-                        method_name = m.to_s.gsub('=','')
-                        data = args[0]
-                    end
-
-                    # prevent traversing out of dir
-                    raise "traversal through . and .. not allowed" if ['.', '..'].include? method_name
-                        
-                    # write data
-                    if data == nil
-                        FileUtils.rm_rf (File.join @path, method_name)
-                    else
-                        FileUtils.rm_rf (File.join @path, method_name) if File.exist? (File.join @path, method_name)
-                        FileUtils.mkpath @path if !File.directory? @path
-                        write(@path, method_name, data)
-                    end
-                
-                # bracket notation
-                elsif method_name == "[]"
-
-                    method_name = dataA.to_s.gsub(/\["/,'').gsub(/"\]/,'')
-
-                    # prevent traversing out of dir
-                    raise "traversal through . and .. not allowed" if ['.', '..'].include? method_name
-                        
-                    if (!File.directory? File.join(@path, method_name)) && (File.exist? File.join(@path, method_name))
-                        read(@path, method_name)
-                    else
-                        OBFS::Store.new({ path: File.join(@path, method_name.to_s) })
-                    end
-
-                # recurse or read
-                else
-
-                    # prevent traversing out of dir
-                    raise "traversal through . and .. not allowed" if ['.', '..'].include? method_name
-
-                    if (!File.directory? File.join(@path, method_name)) && (File.exist? File.join(@path, method_name))
-                        read(@path, method_name)
-                    else
-                        OBFS::Store.new({ path: File.join(@path, method_name.to_s) })
-                    end
-
-                end
-                
-            end
 
-            # special methods
+    # ============================================================
+    # REGULAR METHODS
+    # ============================================================
 
-            # returns current working path for obfs
-            def _path
-                @path
-            end
+    def method_missing(m, *args, &block)
 
-            # returns directory contents in an array
-            def _index
-                Dir.entries(@path).reject { |k| k == '.' || k == '..' } rescue nil
-            end
+      method_name = m.to_s
+      dataA = args[0]
+      dataB = args[1]
 
-            # searches directory contents (1 level) and returns array sorted by relevance
-            def _find(term = '', records = 1000, tolerance = 50)
-                output = []
-                search_space = Dir.entries(@path).reject { |k| k == '.' || k == '..' } rescue []
-                search_space.each do |search_space_term|
-                    if OBFS::Levenshtein.distance(search_space_term, term) <= tolerance && OBFS::WhiteSimilarity.similarity(search_space_term, term) > 0.0
-                        output << search_space_term
-                    end
-                end
-                output.first(records)
-            end
 
-            # searches directory contents (1 level) and returns boolean if term exist
-            def _exist(term = '')
-                exist_space = Dir.entries(@path).reject { |k| k != term.to_s || k == '.' || k == '..' } rescue nil
-                if !exist_space.nil?
-                    if exist_space.length > 0
-                        true
-                    else
-                        false
-                    end
-                else
-                    false
-                end 
-            end
+      # ----------------------------------------------------------
+      # setter call
+      #
+      #   obfs.foo = 'bar'
+      #   obfs['foo'] = 'bar'
+      # ----------------------------------------------------------
 
-            private
+      if method_name.end_with?('=')
 
-            # filesystem R/W
+        method_name = method_name.gsub('=', '')
 
-            def write(path, filename, data)
-                curr_path = File.join path, filename
-                File.write(curr_path, JSON.dump(data))
-            end
 
-            def read(path, filename)
-                curr_path = File.join path, filename
-                JSON.parse(File.open(curr_path).read) rescue File.open(curr_path).read
+        # bracket setter
+        if method_name == "[]"
+
+          method_name = validate_child_name!(dataA)
+          data = dataB
+
+
+        # dot setter
+        else
+
+          method_name = validate_child_name!(
+            m.to_s.gsub('=', '')
+          )
+
+          data = args[0]
+
+        end
+
+
+        # delete
+        if data == nil
+
+          FileUtils.rm_rf(
+            File.join(
+              @path,
+              method_name
+            )
+          )
+
+
+        # write
+        else
+
+          child_path =
+            File.join(
+              @path,
+              method_name
+            )
+
+
+          FileUtils.rm_rf(child_path) if File.exist?(child_path)
+
+          FileUtils.mkpath @path if !File.directory? @path
+
+          write(
+            @path,
+            method_name,
+            data
+          )
+
+        end
+
+
+      # ----------------------------------------------------------
+      # bracket getter
+      #
+      #   obfs['foo']
+      # ----------------------------------------------------------
+
+      elsif method_name == "[]"
+
+        method_name =
+          dataA
+            .to_s
+            .gsub(/\["/, '')
+            .gsub(/"\]/, '')
+
+
+        method_name =
+          validate_child_name!(
+            method_name
+          )
+
+
+        child_path =
+          File.join(
+            @path,
+            method_name
+          )
+
+
+        if !File.directory?(child_path) &&
+           File.exist?(child_path)
+
+          read(
+            @path,
+            method_name
+          )
+
+        else
+
+          OBFS::Store.new({
+            path: child_path
+          })
+
+        end
+
+
+      # ----------------------------------------------------------
+      # dot getter / recursive access
+      #
+      #   obfs.foo.bar
+      # ----------------------------------------------------------
+
+      else
+
+        method_name =
+          validate_child_name!(
+            method_name
+          )
+
+
+        child_path =
+          File.join(
+            @path,
+            method_name
+          )
+
+
+        if !File.directory?(child_path) &&
+           File.exist?(child_path)
+
+          read(
+            @path,
+            method_name
+          )
+
+        else
+
+          OBFS::Store.new({
+            path: child_path
+          })
+
+        end
+
+      end
+
+    end
+
+
+    # ============================================================
+    # SPECIAL METHODS
+    # ============================================================
+
+
+    # ------------------------------------------------------------
+    # current path
+    #
+    #   obfs._path
+    # ------------------------------------------------------------
+
+    def _path
+      @path
+    end
+
+
+    # ------------------------------------------------------------
+    # directory contents
+    #
+    # Existing behavior preserved:
+    #
+    # - excludes "." and ".."
+    # - includes dot-prefixed entries
+    # - preserves filesystem ordering
+    # - returns nil on failure
+    #
+    #   obfs._index
+    #   obfs._keys
+    # ------------------------------------------------------------
+
+    def _index
+
+      Dir.entries(@path).reject {
+        |k| k == '.' || k == '..'
+      } rescue nil
+
+    end
+
+    alias_method :_keys, :_index
+
+
+    # ------------------------------------------------------------
+    # one-level fuzzy search
+    #
+    # Existing signature and return type preserved:
+    #
+    #   obfs._find(term, records, tolerance)
+    #
+    # Returns an Array<String>, but now actually sorted by
+    # relevance as originally intended.
+    # ------------------------------------------------------------
+
+    def _find(term = '', records = 1000, tolerance = 50)
+
+      term = term.to_s
+
+
+      search_space =
+        Dir.entries(@path).reject {
+          |k| k == '.' || k == '..'
+        } rescue []
+
+
+      results = []
+
+
+      search_space.each do |search_space_term|
+
+        distance =
+          OBFS::Levenshtein.distance(
+            search_space_term,
+            term
+          )
+
+
+        similarity =
+          OBFS::WhiteSimilarity.similarity(
+            search_space_term,
+            term
+          )
+
+
+        if distance <= tolerance &&
+           similarity > 0.0
+
+          results << {
+            name: search_space_term,
+            score: fuzzy_score(
+              term,
+              search_space_term
+            )
+          }
+
+        end
+
+      end
+
+
+      results
+        .sort_by {
+          |result|
+
+          [
+            -result[:score],
+            result[:name].downcase
+          ]
+        }
+        .first(records)
+        .map {
+          |result|
+
+          result[:name]
+        }
+
+    end
+
+
+    # ------------------------------------------------------------
+    # existing direct-child existence check
+    #
+    # Existing behavior preserved.
+    #
+    #   obfs._exist('foo')
+    # ------------------------------------------------------------
+
+    def _exist(term = '')
+
+      exist_space =
+        Dir.entries(@path).reject {
+          |k|
+
+          k != term.to_s ||
+            k == '.' ||
+            k == '..'
+        } rescue nil
+
+
+      if !exist_space.nil?
+
+        if exist_space.length > 0
+          true
+        else
+          false
+        end
+
+      else
+
+        false
+
+      end
+
+    end
+
+
+    # ------------------------------------------------------------
+    # current node existence
+    #
+    #   obfs.foo.bar._exists
+    #   obfs.foo.bar._exists?
+    # ------------------------------------------------------------
+
+    def _exists
+      File.exist?(@path)
+    end
+
+    def _exists?
+      _exists
+    end
+
+
+    # ------------------------------------------------------------
+    # direct-child existence
+    #
+    #   obfs.foo._has('bar')
+    #   obfs.foo._has?('bar')
+    #
+    # Unlike _exist, this uses File.exist? directly instead
+    # of enumerating the current directory.
+    # ------------------------------------------------------------
+
+    def _has(term = '')
+
+      child_name =
+        validate_child_name!(
+          term
+        )
+
+
+      File.exist?(
+        File.join(
+          @path,
+          child_name
+        )
+      )
+
+
+    rescue
+
+      false
+
+    end
+
+
+    def _has?(term = '')
+      _has(term)
+    end
+
+
+    # ------------------------------------------------------------
+    # current node timestamp
+    #
+    #   obfs.foo._timestamp
+    #
+    # Returns nil when the node does not exist or cannot be read.
+    # ------------------------------------------------------------
+
+    def _timestamp
+
+      File.mtime(@path)
+
+
+    rescue
+
+      nil
+
+    end
+
+
+    # ------------------------------------------------------------
+    # recursive fuzzy directory search
+    #
+    #   obfs._search('nginx')
+    #
+    #   obfs.systems._search(
+    #     'nginx certificate',
+    #     {
+    #       recursive: true,
+    #       min_score: 0.6,
+    #       limit: 10
+    #     }
+    #   )
+    #
+    # camelCase minScore is also accepted:
+    #
+    #   {
+    #     minScore: 0.6
+    #   }
+    #
+    # Defaults:
+    #
+    #   recursive: true
+    #   min_score: 0.5
+    #   limit:      unlimited
+    #
+    # Returns:
+    #
+    #   [
+    #     {
+    #       path: "services/nginx",
+    #       score: 1.0
+    #     },
+    #     {
+    #       path: "services/nginx/certificates",
+    #       score: 0.9
+    #     }
+    #   ]
+    #
+    # Search:
+    #
+    # - is scoped to the current Store node
+    # - searches directories only
+    # - searches directory names and relative paths
+    # - does not read file contents
+    # - does not follow symbolic links
+    # - ignores dot-prefixed entries
+    # - returns relevance-sorted results
+    # ------------------------------------------------------------
+
+    def _search(term = '', options = {})
+
+      return [] unless File.directory?(@path)
+
+
+      term =
+        term
+          .to_s
+          .strip
+
+
+      return [] if term.empty?
+
+
+      options = {} unless options.is_a?(Hash)
+
+
+      recursive =
+        search_option(
+          options,
+          [
+            :recursive,
+            'recursive'
+          ],
+          true
+        )
+
+
+      min_score =
+        search_option(
+          options,
+          [
+            :min_score,
+            :minScore,
+            'min_score',
+            'minScore'
+          ],
+          0.5
+        ).to_f
+
+
+      limit =
+        search_option(
+          options,
+          [
+            :limit,
+            'limit'
+          ],
+          nil
+        )
+
+
+      # clamp score to 0.0 - 1.0
+
+      min_score = 0.0 if min_score < 0.0
+      min_score = 1.0 if min_score > 1.0
+
+
+      results = []
+
+
+      search_directories(
+        @path,
+        '',
+        term,
+        recursive,
+        min_score,
+        results
+      )
+
+
+      results.sort_by! do |result|
+
+        [
+          -result[:score],
+          result[:path].downcase
+        ]
+
+      end
+
+
+        unless limit.nil? || (limit.respond_to?(:infinite?) && limit.infinite?)
+
+            begin
+
+                limit =
+                Integer(limit)
+
+            rescue
+
+                return []
+
             end
 
+            return [] if limit <= 0
+
+            results = results.first(limit)
+
+        end
+
+
+      results
+
+    end
+
+
+    private
+
+
+    # ============================================================
+    # FILESYSTEM R/W
+    # ============================================================
+
+
+    # ------------------------------------------------------------
+    # write
+    #
+    # Original behavior intentionally preserved.
+    #
+    # Hashes, Arrays, Strings, Numbers, Booleans, etc. continue
+    # to be JSON serialized into a single file.
+    # ------------------------------------------------------------
+
+    def write(path, filename, data)
+
+      curr_path =
+        File.join(
+          path,
+          filename
+        )
+
+
+      File.write(
+        curr_path,
+        JSON.dump(data)
+      )
+
+    end
+
+
+    # ------------------------------------------------------------
+    # read
+    #
+    # Original behavior intentionally preserved.
+    #
+    # JSON is parsed when possible.
+    # Otherwise raw file contents are returned.
+    # ------------------------------------------------------------
+
+    def read(path, filename)
+
+      curr_path =
+        File.join(
+          path,
+          filename
+        )
+
+
+      content =
+        File.open(
+          curr_path
+        ).read
+
+
+      begin
+
+        JSON.parse(content)
+
+      rescue
+
+        content
+
+      end
+
+    end
+
+
+    # ============================================================
+    # SEARCH
+    # ============================================================
+
+
+    # ------------------------------------------------------------
+    # recursively search directory structure
+    # ------------------------------------------------------------
+
+    def search_directories(
+      path,
+      relative_path,
+      term,
+      recursive,
+      min_score,
+      results
+    )
+
+      entries =
+        Dir.entries(path).reject do |entry|
+
+          entry == '.' ||
+            entry == '..' ||
+            entry.start_with?('.')
+
+        end rescue []
+
+
+      entries.each do |entry|
+
+        full_path =
+          File.join(
+            path,
+            entry
+          )
+
+
+        # do not follow symbolic links
+
+        next if File.symlink?(full_path)
+
+
+        # search directory structure only
+
+        next unless File.directory?(full_path)
+
+
+        child_relative_path =
+
+          if relative_path.empty?
+
+            entry
+
+          else
+
+            File.join(
+              relative_path,
+              entry
+            )
+
+          end
+
+
+        name_score =
+          fuzzy_score(
+            term,
+            entry
+          )
+
+
+        path_score =
+          fuzzy_score(
+            term,
+            child_relative_path
+          )
+
+
+        score =
+          [
+            name_score,
+            path_score
+          ].max
+
+
+        if score >= min_score
+
+          results << {
+            path: child_relative_path,
+            score: score.round(6)
+          }
+
+        end
+
+
+        if recursive
+
+          search_directories(
+            full_path,
+            child_relative_path,
+            term,
+            recursive,
+            min_score,
+            results
+          )
+
+        end
+
+      end
+
+    end
+
+
+    # ------------------------------------------------------------
+    # calculate fuzzy relevance score
+    #
+    # Score range:
+    #
+    #   0.0 - 1.0
+    #
+    # Uses:
+    #
+    # - exact matches
+    # - prefix matches
+    # - substring matches
+    # - token coverage
+    # - existing Levenshtein implementation
+    # - existing WhiteSimilarity implementation
+    #
+    # No additional dependencies required.
+    # ------------------------------------------------------------
+
+    def fuzzy_score(term, candidate)
+
+      query =
+        normalize_search_term(term)
+
+
+      value =
+        normalize_search_term(candidate)
+
+
+      return 0.0 if query.empty? || value.empty?
+
+      return 1.0 if query == value
+
+
+      scores = []
+
+
+      # ----------------------------------------------------------
+      # prefix match
+      # ----------------------------------------------------------
+
+      scores << 0.95 if value.start_with?(query)
+
+
+      # ----------------------------------------------------------
+      # substring match
+      # ----------------------------------------------------------
+
+      scores << 0.90 if value.include?(query)
+
+
+      # ----------------------------------------------------------
+      # token coverage
+      # ----------------------------------------------------------
+
+      query_tokens =
+        query.split(/\s+/)
+
+
+      unless query_tokens.empty?
+
+        matched_tokens =
+          query_tokens.count do |token|
+
+            value.include?(token)
+
+          end
+
+
+        coverage =
+          matched_tokens.to_f /
+          query_tokens.length.to_f
+
+
+        scores << (
+          coverage * 0.85
+        )
+
+      end
+
+
+      # ----------------------------------------------------------
+      # normalized Levenshtein similarity
+      # ----------------------------------------------------------
+
+      max_length =
+        [
+          query.length,
+          value.length
+        ].max
+
+
+      if max_length > 0
+
+        distance =
+          OBFS::Levenshtein.distance(
+            query,
+            value
+          ).to_f
+
+
+        levenshtein_score =
+          1.0 -
+          (
+            distance /
+            max_length.to_f
+          )
+
+
+        levenshtein_score = 0.0 if levenshtein_score < 0.0
+        levenshtein_score = 1.0 if levenshtein_score > 1.0
+
+
+        scores << levenshtein_score
+
+      end
+
+
+      # ----------------------------------------------------------
+      # existing WhiteSimilarity
+      # ----------------------------------------------------------
+
+      begin
+
+        white_score =
+          OBFS::WhiteSimilarity.similarity(
+            query,
+            value
+          ).to_f
+
+
+        # support either:
+        #
+        #   0.0 - 1.0
+        #
+        # or:
+        #
+        #   0 - 100
+        #
+
+        white_score /= 100.0 if white_score > 1.0
+
+
+        white_score = 0.0 if white_score < 0.0
+        white_score = 1.0 if white_score > 1.0
+
+
+        scores << white_score
+
+
+      rescue
+
+        # Remaining scorers are sufficient.
+
+      end
+
+
+      scores.empty? ? 0.0 : scores.max
+
+    end
+
+
+    # ------------------------------------------------------------
+    # normalize text for fuzzy matching
+    #
+    # Examples:
+    #
+    #   "import-scenarios"
+    #       =>
+    #   "import scenarios"
+    #
+    #   "systems/nginx_errors"
+    #       =>
+    #   "systems nginx errors"
+    # ------------------------------------------------------------
+
+    def normalize_search_term(value)
+
+      value
+        .to_s
+        .downcase
+        .gsub(/[\\\/:_\-]+/, ' ')
+        .gsub(/[^a-z0-9\s]/, '')
+        .gsub(/\s+/, ' ')
+        .strip
+
+    end
+
+
+    # ------------------------------------------------------------
+    # retrieve option using symbol/string equivalents
+    #
+    # Presence testing is used rather than || so:
+    #
+    #   recursive: false
+    #
+    # works correctly.
+    # ------------------------------------------------------------
+
+    def search_option(
+      options,
+      keys,
+      default_value
+    )
+
+      keys.each do |key|
+
+        return options[key] if options.key?(key)
+
+      end
+
+
+      default_value
+
     end
 
+
+    # ============================================================
+    # PATH SAFETY
+    # ============================================================
+
+
+    # ------------------------------------------------------------
+    # validates one OBFS object key
+    #
+    # An individual key represents exactly one filesystem node.
+    #
+    # Therefore:
+    #
+    #   obfs['foo']['bar']
+    #
+    # is valid, while:
+    #
+    #   obfs['foo/bar']
+    #   obfs['../foo']
+    #   obfs['foo/../../etc']
+    #   obfs['..\\foo']
+    #
+    # are rejected.
+    #
+    # This prevents escaping the current OBFS hierarchy through
+    # bracket notation or dynamically generated keys.
+    # ------------------------------------------------------------
+
+    def validate_child_name!(name)
+
+      name =
+        name.to_s
+
+
+      if name.empty?
+
+        raise "OBFS key cannot be empty"
+
+      end
+
+
+      if name == '.' ||
+         name == '..' ||
+         name.include?('/') ||
+         name.include?('\\') ||
+         name.include?("\0")
+
+        raise "filesystem traversal is not allowed"
+
+      end
+
+
+      name
+
+    end
+
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: obfs
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Jensel Gatchalian
 bindir: bin
 cert_chain: []
-date: 2021-01-16 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies: []
 description: File-based, object-oriented data store for Ruby
 email: jensel.gatchalian@gmail.com
@@ -37,7 +37,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.20
 specification_version: 4
 summary: OBFS
 test_files: []