obfs 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2651e95cf754b5588ce3890154db176634ee85ee3cf6bc869940b985787552e1
-  data.tar.gz: 32aa77c08d31978cf973acbaef8636a8f0f431f69dd372ec62ae75430944b322
+  metadata.gz: 2a4b8b313bcfac3893da631ea24c90b5cf39f7337e4dd804e922edfa893d4d77
+  data.tar.gz: b7afaac2c2fa61e82e888223dd6473a14dbde609dea0eb67b06d2069bafb164a
 SHA512:
-  metadata.gz: 21072b9fa529f96cc73fd144691344a2fa0b3383c2b55737f36f8b597924c182cb02c6c4f041a4c4d9211d95d831e2af16bfacc953a7c15971543a2ba5826a21
-  data.tar.gz: 4de8c6e75e9a1a14aaea87095dca85296d09913fad9db69669a79e6ce4c961d27742d13e35c2c43225608ceb95ec40ba8bfd7d7674244215257b3e940098c5b4
+  metadata.gz: b782fbfd5d5c740c3256a74b0fb66083d102cc71c59439c673c9a86bc516a438aa63f673d7a609d55d3376fb548421d846345142429b211eeb3e3b304b0edbc6
+  data.tar.gz: 3fdd856e0c0c4d65b593f47893c3a85d8d2a3514a03f28656eebbece06aa5ff22a746c58f9b022b14d761187b0cd5ef7336113912caf82c06c80de4a4881fdce

data/README.md

