lora-ruby 0.2.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1070b9b3c1c0f6417eb4fec39a875ab9a966cf7dc9679608e79817129df050e
+  data.tar.gz: ab88ef302defb70eca748d401d558f9136f08792addb462863d2cfe42a7da4bb
+SHA512:
+  metadata.gz: 2e30841ef82bea511be9d40974175638995a2981117926b969bc09565c957044f4a344b635393c4f3998810affa889c9323c5761ad0efa4cb7eaa5202eac1f1d
+  data.tar.gz: 3fd3df27863a1c38432dcc75215248dac2dce75c65e3b6b57b81b08de33c54ecf7a53804c5bfb5c0a7ccf64a1fd36b22c7652ea6296994afd0c7a912f1121b30

data/LICENSE

@@ -0,0 +1,87 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             LoraDB, Inc.
+Licensed Work:        LoraDB
+Change Date:          2029-04-19
+Change License:       Apache License, Version 2.0
+
+Additional Use Grant: You may use, copy, modify, create derivative works of,
+                      distribute, and make production use of the Licensed Work
+                      for internal business purposes and non-production
+                      purposes, provided that you do not use the Licensed Work
+                      to offer, operate, or make available a database-as-a-
+                      service, hosted API, managed database platform, or any
+                      substantially similar hosted service for third parties.
+
+                      The Additional Use Grant does not permit using the
+                      Licensed Work to provide a commercial or non-commercial
+                      hosted service that allows third parties to access LoraDB
+                      functionality, including as part of a competing managed
+                      database platform, backend-as-a-service, application
+                      platform, developer platform, or resale offering.
+
+Business Source License
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+3. To specify a Change Date.
+4. Not to modify this License in any other way.

data/README.md

