nodo 1.5.5 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cef66bc4b1d53b20500110ac7acbc226ec361b6aaed569874ce8568a6718242
-  data.tar.gz: ab2cae6eef01d53ebc1c471a5e08edfd37a263178adc49aa459c98dfcea4e92f
+  metadata.gz: 95d8c9823753373c6be5ad0c493e7f14346950b611d4ca0d90c5a96bcabfa5e6
+  data.tar.gz: 3ad4b37694f4ef33cfadad03794ce7b4bf2a9fd42dc4e0abb319ec981e529b33
 SHA512:
-  metadata.gz: 9bf90e8b56366f2e42039026575db43a0c5a9808a677a533c3e211c9ae211a8f06b2ea0890550e22fca259f9fa416c0e96017a676538a3eb673f2a66caa0996a
-  data.tar.gz: 2573e2dfd199bb9f8e25dc11c5dcb49e0ba6f29796aaa523656fa1020e0d8ce325ab411cf2d60413ac0557407fec4a132ba51d75075585a0e7b56d76bfc42811
+  metadata.gz: 0e0004a84541cb4edd4cc398250fe17ee5623aed13f1bbb76b31eee531867906cffd87c5e0f71b50c0c72fdae4f26e57d24f654fdd2623bee90b20c60f3ff0b4
+  data.tar.gz: 539b75f4a8283f4db872db614158403129651f4b0811d9e7f9ef5dfa1f506bedcf238fa0b93896fe776ae936bbc8eba9cbd44ea86fa8f80b87142e5d69cfe957

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
 
@@ -175,8 +170,17 @@ end
 
 ### 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
@@ -185,6 +189,105 @@ class Foo < Nodo::Core
   JS
 end
 
-foo.new.sleep(2)
+Foo.new.sleep(2)
 =>  Nodo::TimeoutError raised
 ```
+
+### Logging
+
+By default, JS errors will be logged to `STDOUT`.
+
+To set a custom logger:
+
+```ruby
+Nodo.logger = Logger.new('nodo.log')
+```
+
+In Rails applications, `Rails.logger` will automatically be set.
+
+
+### Debugging
+
+To get verbose debug output, set
+
+```ruby
+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,28 +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) 
-        code = (code ||= _code).strip
-        raise ArgumentError, 'function code is required' if '' == code
-        self.functions = functions.merge(name => Function.new(name, _code || code, caller.first, 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
@@ -94,7 +73,7 @@ module Nodo
             nodo.core.close(() => { process.exit(0) });
           };
 
-          process.on('SIGINT', shutdown);
+          // process.on('SIGINT', shutdown);
           process.on('SIGTERM', shutdown);
 
           nodo.core.run(socket);
@@ -104,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}
@@ -115,14 +93,57 @@ 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)
+        raise ArgumentError, "reserved method name #{name.inspect}" if reserved_method_name?(name)
+        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 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)
+        self.scripts = scripts + [Script.new(code)]
+      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
@@ -130,6 +151,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
@@ -146,6 +174,17 @@ module Nodo
       self.class.clsid
     end
     
+    def context_defined?
+      @context_defined
+    end
+    
+    def log_exception(e)
+      return unless logger = Nodo.logger
+      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
       return if node_pid
       spawn_process
@@ -157,11 +196,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)
@@ -171,7 +221,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
@@ -184,10 +234,16 @@ 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
@@ -207,9 +263,14 @@ module Nodo
     def handle_error(response, function)
       if response.body
         result = parse_response(response)
-        raise 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
-      raise CallError, "Node returned #{response.code}"
+      error ||= CallError.new("Node returned #{response.code}")
+      log_exception(error)
+      raise error
     end
     
     def parse_response(response)

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/nodo.js

@@ -1,5 +1,8 @@
 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');
   const http = require('http');
@@ -9,6 +12,7 @@ module.exports = (function() {
   
   let server, closing;
   const classes = {};
+  const contexts = {};
   
   function render_error(e) {
     let errInfo = {};
@@ -24,7 +28,7 @@ module.exports = (function() {
   function respond_with_error(res, code, name) {
     res.statusCode = code;
     const rendered = render_error(name);
-    log(`Error ${code} ${rendered}`);
+    debug(`Error ${code} ${rendered}`);
     res.end(rendered, 'utf8');
   }
   
@@ -35,34 +39,41 @@ module.exports = (function() {
     if (start) {
       timing = ` in ${(performance.now() - start).toFixed(2)}ms`;
     }
-    log(`Completed 200 OK${timing}`);
+    debug(`Completed 200 OK${timing}\n`);
   }
 
-  function log(message) {
-    // fs.appendFileSync('log/nodo.log', `${message}\n`);
-    // console.log(`[Nodo] ${message}`);
+  function debug(message) {
+    if (DEBUG) {
+      // fs.appendFileSync('log/nodo.log', `${message}\n`);
+      console.log(`[Nodo] ${message}`);
+    }
   }
   
   const core = {
     run: (socket) => {
-      log('Starting up...');
+      debug('Starting up...');
       server = http.createServer((req, res) => {
         const start = performance.now();
         
         res.setHeader('Content-Type', 'application/json');
-        log(`${req.method} ${req.url}`);
+        debug(`${req.method} ${req.url}`);
 
         if (req.method !== 'POST' || !req.url.startsWith('/')) {
           return respond_with_error(res, 405, 'Method Not Allowed');
         }
         
         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) {
@@ -84,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);
               });
             }
@@ -103,12 +122,12 @@ module.exports = (function() {
 
       //server.maxConnections = 64;
       server.listen(socket, () => {
-        log(`server ready, listening on ${socket} (max connections: ${server.maxConnections})`);
+        debug(`server ready, listening on ${socket} (max connections: ${server.maxConnections})`);
       });
     },
     
     close: (finalizer) => {
-      log("Shutting down");
+      debug("Shutting down");
       if (!closing) {
         closing = true;
         server.close(finalizer);
@@ -116,5 +135,5 @@ module.exports = (function() {
     }
   };
   
-  return { core: core, log: log };
+  return { core: core, debug: debug };
 })();

data/lib/nodo/railtie.rb

@@ -3,6 +3,7 @@ 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
 end

data/lib/nodo/version.rb

@@ -1,3 +1,3 @@
 module Nodo
-  VERSION = '1.5.5'
+  VERSION = '1.6.2'
 end

data/lib/nodo.rb

@@ -3,16 +3,20 @@ require 'json'
 require 'fileutils'
 require 'tmpdir'
 require 'tempfile'
+require 'logger'
 require 'socket'
 require 'forwardable'
 
 module Nodo
   class << self
-    attr_accessor :modules_root, :env, :binary
+    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.5
+  version: 1.6.2
 platform: ruby
 authors:
 - Matthias Grosser