@@ -0,0 +1,602 @@
+# OBFS
+
+[![Gem Version](https://badge.fury.io/rb/obfs.svg)](https://badge.fury.io/rb/obfs)
+
+File-based, object-oriented data store for Ruby.
+
+OBFS maps recursive Ruby object access directly to the filesystem, allowing data to be addressed using dot notation, bracket notation, or a combination of both.
+
+```ruby
+datastore.users.cat.preferences.theme = "dark"
+
+datastore["users"]["cat"]["preferences"]["theme"]
+# => "dark"
+```
+
+The resulting filesystem structure is:
+
+```text
+users/
+└── cat/
+    └── preferences/
+        └── theme
+```
+
+OBFS also includes filesystem discovery helpers, including direct existence checks, recursive fuzzy directory search, timestamps, and directory indexing. It uses Ruby standard libraries and independent OBFS-owned text algorithms, with no external runtime gem dependencies.
+
+
+## Quickstart
+
+Add OBFS to your `Gemfile`:
+
+```ruby
+gem "obfs"
+```
+
+Require it:
+
+```ruby
+require "obfs"
+```
+
+Create a store:
+
+```ruby
+datastore = OBFS::Store.new
+```
+
+Write data:
+
+```ruby
+datastore.somefile = "some value"
+
+datastore["somefile"] = "some value"
+```
+
+Read data:
+
+```ruby
+datastore.somefile
+
+datastore["somefile"]
+```
+
+Delete data:
+
+```ruby
+datastore.somefile = nil
+
+datastore["somefile"] = nil
+```
+
+Supported values include:
+
+- String
+- Array
+- Hash
+- Integer
+- Float
+- Boolean
+
+
+## Usage
+
+By default, OBFS stores data inside:
+
+```text
+~/.obfs
+```
+
+A custom path can be specified:
+
+```ruby
+datastore = OBFS::Store.new({
+  path: "/some/other/folder"
+})
+```
+
+Paths are recursively created as needed.
+
+For example:
+
+```ruby
+datastore.some.long.path.to.create = "some string"
+```
+
+creates:
+
+```text
+some/
+└── long/
+    └── path/
+        └── to/
+            └── create
+```
+
+The file `create` contains the JSON-serialized value:
+
+```text
+"some string"
+```
+
+Bracket notation can also be used:
+
+```ruby
+datastore["some"]["long"]["path"]["to"]["create"] = "some string"
+```
+
+Dot and bracket notation may be mixed:
+
+```ruby
+datastore.some["long"].path["to"].create = "some string"
+```
+
+Hashes and arrays are serialized as JSON values into leaf files:
+
+```ruby
+datastore.settings = {
+  "theme" => "dark",
+  "notifications" => true
+}
+
+datastore.numbers = [1, 2, 3]
+```
+
+Reading those values returns the corresponding Ruby objects:
+
+```ruby
+datastore.settings
+# => {"theme"=>"dark", "notifications"=>true}
+
+datastore.numbers
+# => [1, 2, 3]
+```
+
+
+## Path Safety
+
+Each OBFS key represents exactly one filesystem node.
+
+Nested paths should therefore be expressed recursively:
+
+```ruby
+datastore["foo"]["bar"]
+```
+
+rather than by embedding filesystem separators:
+
+```ruby
+datastore["foo/bar"]
+```
+
+OBFS rejects keys containing filesystem path separators, null bytes, `.` or `..`.
+
+For example, the following are rejected:
+
+```ruby
+datastore[".."]
+datastore["../foo"]
+datastore["../../etc/passwd"]
+datastore["foo/bar"]
+datastore["..\\Windows"]
+```
+
+This prevents dynamic OBFS keys from traversing outside the intended datastore hierarchy.
+
+
+## Special Methods
+
+### `_path`
+
+Returns the current filesystem path.
+
+```ruby
+datastore.some.data._path
+```
+
+Example:
+
+```text
+/home/user/.obfs/some/data
+```
+
+
+### `_index`
+
+Returns the entries in the current directory.
+
+```ruby
+datastore.some.data._index
+```
+
+Example:
+
+```ruby
+[
+  "foo",
+  "bar",
+  "baz"
+]
+```
+
+
+### `_keys`
+
+Alias for `_index`.
+
+```ruby
+datastore.some.data._keys
+```
+
+
+### `_find`
+
+Performs a fuzzy search against entries in the current directory only.
+
+```ruby
+datastore.some.data._find("some term")
+```
+
+Full signature:
+
+```ruby
+datastore.some.data._find(term, records, tolerance)
+```
+
+Arguments:
+
+- `term` - search term
+- `records` - maximum number of records to return; defaults to `1000`
+- `tolerance` - maximum Levenshtein distance; defaults to `50`
+
+Results are returned as an array of entry names sorted by relevance. Entries must be within the Levenshtein tolerance and have a positive normalized bigram/Dice similarity score. The distance check is case-sensitive; similarity normalizes case, path separators, and whitespace.
+
+Example:
+
+```ruby
+datastore.services._find("nginx")
+```
+
+might return:
+
+```ruby
+[
+  "nginx",
+  "nginx_config",
+  "old_nginx"
+]
+```
+
+`_find` searches only the current directory level.
+
+
+### `_exist`
+
+Checks whether an immediate child with the specified name exists.
+
+```ruby
+datastore.some.data._exist("some term")
+```
+
+Returns:
+
+```ruby
+true
+```
+
+or:
+
+```ruby
+false
+```
+
+This method is retained for compatibility with earlier versions of OBFS.
+
+
+### `_exists`
+
+Checks whether the current OBFS node physically exists.
+
+```ruby
+datastore.some.data._exists
+```
+
+A question-mark alias is also available:
+
+```ruby
+datastore.some.data._exists?
+```
+
+Example:
+
+```ruby
+datastore.services.nginx._exists?
+# => true
+```
+
+
+### `_has`
+
+Checks whether an immediate child exists.
+
+```ruby
+datastore.services._has("nginx")
+```
+
+A question-mark alias is also available:
+
+```ruby
+datastore.services._has?("nginx")
+```
+
+Returns:
+
+```ruby
+true
+```
+
+or:
+
+```ruby
+false
+```
+
+Unlike `_exist`, `_has` performs a direct filesystem existence check rather than enumerating the current directory.
+
+
+### `_timestamp`
+
+Returns the modification time of the current filesystem node.
+
+```ruby
+datastore.services.nginx._timestamp
+```
+
+Returns a Ruby `Time` object when the node exists:
+
+```ruby
+2026-10-04 14:30:00 -0700
+```
+
+or:
+
+```ruby
+nil
+```
+
+if the node does not exist or cannot be read.
+
+
+### `_search`
+
+Performs a fuzzy search against directory names and relative directory paths.
+
+Unlike `_find`, `_search` can recursively search the entire directory hierarchy beneath the current OBFS node.
+
+Basic usage:
+
+```ruby
+datastore._search("nginx")
+```
+
+Example result:
+
+```ruby
+[
+  {
+    path: "systems/services/nginx",
+    score: 1.0
+  },
+  {
+    path: "systems/services/nginx/certificates",
+    score: 0.95
+  }
+]
+```
+
+Search may also be scoped to any recursive OBFS node:
+
+```ruby
+datastore.systems.services._search("nginx")
+```
+
+Options can be supplied using a hash:
+
+```ruby
+datastore._search(
+  "nginx certificate",
+  {
+    recursive: true,
+    min_score: 0.6,
+    limit: 10
+  }
+)
+```
+
+Available options:
+
+- `recursive` - recursively search child directories; defaults to `true`
+- `min_score` - minimum fuzzy relevance score from `0.0` to `1.0`; defaults to `0.5`
+- `limit` - maximum number of results; unlimited by default
+
+`minScore` is also accepted for compatibility with the JavaScript version:
+
+```ruby
+datastore._search(
+  "nginx",
+  {
+    minScore: 0.6
+  }
+)
+```
+
+Search results are sorted from highest to lowest relevance.
+
+`_search`:
+
+- searches directory names
+- searches relative directory paths
+- does not read stored file contents
+- does not follow symbolic links
+- ignores dot-prefixed entries
+- is scoped to the current OBFS node
+
+
+## `_find` vs `_search`
+
+`_find` is intended for lightweight one-level discovery:
+
+```ruby
+datastore.services._find("nginx")
+```
+
+and returns:
+
+```ruby
+[
+  "nginx",
+  "nginx_config"
+]
+```
+
+`_search` is intended for deeper discovery:
+
+```ruby
+datastore._search("nginx certificate")
+```
+
+and returns scored relative paths:
+
+```ruby
+[
+  {
+    path: "systems/services/nginx/certificates",
+    score: 0.95
+  }
+]
+```
+
+
+## Recursive Object Storage
+
+One of the primary goals of OBFS is to allow the filesystem to behave like an arbitrarily recursive Ruby object.
+
+For example:
+
+```ruby
+datastore.projects.example.servers.production.services.nginx.status = "running"
+```
+
+can later be accessed using the same structure:
+
+```ruby
+datastore.projects.example.servers.production.services.nginx.status
+# => "running"
+```
+
+The hierarchy itself is stored using physical directories and files, making the datastore directly inspectable using normal filesystem tools.
+
+
+## Notes
+
+- OBFS uses the filesystem directly as its persistence layer.
+- Intermediate paths are created automatically when writing data.
+- Setting a value to `nil` removes the corresponding file or directory recursively.
+- Existing values are replaced when reassigned.
+- JSON-compatible values are serialized using Ruby's JSON library.
+- Files containing valid JSON are deserialized when read.
+- Non-JSON files are returned as raw text.
+- Fuzzy search uses independent `OBFS::Levenshtein` and `OBFS::StringSimilarity` implementations.
+- No external runtime gem dependencies are required; the Text gem is not needed.
+- No database server is required.
+
+
+## Platform Support
+
+OBFS requires Ruby >= 2.0.0. The updated text algorithms use Ruby 2.0-compatible APIs. Syntax and basic behavior were validated on Ruby 4.0.7 on Linux; this update has not been tested on Ruby 2.0 itself.
+
+Windows and macOS have not been formally tested.
+
+
+## Links
+
+- [RubyGems](https://rubygems.org/gems/obfs)
+- [GitHub](https://github.com/jenselg/obfs-ruby)
+- [JavaScript / Node.js Version](https://github.com/jenselg/obfs)
+
+
+## Text Algorithms
+
+The algorithms are implemented locally in `lib/obfs/levenshtein.rb` and
+`lib/obfs/string_similarity.rb`. Requiring `obfs` loads both automatically.
+
+### `OBFS::Levenshtein.distance`
+
+Calculates unit-cost insertion, deletion, and substitution distance over Unicode
+codepoints. Inputs must support String encoding; Unicode normalization is not
+performed.
+
+```ruby
+OBFS::Levenshtein.distance("kitten", "sitting")
+# => 3
+
+OBFS::Levenshtein.distance("kitten", "sitting", 2)
+# => 2
+```
+
+The optional `max_distance` must be a nonnegative Integer or `nil`. When supplied,
+the result is capped at that maximum, preserving the existing API contract. A
+result equal to the maximum means the actual distance is at least that value.
+
+### `OBFS::StringSimilarity.similarity`
+
+Returns a normalized character-bigram Dice score between `0.0` and `1.0`. It
+normalizes case, path separators (`/`, `\`, `:`, `_`, and `-`), and whitespace.
+Bigrams span the normalized string, including spaces, and repeated bigrams count
+separately. Unicode codepoints are used without Unicode normalization.
+
+```ruby
+OBFS::StringSimilarity.similarity("France", "French")
+# => 0.4
+
+OBFS::StringSimilarity.similarity("nginx_config", "NGINX CONFIG")
+# => 1.0
+```
+
+Equal nonempty normalized strings score `1.0`, including one-character strings.
+Empty inputs score `0.0`; unequal one-character strings score `0.0`.
+
+Store relevance takes the highest score from exact, prefix, substring, token
+coverage, normalized Levenshtein, and Dice matching. `_find` and `_search` retain
+their signatures and result formats, but rankings can change with the new Dice
+scorer.
+
+When upgrading, replace `lib/obfs/white_similarity.rb` with
+`lib/obfs/string_similarity.rb` and update any direct `OBFS::WhiteSimilarity`
+references to `OBFS::StringSimilarity`. The copied Text implementations and
+`text/*` requires are no longer used.
+
+
+## License
+
+### MIT License
+
+Copyright (c) 2021 Jensel Gatchalian <jensel.gatchalian@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/obfs/levenshtein.rb

@@ -0,0 +1,41 @@
+module OBFS
+  module Levenshtein
+    extend self
+
+    # Unit-cost edit distance over Unicode codepoints, without normalization.
+    # With a maximum, return the exact distance capped at that maximum.
+    def distance(str1, str2, max_distance = nil)
+      unless max_distance.nil? ||
+             (max_distance.is_a?(Integer) && max_distance >= 0)
+        raise ArgumentError, 'max_distance must be a nonnegative Integer or nil'
+      end
+      return 0 if max_distance == 0
+
+      left = str1.encode('UTF-8').each_codepoint.to_a
+      right = str2.encode('UTF-8').each_codepoint.to_a
+      return 0 if left == right
+
+      # The shorter input determines the width of the two working rows.
+      left, right = right, left if left.length < right.length
+      if max_distance && left.length - right.length >= max_distance
+        return max_distance
+      end
+      return left.length if right.empty?
+
+      previous = (0..right.length).to_a
+      left.each_with_index do |character, row|
+        current = [row + 1]
+        right.each_with_index do |other, column|
+          current << [current[column] + 1,
+                      previous[column + 1] + 1,
+                      previous[column] + (character == other ? 0 : 1)].min
+        end
+        # Every path to the final cell crosses this row; costs cannot decrease.
+        return max_distance if max_distance && current.min >= max_distance
+        previous = current
+      end
+
+      max_distance ? [previous.last, max_distance].min : previous.last
+    end
+  end
+end