nodo 1.5.6 → 1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 650d220075d68a34268a03f2e68587b1caab13f47707c8b44f7cb7d05f5a5588
-  data.tar.gz: 0b73f0cd827a1ab364975d3559f64f2d9c49afe265759715f92d23f133bab10c
+  metadata.gz: 42cd6c0e3e07674ceb2f10dd670c490b7f23ed6534f22f978a40e0b91d529570
+  data.tar.gz: b560df0c25e2b72842e6d6d5be610503252069bfd1741fb2cd9228066d28f91e
 SHA512:
-  metadata.gz: 0c1049cd1e574c0a7ec503ef01ae735d7b3ca33d21695a1a76c4c8f5c92f0914db58b59136a7ea0bcf17b83f9c6776817b8b4890061e6c442e414c5476d80037
-  data.tar.gz: d5fd39f74f9ebfabaec0463dbf7234e6da34a73b3167f2580fb6ac276f52f6aef433156ef0917b4a5c9c344f1dfc6d0f28e7c1af1bfe329829c5c87068d932dd
+  metadata.gz: 012ed2197c0ea3e519884b3295a62986158326027adb08c484fbf87903874763594fe72236bebcc01f47a919a4893ef92cdc7a14b1f8ad02da7ea527ae5eab38
+  data.tar.gz: 6a953be3a789671c966248dcc385740c5964ad0bbb370411d93cdc44ee7ea129c14537d73c08e7a44eb4c19ca1bc2b5465873bec65fd4d56884ba9ed339981d6

data/README.md

