grumlin 0.22.4 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 512af99a3613024d7ea0a4837359fae0f54d0a8cbe1077b5084dc9f5b0136143
-  data.tar.gz: ef0ba0abdcc269b1873e81b30fd08fce1647b31856f75d6652af67151fc402f4
+  metadata.gz: e5a4223c6fde72d3f4ce23f3da0081a816f395a070d8737d9915f15b166c9721
+  data.tar.gz: 8c95dcb15d4f55741cc370298e1e763427858908abebaec33f945e404d3a6fa3
 SHA512:
-  metadata.gz: 881de04b1163b74f27a6b890d3a43e16deaa2ab05f553c5bb567af20c689dc78fc5fed4cd81a33803ab3ed37f19be721f71e49062bcb89fa318370c5926ed20f
-  data.tar.gz: e26aad07bc0e3f8f59ca06ed2bb0875b3cc499db7e3982e1617a28da4995a60c8b68dceb6666379fa36289cbe4fa3c7a621c8a72509e7e8fbe7c7f504fcc7ebc
+  metadata.gz: 69162f44551c45c0898ffa0c3650cee448a155d1950de5ea0a2a4b570c1b2b41612f3b97bd063f88f683af5fad3c18d4b874b96392a30334c77ab0e1fb1fd226
+  data.tar.gz: 1fdb7d10a84da7d8c8173e2b0edb0f5b0f913fb0418fce59bb92d28de9c2e9a1743b89eca1f0ed8495b4d0519d2068c2314e9f17f23b77a4297e080512ace082

data/.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/.rubocop.yml

@@ -65,10 +65,6 @@ RSpec/DescribeClass:
 RSpec/MultipleMemoizedHelpers:
   Max: 7
 
-Style/WordArray:
-  Exclude:
-    - spec/**/*_spec.rb
-
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -83,9 +79,13 @@ Style/Documentation:
 Style/MultilineBlockChain:
   Enabled: false
 
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+  Exclude:
+    - spec/**/*_spec.rb
 
-# TODO:
-# Style/SymbolArray:
-#   EnforcedStyle: brackets
-# Style/WordArray:
-#   EnforcedStyle: brackets
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    grumlin (0.22.4)
+    grumlin (1.0.0.rc1)
       async-pool (~> 0.3)
       async-websocket (>= 0.19, < 0.20)
+      ibsciss-middleware (~> 0.4.0)
       oj (~> 3.13)
       retryable (~> 3.0)
       zeitwerk (~> 2.6)
@@ -21,7 +22,7 @@ GEM
       console (~> 1.10)
       nio4r (~> 2.3)
       timers (~> 4.1)
-    async-http (0.59.1)
+    async-http (0.59.2)
       async (>= 1.25)
       async-io (>= 1.28)
       async-pool (>= 0.2)
@@ -29,9 +30,9 @@ GEM
       protocol-http1 (~> 0.14.0)
       protocol-http2 (~> 0.14.0)
       traces (>= 0.4.0)
-    async-io (1.33.0)
+    async-io (1.34.0)
       async
-    async-pool (0.3.11)
+    async-pool (0.3.12)
       async (>= 1.25)
     async-rspec (1.16.1)
       rspec (~> 3.0)
@@ -57,6 +58,7 @@ GEM
     fiber-local (1.0.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
+    ibsciss-middleware (0.4.2)
     iniparse (1.5.0)
     jaro_winkler (1.5.4)
     json (2.6.2)
@@ -78,8 +80,8 @@ GEM
     parser (3.1.2.1)
       ast (~> 2.4.1)
     protocol-hpack (1.4.2)
-    protocol-http (0.23.5)
-    protocol-http1 (0.14.4)
+    protocol-http (0.23.12)
+    protocol-http1 (0.14.6)
       protocol-http (~> 0.22)
     protocol-http2 (0.14.2)
       protocol-hpack (~> 1.4)
@@ -154,8 +156,8 @@ GEM
       yard (~> 0.9, >= 0.9.24)
     thor (1.2.1)
     tilt (2.0.11)
-    timers (4.3.3)
-    traces (0.6.1)
+    timers (4.3.4)
+    traces (0.7.0)
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.2.0)