@@ -0,0 +1,190 @@
+# lora-ruby
+
+Ruby bindings for the [Lora](../../README.md) in-memory graph engine.
+Ships a native extension built with [Magnus](https://github.com/matsadler/magnus)
+on top of [`rb-sys`](https://github.com/oxidize-rb/rb-sys) so the Rust
+engine runs in-process — no separate server, no socket hop.
+
+> **Status:** prototype / feasibility check. Published source gem on
+> RubyGems; precompiled platform gems are built for the supported
+> targets (see "Release" below).
+
+## Install
+
+```bash
+gem install lora-ruby
+# or in a Gemfile
+gem "lora-ruby"
+```
+
+`require "lora_ruby"` loads the native extension from
+`lib/lora_ruby/lora_ruby.{so,bundle,dll}`. If a precompiled gem for
+your platform exists on RubyGems, the install is a direct download; if
+not, the source gem is built locally with `cargo` and a stable Rust
+toolchain (1.87+).
+
+## Usage
+
+```ruby
+require "lora_ruby"
+
+db = LoraRuby::Database.create
+
+db.execute("CREATE (:Person {name: $n, age: $a})", { n: "Alice", a: 30 })
+
+result = db.execute("MATCH (n:Person) RETURN n")
+result["rows"].each do |row|
+  n = row["n"]
+  puts n["properties"]["name"] if LoraRuby.node?(n)
+end
+```
+
+### Params
+
+`execute` accepts a second argument — either `nil` or a `Hash` keyed by
+parameter name (`String` or `Symbol`). Values can be any of:
+
+- `nil`, `true`, `false`, `Integer`, `Float`, `String`, `Symbol` (stringified)
+- `Array` of the above (recursive)
+- `Hash` keyed by `String`/`Symbol` with the above values (recursive)
+- Tagged temporal/spatial Hashes produced by the constructors below
+
+## Module shape — why `LoraRuby::Database`?
+
+Three reasonable options were considered:
+
+- `LoraRuby::Database` — matches the gem filename; scope is obvious.
+- `LoraDB::Database` — matches the brand (loradb.com).
+- `Lora::Database` — shortest, but collides with arbitrary "lora" apps.
+
+We went with **`LoraRuby::Database`** for symmetry with the Python
+binding's `lora_python.Database` and because it mirrors the
+`require "lora_ruby"` path exactly. The gem name on RubyGems is
+`lora-ruby` (hyphen); the Ruby constant follows Rubocop convention
+(CamelCase, no hyphen).
+
+## Public API
+
+```ruby
+LoraRuby::Database.create            # -> Database
+LoraRuby::Database.new               # -> Database  (alias of .create)
+
+db.execute(query, params = nil)       # -> { "columns" => [...], "rows" => [...] }
+db.clear                              # -> nil
+db.node_count                         # -> Integer
+db.relationship_count                 # -> Integer
+
+LoraRuby::VERSION                    # gem version
+```
+
+Result shape:
+
+```ruby
+{
+  "columns" => ["name"],
+  "rows"    => [{ "name" => "Alice" }],
+}
+```
+
+Hash keys on the output are always **strings**, matching the `lora-node`,
+`lora-wasm`, and `lora-python` bindings. Input Hashes accept either
+symbol or string keys — both work for param names and for tagged
+constructor Hashes like `point`/`date`/...
+
+## Typed value model
+
+Identical contract to the other bindings:
+
+| Ruby shape                                                              | Lora value      |
+|-------------------------------------------------------------------------|-------------------|
+| `nil`, `true`/`false`, `Integer`, `Float`, `String`                      | scalars           |
+| `Array`, `Hash`                                                          | collections       |
+| `{"kind" => "node", "id", "labels", "properties"}`                       | node              |
+| `{"kind" => "relationship", "id", …}`                                    | relationship      |
+| `{"kind" => "path", "nodes" => [...], "rels" => [...]}`                  | path              |
+| `{"kind" => "date", "iso" => "YYYY-MM-DD"}` (and `time`, …)              | temporal          |
+| point Hashes (below)                                                    | point             |
+
+Points are returned as Hashes keyed on their CRS:
+
+| SRID | Hash                                                                                                       |
+|------|------------------------------------------------------------------------------------------------------------|
+| 7203 | `{"kind"=>"point","srid"=>7203,"crs"=>"cartesian","x","y"}`                                                |
+| 9157 | `{"kind"=>"point","srid"=>9157,"crs"=>"cartesian-3D","x","y","z"}`                                         |
+| 4326 | `{"kind"=>"point","srid"=>4326,"crs"=>"WGS-84-2D","x","y","longitude","latitude"}`                         |
+| 4979 | `{"kind"=>"point","srid"=>4979,"crs"=>"WGS-84-3D","x","y","z","longitude","latitude","height"}`            |
+
+### Constructors and guards
+
+Re-exported on both `LoraRuby` and `LoraRuby::Types`:
+
+- Constructors: `date`, `time`, `localtime`, `datetime`,
+  `localdatetime`, `duration`, `cartesian`, `cartesian_3d`, `wgs84`,
+  `wgs84_3d`.
+- Guards: `node?`, `relationship?`, `path?`, `point?`, `temporal?`.
+
+```ruby
+db.execute(
+  "CREATE (:Event {on: $d, at: $c})",
+  { d: LoraRuby.date("2025-03-14"), c: LoraRuby.cartesian(1.5, 2.5) },
+)
+```
+
+## Errors
+
+- `LoraRuby::Error` — base class (extends `StandardError`).
+- `LoraRuby::QueryError` — parse / analyze / execute failure.
+- `LoraRuby::InvalidParamsError` — a parameter value couldn't be mapped.
+
+## Concurrency (GVL release)
+
+`Database#execute` calls `rb_thread_call_without_gvl`, so other Ruby
+threads run while the engine is busy. Concurrent queries against the
+same `Database` serialise on an internal `Mutex`; parallel queries
+against **different** `Database` instances have no shared state.
+
+The engine has no cancellation hook, so we pass a `NULL` unblock
+function. A thread interrupted mid-query (`Thread#kill`) will observe
+the interrupt **after** the current query finishes. Keep queries short
+if you rely on cooperative cancellation.
+
+## Local development
+
+```bash
+cd crates/lora-ruby
+bundle install
+bundle exec rake compile        # cargo build → lib/lora_ruby/lora_ruby.<ext>
+bundle exec rake test           # minitest
+bundle exec rake build          # pkg/lora-ruby-<version>.gem
+```
+
+`rake compile` drives `cargo` through `rb_sys/extensiontask`; it is
+what `gem install` runs on end-user machines that don't have a
+precompiled platform gem.
+
+## Architecture
+
+```
+lora-database (Rust, embedded)
+   └── crates/lora-ruby/                (gem root + cargo crate)
+          ├── Cargo.toml                 Rust workspace member
+          ├── extconf.rb                 rb-sys / mkmf entry point
+          ├── src/lib.rs                 <- Magnus / rb-sys bindings
+          └── lib/lora_ruby/
+                 ├── lora_ruby.<ext>      (native, built by rake compile)
+                 ├── types.rb             tagged-dict constructors + guards
+                 └── version.rb           gem version
+```
+
+rb-sys' convention keeps `Cargo.toml` and `extconf.rb` side by side so
+the cargo manifest directory IS the gem root. That makes the crate
+a first-class Cargo workspace member (shared `Cargo.lock`,
+`target/`, `cargo check --workspace` coverage) without a nested
+`ext/<name>/` directory.
+
+## Release
+
+Source gem is always built. Precompiled platform gems are emitted via
+`rb_sys/cross` for `{x86_64,aarch64}-linux`, `{x86_64,arm64}-darwin`, and
+`x64-mingw-ucrt`. See `.github/workflows/packages-release.yml` (Ruby
+section) and `RELEASING.md`.

data/lib/lora_ruby/types.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module LoraRuby
+  # Shared value model — aligned with the `LoraValue` contract used by
+  # `lora-node`, `lora-wasm`, and `lora-python`.
+  #
+  # - Scalars pass through as Ruby natives (`nil`, `true`, `false`,
+  #   `Integer`, `Float`, `String`).
+  # - Lists and maps come back as `Array` / `Hash` (string keys).
+  # - Graph, temporal, and spatial values come back as plain `Hash`es
+  #   with a `"kind"` discriminator.
+  #
+  # If you want to narrow a value explicitly, use the `node?` / `point?`
+  # / `temporal?` helpers below.
+  module Types
+    SRID_CARTESIAN_2D  = 7203
+    SRID_CARTESIAN_3D  = 9157
+    SRID_WGS84_2D      = 4326
+    SRID_WGS84_3D      = 4979
+
+    CRS_CARTESIAN_2D   = "cartesian"
+    CRS_CARTESIAN_3D   = "cartesian-3D"
+    CRS_WGS84_2D       = "WGS-84-2D"
+    CRS_WGS84_3D       = "WGS-84-3D"
+
+    TEMPORAL_KINDS = %w[date time localtime datetime localdatetime duration].freeze
+
+    VECTOR_COORD_TYPES = %w[FLOAT64 FLOAT32 INTEGER INTEGER32 INTEGER16 INTEGER8].freeze
+
+    module_function
+
+    # ------------------------------------------------------------------
+    # Temporal constructors — ISO-8601 tagged Hashes. The native
+    # extension normalises + validates these on the way into the engine;
+    # invalid ISO strings raise `LoraRuby::InvalidParamsError`.
+    # ------------------------------------------------------------------
+
+    def date(iso)          = { "kind" => "date",          "iso" => iso }
+    def time(iso)          = { "kind" => "time",          "iso" => iso }
+    def localtime(iso)     = { "kind" => "localtime",     "iso" => iso }
+    def datetime(iso)      = { "kind" => "datetime",      "iso" => iso }
+    def localdatetime(iso) = { "kind" => "localdatetime", "iso" => iso }
+    def duration(iso)      = { "kind" => "duration",      "iso" => iso }
+
+    # ------------------------------------------------------------------
+    # Vector constructor — returns the canonical tagged Hash that the
+    # engine accepts as a VECTOR parameter and emits on return.
+    # ------------------------------------------------------------------
+
+    def vector(values, dimension, coordinate_type)
+      {
+        "kind"           => "vector",
+        "dimension"      => dimension,
+        "coordinateType" => coordinate_type.to_s,
+        "values"         => values.dup,
+      }
+    end
+
+    # ------------------------------------------------------------------
+    # Spatial constructors — mirrors lora_python.cartesian / wgs84.
+    # `cartesian(1, 2)` returns a 2D cartesian point; use `cartesian_3d`
+    # for the 3D variant. WGS-84 variants carry `longitude` / `latitude`
+    # aliases alongside `x` / `y` so result-side consumers can read
+    # either without conversion.
+    # ------------------------------------------------------------------
+
+    def cartesian(x, y)
+      {
+        "kind" => "point",
+        "srid" => SRID_CARTESIAN_2D,
+        "crs"  => CRS_CARTESIAN_2D,
+        "x"    => x.to_f,
+        "y"    => y.to_f,
+      }
+    end
+
+    def cartesian_3d(x, y, z)
+      {
+        "kind" => "point",
+        "srid" => SRID_CARTESIAN_3D,
+        "crs"  => CRS_CARTESIAN_3D,
+        "x"    => x.to_f,
+        "y"    => y.to_f,
+        "z"    => z.to_f,
+      }
+    end
+
+    def wgs84(longitude, latitude)
+      {
+        "kind"      => "point",
+        "srid"      => SRID_WGS84_2D,
+        "crs"       => CRS_WGS84_2D,
+        "x"         => longitude.to_f,
+        "y"         => latitude.to_f,
+        "longitude" => longitude.to_f,
+        "latitude"  => latitude.to_f,
+      }
+    end
+
+    def wgs84_3d(longitude, latitude, height)
+      {
+        "kind"      => "point",
+        "srid"      => SRID_WGS84_3D,
+        "crs"       => CRS_WGS84_3D,
+        "x"         => longitude.to_f,
+        "y"         => latitude.to_f,
+        "z"         => height.to_f,
+        "longitude" => longitude.to_f,
+        "latitude"  => latitude.to_f,
+        "height"    => height.to_f,
+      }
+    end
+
+    # ------------------------------------------------------------------
+    # Guards — duck-typed narrowing helpers. Accept symbol-keyed and
+    # string-keyed Hashes because that's what callers might build up
+    # manually (the native extension always emits string keys).
+    # ------------------------------------------------------------------
+
+    def node?(v)         = tagged?(v, "node")
+    def relationship?(v) = tagged?(v, "relationship")
+    def path?(v)         = tagged?(v, "path")
+    def point?(v)        = tagged?(v, "point")
+    def vector?(v)       = tagged?(v, "vector")
+
+    def temporal?(v)
+      return false unless v.is_a?(Hash)
+      TEMPORAL_KINDS.include?(kind_of(v))
+    end
+
+    def tagged?(v, expected)
+      return false unless v.is_a?(Hash)
+      kind_of(v) == expected
+    end
+
+    def kind_of(hash)
+      hash["kind"] || hash[:kind]
+    end
+  end
+end

data/lib/lora_ruby/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LoraRuby
+  # Gem version — kept in lockstep with the workspace Cargo.toml version
+  # by `scripts/sync-versions.mjs`. The native extension also defines
+  # `LoraRuby::VERSION` (from Cargo's `CARGO_PKG_VERSION`); we pre-seed
+  # the constant here so `require "lora_ruby/version"` works during
+  # `gem build` / `bundle install` before the `.so` has been compiled.
+  #
+  # Guard against redefinition so re-requiring this file (or loading
+  # both paths) doesn't emit a "warning: already initialized constant"
+  # when the native extension loads second with the identical value.
+  VERSION = "0.2.0" unless const_defined?(:VERSION)
+end

data/lib/lora_ruby.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Public entry point for the gem. Users `require "lora_ruby"` which
+# loads the native extension and re-exports the public API.
+#
+#   require "lora_ruby"
+#
+#   db = LoraRuby::Database.create
+#   db.execute("CREATE (:Person {name: $n})", { n: "Alice" })
+#   result = db.execute("MATCH (n:Person) RETURN n.name AS name")
+#   result["rows"] # => [{"name" => "Alice"}]
+
+require_relative "lora_ruby/version"
+
+# Load the native extension. rb-sys builds it under the gem's extension
+# directory and installs it to lib/lora_ruby/lora_ruby.{so,bundle,dll}
+# from extconf.rb's create_rust_makefile("lora_ruby/lora_ruby").
+require "lora_ruby/lora_ruby"
+
+require_relative "lora_ruby/types"
+
+module LoraRuby
+  # Top-level sugar so callers can write `LoraRuby.cartesian(...)`
+  # without having to say `LoraRuby::Types.cartesian(...)`. Same
+  # trade-off `lora_python.types` makes.
+  #
+  # We explicitly re-export each method rather than `extend Types`
+  # because `Types`' methods are declared with `module_function`,
+  # which makes them public module methods on `Types` itself but
+  # private instance methods — extending would copy them over as
+  # private singletons on `LoraRuby`, which isn't the intended UX.
+  %i[
+    date time localtime datetime localdatetime duration
+    cartesian cartesian_3d wgs84 wgs84_3d
+    vector
+    node? relationship? path? point? temporal? vector?
+  ].each do |m|
+    define_singleton_method(m) do |*args, **kwargs|
+      if kwargs.empty?
+        Types.public_send(m, *args)
+      else
+        Types.public_send(m, *args, **kwargs)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: lora-ruby
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x86_64-linux
+authors:
+- LoraDB, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !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.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+description: Ruby bindings for the Lora in-memory graph database. Exposes the embedded
+  Rust engine as a native extension via Magnus/rb-sys, so queries run in-process without
+  a separate server.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/lora_ruby.rb
+- lib/lora_ruby/3.1/lora_ruby.so
+- lib/lora_ruby/3.2/lora_ruby.so
+- lib/lora_ruby/3.3/lora_ruby.so
+- lib/lora_ruby/types.rb
+- lib/lora_ruby/version.rb
+homepage: https://github.com/lora-db/lora
+licenses:
+- BUSL-1.1
+metadata:
+  homepage_uri: https://github.com/lora-db/lora
+  source_code_uri: https://github.com/lora-db/lora/tree/main/crates/lora-ruby
+  bug_tracker_uri: https://github.com/lora-db/lora/issues
+  documentation_uri: https://github.com/lora-db/lora/blob/main/crates/lora-ruby/README.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.4.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for the Lora in-memory graph database
+test_files: []