@@ -1,4 +1,5 @@
-[![Gem Version](https://badge.fury.io/rb/nodo.svg)](http://badge.fury.io/rb/nodo)  [![build](https://github.com/mtgrosser/nodo/actions/workflows/build.yml/badge.svg)](https://github.com/mtgrosser/nodo/actions/workflows/build.yml)
+[![Gem Version](https://badge.fury.io/rb/nodo.svg)](http://badge.fury.io/rb/nodo)
+[![build](https://github.com/mtgrosser/nodo/actions/workflows/build.yml/badge.svg)](https://github.com/mtgrosser/nodo/actions/workflows/build.yml)
 
 # Nōdo – call Node.js from Ruby
 
@@ -107,13 +108,7 @@ To set a custom path:
 Nodo.modules_root = 'path/to/node_modules'
 ```
 
-For Rails applications, it will be set to `vendor/node_modules`. 
-To use the Rails 6 default of putting `node_modules` to `RAILS_ROOT`:
-
-```ruby
-# config/initializers/nodo.rb
-Nodo.modules_root = Rails.root.join('node_modules')
-```
+Also see: [Clean your Rails root](#Clean-your-Rails-root)
 
 ### Defining JS constants
 
@@ -136,6 +131,23 @@ class BarFoo < Nodo::Core
 end
 ```
 
+With the above syntax, the script code will be generated during class definition
+time. In order to have the code generated when the first instance is created, the
+code can be defined inside a block:
+
+```ruby
+class Foo < Nodo::Core
+  script do
+    <<~JS
+      var definitionTime = #{Time.now.to_json};
+    JS
+  end
+end
+```
+
+Note that the script will still be executed only once, when the first instance
+of class is created.
+
 ### Inheritance
 
 Subclasses will inherit functions, constants, dependencies and scripts from
@@ -173,10 +185,50 @@ class SyncFoo < Nodo::Core
 end
 ```
 
+### Deferred function definition
+
+By default, the function code string literal is created when the class
+is defined. Therefore any string interpolation inside the code will take
+place at definition time.
+
+In order to defer the code generation until the first object instantiation,
+the function code can be given inside a block:
+
+```ruby
+class Deferred < Nodo::Core
+  function :now, <<~JS
+    () => { return #{Time.now.to_json}; }
+  JS
+
+  function :later do
+    <<~JS
+      () => { return #{Time.now.to_json}; }
+    JS
+  end
+end
+
+instance = Deferred.new
+sleep 5
+instance.now => "2021-10-28 20:30:00 +0200"
+instance.later => "2021-10-28 20:30:05 +0200"
+```
+
+The block will be invoked when the first instance is created. As with deferred
+scripts, it will only be invoked once.
+
 ### Limiting function execution time
 
-The default timeout for a single JS function call is 60 seconds due to the
-`Net::HTTP` default. It can be overridden on a per-function basis:
+The default timeout for a single JS function call is 60 seconds and can be
+set globally:
+
+```ruby
+Nodo.timeout = 5
+```
+
+If the execution of a single function call exceeds the timeout, `Nodo::TimeoutError`
+is raised.
+
+The timeout can also be set on a per-function basis:
 
 ```ruby
 class Foo < Nodo::Core
@@ -201,6 +253,7 @@ Nodo.logger = Logger.new('nodo.log')
 
 In Rails applications, `Rails.logger` will automatically be set.
 
+
 ### Debugging
 
 To get verbose debug output, set
@@ -211,3 +264,78 @@ Nodo.debug = true
 
 before instantiating any worker instances. The debug mode will be active during
 the current process run.
+
+To print a debug message from JS code:
+
+```js
+nodo.debug("Debug message");
+```
+
+### Evaluation
+
+While `Nodo` is mainly function-based, it is possible to evaluate JS code in the
+context of the defined object.
+
+```ruby
+foo = Foo.new.evaluate("3 + 5")
+=> 8
+```
+
+Evaluated code can access functions, required dependencies and constants:
+
+```ruby
+class Foo < Nodo::Core
+  const :BAR, 'bar'
+  require :uuid
+  function :hello, code: '() => "world"'
+end
+
+foo = Foo.new
+
+foo.evaluate('BAR')
+=> "bar"
+
+foo.evaluate('uuid.v4()')
+=> "f258bef3-0d6f-4566-ad39-d8dec973ef6b"
+
+foo.evaluate('hello()')
+=> "world"
+```
+
+Variables defined by evaluation are local to the current instance:
+
+```ruby
+one = Foo.new
+one.evaluate('a = 1')
+two = Foo.new
+two.evaluate('a = 2')
+one.evaluate('a') => 1
+two.evaluate('a') => 2
+```
+
+⚠️ Evaluation comes with the usual caveats:
+
+- Avoid modifying any of your predefined identifiers. Remember that in JS,
+  as in Ruby, constants are not necessarily constant.
+- Never evaluate any code which includes un-checked user data. The Node.js process
+  has full read/write access to your filesystem! 💥
+
+
+## Clean your Rails root
+
+For Rails applications, Nodo enables you to move `node_modules`, `package.json` and
+`yarn.lock` into your application's `vendor` folder by setting the `NODE_PATH` in
+an initializer:
+
+```ruby
+# config/initializers/nodo.rb
+Nodo.modules_root = Rails.root.join('vendor', 'node_modules')
+```
+
+The rationale for this is NPM modules being external vendor dependencies, which
+should not clutter the application root directory.
+
+With this new default, all `yarn` operations should be done after `cd`ing to `vendor`.
+
+This repo provides an [adapted version](https://github.com/mtgrosser/nodo/blob/master/install/yarn.rake)
+of the `yarn:install` rake task which will automatically take care of the vendored module location.

data/lib/nodo/constant.rb

@@ -7,7 +7,7 @@ module Nodo
     end
 
     def to_js
-      "const #{name} = #{value.to_json};\n"
+      "const #{name} =  __nodo_klass__.#{name} = #{value.to_json};\n"
     end
   end
 end

data/lib/nodo/core.rb

@@ -1,8 +1,11 @@
 module Nodo
   class Core
     SOCKET_NAME = 'nodo.sock'
-    DEFINE_METHOD = '__nodo_define_class__'
-    TIMEOUT = 5
+    DEFINE_METHOD = '__nodo_define_class__'.freeze
+    EVALUATE_METHOD = '__nodo_evaluate__'.freeze
+    GC_METHOD = '__nodo_gc__'.freeze
+    INTERNAL_METHODS = [DEFINE_METHOD, EVALUATE_METHOD, GC_METHOD].freeze
+    LAUNCH_TIMEOUT = 5
     ARRAY_CLASS_ATTRIBUTES = %i[dependencies constants scripts].freeze
     HASH_CLASS_ATTRIBUTES = %i[functions].freeze
     CLASS_ATTRIBUTES = (ARRAY_CLASS_ATTRIBUTES + HASH_CLASS_ATTRIBUTES).freeze
@@ -10,6 +13,7 @@ module Nodo
     @@node_pid = nil
     @@tmpdir = nil
     @@mutex = Mutex.new
+    @@exiting = nil
     
     class << self
       extend Forwardable
@@ -21,15 +25,11 @@ module Nodo
           subclass.send "#{attr}=", send(attr).dup
         end
       end
-
+      
       def instance
         @instance ||= new
       end
       
-      def class_function(*methods)
-        singleton_class.def_delegators(:instance, *methods)
-      end
-      
       def class_defined?
         !!class_defined
       end
@@ -42,6 +42,7 @@ module Nodo
         define_method "#{attr}=" do |value|
           instance_variable_set :"@#{attr}", value
         end
+        protected "#{attr}="
       end
       
       ARRAY_CLASS_ATTRIBUTES.each do |attr|
@@ -55,30 +56,6 @@ module Nodo
           instance_variable_get(:"@#{attr}") || instance_variable_set(:"@#{attr}", {})
         end
       end
-      
-      def require(*mods)
-        deps = mods.last.is_a?(Hash) ? mods.pop : {}
-        mods = mods.map { |m| [m, m] }.to_h
-        self.dependencies = dependencies + mods.merge(deps).map { |name, package| Dependency.new(name, package) }
-      end
-
-      def function(name, _code = nil, timeout: 60, code: nil)
-        raise ArgumentError, "reserved method name #{name.inspect}" if Nodo::Core.method_defined?(name) || name.to_s == DEFINE_METHOD
-        code = (code ||= _code).strip
-        raise ArgumentError, 'function code is required' if '' == code
-        loc = caller_locations(1, 1)[0]
-        source_location = "#{loc.path}:#{loc.lineno}: in `#{name}'"
-        self.functions = functions.merge(name => Function.new(name, _code || code, source_location, timeout))
-        define_method(name) { |*args| call_js_method(name, args) }
-      end
-      
-      def const(name, value)
-        self.constants = constants + [Constant.new(name, value)]
-      end
-      
-      def script(code)
-        self.scripts = scripts + [Script.new(code)]
-      end
 
       def generate_core_code
         <<~JS
@@ -106,8 +83,7 @@ module Nodo
       def generate_class_code
         <<~JS
           (() => {
-            const __nodo_log = nodo.log;
-            const __nodo_klass__ = {};
+            const __nodo_klass__ = { nodo: global.nodo };
             #{dependencies.map(&:to_js).join}
             #{constants.map(&:to_js).join}
             #{functions.values.map(&:to_js).join}
@@ -117,14 +93,55 @@ module Nodo
         JS
       end
       
+      protected
+      
+      def finalize_context(context_id)
+        proc do
+          if not @@exiting and core = Nodo::Core.instance
+            core.send(:call_js_method, GC_METHOD, context_id)
+          end
+        end
+      end
+      
       private
       
+      def require(*mods)
+        deps = mods.last.is_a?(Hash) ? mods.pop : {}
+        mods = mods.map { |m| [m, m] }.to_h
+        self.dependencies = dependencies + mods.merge(deps).map { |name, package| Dependency.new(name, package) }
+      end
+
+      def function(name, _code = nil, timeout: Nodo.timeout, code: nil, &block)
+        raise ArgumentError, "reserved method name #{name.inspect}" if reserved_method_name?(name)
+        loc = caller_locations(1, 1)[0]
+        source_location = "#{loc.path}:#{loc.lineno}: in `#{name}'"
+        self.functions = functions.merge(name => Function.new(name, _code || code, source_location, timeout, &block))
+        define_method(name) { |*args| call_js_method(name, args) }
+      end
+      
+      def class_function(*methods)
+        singleton_class.def_delegators(:instance, *methods)
+      end
+
+      def const(name, value)
+        self.constants = constants + [Constant.new(name, value)]
+      end
+      
+      def script(code = nil, &block)
+        self.scripts = scripts + [Script.new(code, &block)]
+      end
+      
       def nodo_js
         Pathname.new(__FILE__).dirname.join('nodo.js').to_s.to_json
       end
+      
+      def reserved_method_name?(name)
+        Nodo::Core.method_defined?(name, false) || Nodo::Core.private_method_defined?(name, false) || name.to_s == DEFINE_METHOD
+      end
     end
     
     def initialize
+      raise ClassError, :new if self.class == Nodo::Core
       @@mutex.synchronize do
         ensure_process_is_spawned
         wait_for_socket
@@ -132,6 +149,13 @@ module Nodo
       end
     end
     
+    def evaluate(code)
+      ensure_context_is_defined
+      call_js_method(EVALUATE_METHOD, code)
+    end
+    
+    private
+    
     def node_pid
       @@node_pid
     end
@@ -148,9 +172,15 @@ module Nodo
       self.class.clsid
     end
     
+    def context_defined?
+      @context_defined
+    end
+    
     def log_exception(e)
       return unless logger = Nodo.logger
-      logger.error "\n#{e.class} (#{e.message}):\n\n#{e.backtrace.join("\n")}"
+      message = "\n#{e.class} (#{e.message})"
+      message << ":\n\n#{e.backtrace.join("\n")}" if e.backtrace
+      logger.error message
     end
     
     def ensure_process_is_spawned
@@ -164,12 +194,22 @@ module Nodo
       self.class.class_defined = true
     end
     
+    def ensure_context_is_defined
+      return if context_defined?
+      @@mutex.synchronize do
+        call_js_method(EVALUATE_METHOD, '')
+        ObjectSpace.define_finalizer(self, self.class.send(:finalize_context, self.object_id))
+        @context_defined = true
+      end
+    end
+    
     def spawn_process
       @@tmpdir = Pathname.new(Dir.mktmpdir('nodo'))
       env = Nodo.env.merge('NODE_PATH' => Nodo.modules_root.to_s)
       env['NODO_DEBUG'] = '1' if Nodo.debug
       @@node_pid = Process.spawn(env, Nodo.binary, '-e', self.class.generate_core_code, '--', socket_path.to_s, err: :out)
       at_exit do
+        @@exiting = true
         Process.kill(:SIGTERM, node_pid) rescue Errno::ECHILD
         Process.wait(node_pid) rescue Errno::ECHILD
         FileUtils.remove_entry(tmpdir) if File.directory?(tmpdir)
@@ -179,7 +219,7 @@ module Nodo
     def wait_for_socket
       start = Time.now
       socket = nil
-      while Time.now - start < TIMEOUT
+      while Time.now - start < LAUNCH_TIMEOUT
         begin
           break if socket = UNIXSocket.new(socket_path)
         rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::ENOTDIR
@@ -192,13 +232,19 @@ module Nodo
 
     def call_js_method(method, args)
       raise CallError, 'Node process not ready' unless node_pid
-      raise CallError, "Class #{clsid} not defined" unless self.class.class_defined? || method == DEFINE_METHOD
+      raise CallError, "Class #{clsid} not defined" unless self.class.class_defined? || INTERNAL_METHODS.include?(method)
       function = self.class.functions[method]
-      raise NameError, "undefined function `#{method}' for #{self.class}" unless function || method == DEFINE_METHOD
-      request = Net::HTTP::Post.new("/#{clsid}/#{method}", 'Content-Type': 'application/json')
+      raise NameError, "undefined function `#{method}' for #{self.class}" unless function || INTERNAL_METHODS.include?(method)
+      context_id = case method
+        when DEFINE_METHOD then 0
+        when GC_METHOD then args.first
+      else
+        object_id
+      end
+      request = Net::HTTP::Post.new("/#{clsid}/#{context_id}/#{method}", 'Content-Type': 'application/json')
       request.body = JSON.dump(args)
       client = Client.new("unix://#{socket_path}")
-      client.read_timeout = function.timeout if function
+      client.read_timeout = function&.timeout || Nodo.timeout
       response = client.request(request)
       if response.is_a?(Net::HTTPOK)
         parse_response(response)
@@ -215,7 +261,10 @@ module Nodo
     def handle_error(response, function)
       if response.body
         result = parse_response(response)
-        error = JavaScriptError.new(result['error'], function) if result.is_a?(Hash) && result.key?('error')
+        error = if result.is_a?(Hash) && result['error'].is_a?(Hash)
+          attrs = result['error']
+          (attrs['nodo_dependency'] ? DependencyError : JavaScriptError).new(attrs, function)
+        end
       end
       error ||= CallError.new("Node returned #{response.code}")
       log_exception(error)

data/lib/nodo/dependency.rb

@@ -7,7 +7,16 @@ module Nodo
     end
   
     def to_js
-      "const #{name} = require(#{package.to_json});\n"
+      <<~JS
+        const #{name} = __nodo_klass__.#{name} = (() => {
+          try {
+            return require(#{package.to_json});
+          } catch(e) {
+            e.nodo_dependency = #{package.to_json};
+            throw e;
+          }
+        })();
+      JS
     end
   end
 end

data/lib/nodo/errors.rb

@@ -2,6 +2,11 @@ module Nodo
   class Error < StandardError; end
   class TimeoutError < Error; end
   class CallError < Error; end
+  class ClassError < Error
+    def initialize(method = nil)
+      super("Cannot call method `#{method}' on Nodo::Core, use subclass instead")
+    end
+  end
   
   class JavaScriptError < Error
     attr_reader :attributes
@@ -37,13 +42,23 @@ module Nodo
     end
     
     def generate_message
-      message = "#{attributes['message'] || 'Unknown error'}"
-      if loc = attributes['loc']
-        message << loc.inject(' in') { |s, (key, value)| s << " #{key}: #{value}" }
-      end
-      message
+      message = "#{attributes['message'] || attributes['name'] || 'Unknown error'}"
+      message << format_location(attributes['loc'])
+    end
+    
+    def format_location(loc)
+      return '' unless loc
+      loc.inject(' in') { |s, (key, value)| s << " #{key}: #{value}" }
     end
   end
   
-  class DependencyError < JavaScriptError; end
+  class DependencyError < JavaScriptError
+    private
+    
+    def generate_message
+      message = "#{attributes['message'] || attributes['name'] || 'Dependency error'}\n"
+      message << "The specified dependency '#{attributes['nodo_dependency']}' could not be loaded. "
+      message << "Run 'yarn add #{attributes['nodo_dependency']}' to install it.\n"
+    end
+  end
 end

data/lib/nodo/function.rb

@@ -2,12 +2,17 @@ module Nodo
   class Function
     attr_reader :name, :code, :source_location, :timeout
   
-    def initialize(name, code, source_location, timeout)
-      @name, @code, @source_location, @timeout = name, code, source_location, timeout
+    def initialize(name, code, source_location, timeout, &block)
+      raise ArgumentError, 'cannot give code when block is given' if code && block
+      code = code.strip if code
+      raise ArgumentError, 'function code is required' if '' == code
+      raise ArgumentError, 'code is required' unless code || block
+      @name, @code, @source_location, @timeout = name, code || block, source_location, timeout
     end
   
     def to_js
-      "const #{name} = __nodo_klass__.#{name} = (#{code});\n"
+      js = code.respond_to?(:call) ? code.call.strip : code
+      "const #{name} = __nodo_klass__.#{name} = (#{js});\n"
     end
   end
 end

data/lib/nodo/nodo.js

@@ -1,5 +1,7 @@
 module.exports = (function() {
   const DEFINE_METHOD = '__nodo_define_class__';
+  const EVALUATE_METHOD = '__nodo_evaluate__';
+  const GC_METHOD = '__nodo_gc__';
   const DEBUG = process.env.NODO_DEBUG;
 
   const vm = require('vm');
@@ -10,6 +12,7 @@ module.exports = (function() {
   
   let server, closing;
   const classes = {};
+  const contexts = {};
   
   function render_error(e) {
     let errInfo = {};
@@ -60,12 +63,17 @@ module.exports = (function() {
         }
         
         const url = req.url.substring(1);
-        const [class_name, method] = url.split('/');
-        let klass;
+        const [class_name, object_id, method] = url.split('/');
+        let klass, context;
         
         if (classes.hasOwnProperty(class_name)) {
           klass = classes[class_name];
-          if (!klass.hasOwnProperty(method)) {
+          if (EVALUATE_METHOD == method) {
+            if (!contexts.hasOwnProperty(object_id)) {
+              contexts[object_id] = vm.createContext({ require: require, ...klass });
+            }
+            context = contexts[object_id];
+          } else if (!klass.hasOwnProperty(method) && !GC_METHOD == method) {
             return respond_with_error(res, 404, `Method ${class_name}#${method} not found`);
           }
         } else if (DEFINE_METHOD != method) {
@@ -87,13 +95,21 @@ module.exports = (function() {
 
           try {
             if (DEFINE_METHOD == method) {
-              let new_class = vm.runInThisContext(input, class_name);
-              classes[class_name] = new_class;
+              classes[class_name] = vm.runInThisContext(input, class_name);
               respond_with_data(res, class_name, start);
+            } else if (EVALUATE_METHOD == method) {
+              Promise.resolve(vm.runInNewContext(input, context)).then((result) => {
+                respond_with_data(res, result, start);
+              }).catch((error) => {
+                respond_with_error(res, 500, error);
+              });
+            } else if (GC_METHOD == method) {
+              delete contexts[object_id];
+              respond_with_data(res, true, start);
             } else {
-              Promise.resolve(klass[method].apply(null, input)).then(function (result) {
+              Promise.resolve(klass[method].apply(null, input)).then((result) => {
                 respond_with_data(res, result, start);
-              }).catch(function(error) {
+              }).catch((error) => {
                 respond_with_error(res, 500, error);
               });
             }

data/lib/nodo/railtie.rb

@@ -3,7 +3,6 @@ require 'active_support'
 
 class Nodo::Railtie < Rails::Railtie
   initializer 'nodo' do |app|
-    Nodo.modules_root = Rails.root.join('vendor', 'node_modules')
     Nodo.env['NODE_ENV'] = Rails.env.to_s
     Nodo.logger = Rails.logger
   end

data/lib/nodo/script.rb

@@ -2,12 +2,14 @@ module Nodo
   class Script
     attr_reader :code
     
-    def initialize(code)
-      @code = code
+    def initialize(code = nil, &block)
+      raise ArgumentError, 'cannot give code when block is given' if code && block
+      @code = code || block
     end
   
     def to_js
-      "#{code}\n"
+      js = code.respond_to?(:call) ? code.call : code
+      "#{js}\n"
     end
   end
 end

data/lib/nodo/version.rb

@@ -1,3 +1,3 @@
 module Nodo
-  VERSION = '1.5.6'
+  VERSION = '1.6.3'
 end

data/lib/nodo.rb

@@ -9,13 +9,14 @@ require 'forwardable'
 
 module Nodo
   class << self
-    attr_accessor :modules_root, :env, :binary, :logger, :debug
+    attr_accessor :modules_root, :env, :binary, :logger, :debug, :timeout
   end
   self.modules_root = './node_modules'
   self.env = {}
   self.binary = 'node'
   self.logger = Logger.new(STDOUT)
   self.debug  = false
+  self.timeout = 60
 end
 
 require_relative 'nodo/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nodo
 version: !ruby/object:Gem::Version
-  version: 1.5.6
+  version: 1.6.3
 platform: ruby
 authors:
 - Matthias Grosser