data/README.md

@@ -82,116 +82,11 @@ Current differences between providers:
 
 **Warning**: Not all steps and expressions defined in the reference documentation are supported.
 
-#### Sugar
-
-Grumlin provides an easy to use module called `Grumlin::Sugar`. Once included in your class it injects some useful
-constants and methods turning your class into an entrypoint for traversals with pure gremlin experience.
-
-```ruby
-class MyRepository
-  include Grumlin::Sugar
-  
-  def nodes(property1:, property2:)
-    g.V()
-      .has(T.label, "node")
-      .has(:property1, property1)
-      .has(:property2, property2)
-      .order.by(:property3, Order.asc).limit(10)
-      .toList
-  end
-end
-```
-
-#### Shortcuts
-
-**Shortcuts** is a way to share and organize gremlin code. They let developers define their own steps consisting of
-sequences of standard gremlin steps, other shortcuts and even add new initially unsupported by Grumlin steps.
-Remember ActiveRecord scopes? Shortcuts are very similar.
-
-**Important**: if a shortcut's name matches a name of a method defined on the wrapped object, this shortcut will be
-be ignored because methods have higher priority.
-
-Shortcuts are designed to be used with `Grumlin::Repository` but still can be used separately, with `Grumlin::Sugar`
-for example.
-
-**Defining**:
-```ruby
-
-# Defining shortcuts
-class ColorShortcut
-  extend Grumlin::Shortcuts
-
-  # Custom step
-  shortcut :hasColor do |color|
-    has(:color, color)
-  end
-end
-
-class ChooseShortcut
-  extend Grumlin::Shortcuts
-
-  # Standard Gremlin step
-  shortcut :choose do |*args|
-    step(:choose, *args)
-  end
-end
-
-class AllShortcuts
-  extend Grumlin::Shortcuts
-
-  # Adding shortcuts from other modules
-  shortcuts_from ColorShortcut
-  shortcuts_from ChooseShortcut
-end
-```
-
-**Using with Grumlin::Sugar**:
-```ruby
-class MyRepository
-  include Grumlin::Sugar
-  extend Grumlin::Shortcuts
-
-  shortcuts_from AllShortcuts
-
-  # Wrapping a traversal
-  def red_triangles
-    g(self.class.shortcuts).V.hasLabel(:triangle)
-       .hasColor("red")
-       .toList
-  end
-
-  # Wrapping _
-  def something_else
-    g(self.class.shortcuts).V.hasColor("red")
-       .repeat(__(self.class.shortcuts))
-       .out(:has)
-       .hasColor("blue")
-       .toList
-  end
-end
-```
-
-##### Overriding standard steps and shortcuts
-
-Sometimes it may be useful to override standard steps. Grumlin does not allow it by default, but one
-is still able to override standard steps if they know what they are doing:
-
-```ruby
-shortcut :addV, override: true do |label|
-  super(label).property(:default, :value)
-end
-```
-
-This will create a new shortcut that overrides the standard step `addV` and adds default properties to all vertices
-created by the repository that uses this shortcut.
-
-Shortcuts also can be overridden, but super() is not available.
-
 #### Grumlin::Repository
-`Grumlin::Repository` combines functionality of `Grumlin::Sugar` and `Grumlin::Shortcuts` as well as adds a few useful
-shortcuts to make gremlin code more rubyish. Can be used as a drop in replacement for `Grumlin::Sugar`. Remember that
-`Grumlin::Sugar` needs to be included, but `Grumlin::Repository` - extended. **Classes extending `Grumlin::Repository`
-or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts 
+`Grumlin::Repository` - is a starting point for all traversals. It provides easy access to `g`, `__` and usual gremlin
+expressions for you class. It has support for defining your own shortcuts and is even shipped with a couple of useful
+shortcuts to make gremlin code more rubyish. **Classes extending `Grumlin::Repository`
+or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts
 defined in the ancestor.
 
 **Definition**
@@ -199,8 +94,8 @@ defined in the ancestor.
 ```ruby
 class MyRepository
   extend Grumlin::Repository
-
-  # Repository supports all Grumlin::Shortcut and Grumlin::Sugar features.
+  # read_only! - forbids mutating queries for this repository. May be useful for separation reads and writes
+  
   # It can add shortcuts from another repository or a shortcuts module
   shortcuts_from ChooseShortcut
   
@@ -252,13 +147,13 @@ Each `return_mode` is mapped to a particular termination step:
 - `drop_in_batches(traversal, batch_size: 10_000)`
 
 and a few methods that emulate upserts:
-- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)` 
+- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)`
 - `upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)`
 - `upsert_edges(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
 - `upsert_vertices(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
 
 All of them support 3 different modes for error handling: `:retry`, `:ignore` and `:raise`. Retry mode is implemented
-with [retryable](https://github.com/nfedyashev/retryable). **params will be merged to the default config for upserts 
+with [retryable](https://github.com/nfedyashev/retryable). **params will be merged to the default config for upserts
 and passed to `Retryable.retryable`. In case if you want to modify retryable behaviour you are to do so.
 
 If you want to use these methods inside a transaction simply pass your `gtx` as `start` parameter:
@@ -270,7 +165,7 @@ end
 
 If you don't want to define you own repository, simply use
 
-`Grumlin::Repository.new` returns an instance of an anonymous class extending `Grumlin::Repository`. 
+`Grumlin::Repository.new` returns an instance of an anonymous class extending `Grumlin::Repository`.
 
 **Usage**
 
@@ -295,6 +190,70 @@ it may be useful for debugging. Note that one needs to call a termination step m
 
 method will return profiling data of the results.
 
+#### Shortcuts
+
+**Shortcuts** is a way to share and organize gremlin code. They let developers define their own steps consisting of
+sequences of standard gremlin steps, other shortcuts and even add new initially unsupported by Grumlin steps.
+Remember ActiveRecord scopes? Shortcuts are very similar.
+
+**Important**: if a shortcut's name matches a name of a method defined on the wrapped object, this shortcut will be
+be ignored because methods have higher priority.
+
+**Defining**:
+```ruby
+
+# Defining shortcuts
+class ColorShortcut
+  extend Grumlin::Shortcuts
+
+  # Custom step
+  shortcut :hasColor do |color|
+    has(:color, color)
+  end
+end
+
+class ChooseShortcut
+  extend Grumlin::Shortcuts
+
+  # Standard Gremlin step
+  shortcut :choose do |*args|
+    step(:choose, *args)
+  end
+end
+
+class AllShortcuts
+  extend Grumlin::Shortcuts
+
+  # Adding shortcuts from other modules
+  shortcuts_from ColorShortcut
+  shortcuts_from ChooseShortcut
+end
+```
+
+##### Overriding standard steps and shortcuts
+
+Sometimes it may be useful to override standard steps. Grumlin does not allow it by default, but one
+is still able to override standard steps if they know what they are doing:
+
+```ruby
+shortcut :addV, override: true do |label|
+  super(label).property(:default, :value)
+end
+```
+
+This will create a new shortcut that overrides the standard step `addV` and adds default properties to all vertices
+created by the repository that uses this shortcut.
+
+Shortcuts also can be overridden, but super() is not available.
+
+##### Middlewares
+
+Middlewares can be used to perform certain actions before and after every query made by `Grumlin`. It can be useful for
+measuring query execution time or performing some modification or validation to the query before it reaches the server or
+modify the response before client gets it.
+
+See [doc/middlewares.md](doc/middlewares.md) for more info and examples.
+
 #### Transactions
 
 Since 0.22.0 `Grumlin` supports transactions when working with providers that supports them:
@@ -315,41 +274,43 @@ end # commits automatically
 
 #### IRB
 
-An example of how to start an IRB session with support for executing gremlin queries:
-
-```ruby
-Async do
-  include Grumlin::Sugar
-
-  IRB.start
-ensure
-  Grumlin.close
-end
-```
-
-Please check out [bin/console](bin/console) for full source. A similar trick may be applied to PRY.
+Please check out [bin/console](bin/console) for inspiration. A similar trick may be applied to PRY.
 
 #### Rails console
 
 In order to make it possible to execute gremlin queries from the rails console you need to define
-a custom console class. It should look somehow like
+a custom console class. It should look somewhat like
 
 ```ruby
-class MyRailsConsole
-  def self.start
+class Async::RailsConsole
+  extend Grumlin::Repository
+
+  def start
+    self.class.shortcuts_from Shortcuts::Content
+
     IRB::WorkSpace.prepend(Rails::Console::BacktraceCleaner)
     IRB::ExtendCommandBundle.include(Rails::ConsoleMethods)
 
-    Async do
-      include Grumlin::Sugar
+    IRB.setup(binding.source_location[0], argv: [])
+    workspace = IRB::WorkSpace.new(binding)
+
+    begin
+      Async do
+        IRB::Irb.new(workspace).run(IRB.conf)
+      ensure
+        Grumlin.close
+      end
+    rescue StandardError, Interrupt, Async::Stop, IRB::Abort
+      retry
+    end
+  end
 
-      IRB.setup(binding.source_location[0], argv: [])
-      workspace = IRB::WorkSpace.new(binding)
+  def inspect
+    'main'
+  end
 
-      IRB::Irb.new(workspace).run(IRB.conf)
-    ensure
-      Grumlin.close
-    end
+  def to_s
+    inspect
   end
 end
 ```
@@ -373,13 +334,13 @@ require 'async/rspec'
 require require "grumlin/test/rspec"
 ...
 config.include_context(Async::RSpec::Reactor) # Runs async reactor
-config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects sugar and makes sure client is closed after every test
+config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects `g`, `__` and expressions, makes sure client is closed after every test
 config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
 ...
 ```
 
-It is highly recommended to use `Grumlin::Sugar` or `Grumlin::Repository` and not trying to use lower level APIs
-as they are subject to change.
+It is highly recommended to use `Grumlin::Repository` and not trying to use lower level APIs as they are subject to 
+change.
 
 ## Development
 

data/Rakefile

@@ -9,7 +9,7 @@ require "rubocop/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[rubocop spec]
+task default: [:rubocop, :spec]
 
 namespace :definitions do
   desc "Format definitions.yml"

data/bin/console

@@ -13,10 +13,25 @@ Grumlin.configure do |config|
   config.url = ENV.fetch("GREMLIN_URL", "ws://localhost:8182/gremlin")
 end
 
-Async do
-  include Grumlin::Sugar
+class Repository
+  extend Grumlin::Repository
+
+  def start_irb
+    IRB.setup(nil)
+    IRB.conf[:PROMPT][:DEFAULT] = { PROMPT_I: "%N(main):%03n:%i> ",
+                                    PROMPT_N: "%N(main):%03n:%i> ",
+                                    PROMPT_S: "%N(main):%03n:%i%l ",
+                                    PROMPT_C: "%N(main):%03n:%i* ",
+                                    RETURN: "=> %s\n" }
+    workspace = IRB::WorkSpace.new(binding)
+    irb = IRB::Irb.new(workspace)
+    IRB.conf[:MAIN_CONTEXT] = irb.context
+    irb.eval_input
+  end
+end
 
-  IRB.start
+Async do
+  Repository.new.start_irb
 ensure
   Grumlin.close
 end

data/doc/middlewares.md

@@ -0,0 +1,97 @@
+# Middlewares
+
+Every single query performed by `Grumlin` goes through a stack of middlewares just like every single request in Rails 
+or many other web frameworks. `Grumlin` ships with a set of middlewares, each one performs some part of the query
+execution process:
+
+- `Middlewares::SerializeToSteps` - converts a `Step` into `Steps`
+- `Middlewares::ApplyShortcuts` - applies shortcuts to `Steps`
+- `Middlewares::SerializeToBytecode` - converts `Steps` into bytecode
+- `Middlewares::BuildQuery` - builds an actual message that will be send to server
+- `Middlewares::CastResults` - casts server response into ruby objects
+- `Middlewares::RunQuery` - actually sends the message to the server
+
+Normally these middlewares must never be rearranged or removed from the stack. Middlewares added after
+`Middlewares::RunQuery` will not be executed.
+
+## Writing a middleware for Grumlin
+
+This entire feature is built on top of [ibsciss-middleware](https://github.com/Ibsciss/ruby-middleware) but uses a
+slightly modified `Builder` which caches the chain for better performance.
+Please refer to ibsciss-middleware docs if you want to implement a middleware.
+
+
+A minimal middleware that measures query execution time and puts it back to `env`:
+
+```ruby
+class MeasureExecutionTime < Grumlin::Middlewares::Middleware # Middleware provides only an initializer with one argument for `app`
+  def call(env)
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = @app.call(env)
+    env[:execution_time] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+    result
+  end
+end
+```
+
+When placed right before `Grumlin::Middlewares::CastResults` your middleware will have access to every intermediate result
+of the query execution process:
+- `env[:traversal]` - contains the original traversal
+- `env[:steps]` - contains the `Steps` representing the traversal
+- `env[:steps_without_shortcuts]` - contains the `Steps` representing the traversal, but with all shortcuts applied
+- `env[:bytecode]` - raw bytecode of the traversal
+- `env[:query]` - raw message that will be sent to the server. `requestId` can be found here: `env[:query][:requestId]`
+
+After the query is performed (after `@app.call(env)`), these keys become available:
+- `env[:results]` - raw results received from the server
+- `env[:parsed_results]` - server results mapped to ruby types, basically the query results as the client gets it
+
+Other useful parts of `env`:
+- `env[:session_id]` - id of the session when executed inside a transaction, otherwise `nil`
+- `env[:pool]` - connection pool that will be used to interact with the server
+- `env[:need_results]` - flag stating whether the client needs the query execution results(`toList`, `next`) or not(`iterate`)
+
+## Adding your middleware to the stack
+
+There are two ways of adding middlewares to your queries:
+- `global` - add the middleware to every single query from every single repository
+- `per repository` - add the middleware to queries performed by particular repositories
+
+Grumlin has one global middleware stack and every repository defines it's which is by default is a
+copy of the global stack. This means one can easily modify repository's stack without worrying about the global one.
+
+When inherited a class extending `Grumlin::Repository` will copy it's middlewares to the subclass, they can also be
+modified independently from the parent's middlewares.
+
+### Adding a middleware globally
+```ruby
+Grumlin.configure do |cfg|
+  cfg.url = ENV.fetch("GREMLIN_URL", "ws://localhost:8182/gremlin")
+  cfg.provider = :tinkergraph
+
+  cfg.middlewares do |b|
+    b.insert_before Grumlin::Middlewares::CastResults, MeasureExecutionTime
+  end
+end
+```
+
+### Adding a middleware to a repository
+```ruby
+class MyRepository
+  # MyRepository inherits a copy of global middlewares
+  extend Grumlin::Repository
+
+  # SomeOtherMiddleware will be added to MyRepository's middlewares only
+  middlewares do |b|
+    b.insert_before Grumlin::Middlewares::CastResults, MeasureExecutionTime
+  end
+end
+
+class AnotherRepository < MyRepository
+  # AnotherRepository inherits parent's middlewares
+  middlewares do |b|
+    # SomeOtherMiddleware will be added to AnotherRepository's middlewares only 
+    b.insert_before Grumlin::Middlewares::CastResults, SomeOtherMiddleware
+  end
+end
+```

data/grumlin.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "async-pool", "~> 0.3"
   spec.add_dependency "async-websocket", ">= 0.19", "< 0.20"
+  spec.add_dependency "ibsciss-middleware", "~> 0.4.0"
   spec.add_dependency "oj", "~> 3.13"
   spec.add_dependency "retryable", "~> 3.0"
   spec.add_dependency "zeitwerk", "~> 2.6"