nodo 1.6.0 → 1.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 421dba598b565369d200c90c8b095786f7b0a98de7c97e88c6927b59b64591a0
-  data.tar.gz: c6ba40e8873c90713edf4cc0887dcf64c3e7b9ea4629f4d97e3fc3c8c58218b9
+  metadata.gz: a4870340520e40bf14cf0e9261711983d5332eaf04419ff1281626ed5b4716e1
+  data.tar.gz: 162b5e4f6739728c91f64422acb579db9c004429f92402db5f393cfb76ffa675
 SHA512:
-  metadata.gz: 58410d1f53c78f40314ae24ea5f6e7d2aeca99f37aeeb6495ccdf0ee8a1fe903c956ad23462cba48ad38132df5614b3f354ee6c09638f52d47fe78e1e90d3064
-  data.tar.gz: 8374444cbbc7257b206fb17abd3470df3488885ae843e414bca3e645cf6c9f9e9d91d6de6f354e5f7fe4a1a98d780f04562df89752286851f8727d86e3c88aa9
+  metadata.gz: dbe6fb8dce3f39968b26800a28f50b7d2c1ac49ffc60537a50950af598bc329b6ae59fae2db8285b16167238448ef370502d7b6f736c4dc4e66563ae0050ccfd
+  data.tar.gz: 37dd504e71489566a9b57df0e217c2f25d09ce3d511dab2ac6daf849829b90f1293ed07dd4e320eb70ef573da7b466263c704bb99cf46cb555449a8253909089

data/README.md

@@ -91,6 +91,23 @@ class FooBar < Nodo::Core
 end
 ```
 
+### Dynamic ESM imports
+
+ES modules can be imported dynamically using `nodo.import()`:
+
+```ruby
+class DynamicFoo < Nodo::Core
+  function :v4, <<~JS
+    async () => {
+      const uuid = await nodo.import('uuid');
+      return await uuid.v4()
+    }
+  JS
+end
+```
+
+Note that the availability of dynamic imports depends on your Node version.
+
 ### Alternate function definition syntax
 
 JS code can also be supplied using the `code:` keyword argument:
@@ -131,6 +148,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
@@ -168,10 +202,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
@@ -208,8 +282,63 @@ 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
+## 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
@@ -220,7 +349,7 @@ an initializer:
 Nodo.modules_root = Rails.root.join('vendor', 'node_modules')
 ```
 
-The rationale behind this is NPM modules being external vendor dependencies, which
+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`.

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');
@@ -7,9 +9,10 @@ module.exports = (function() {
   const path = require('path');
   const fs = require('fs');
   const performance = require('perf_hooks').performance;
-  
+
   let server, closing;
   const classes = {};
+  const contexts = {};
   
   function render_error(e) {
     let errInfo = {};
@@ -45,7 +48,11 @@ module.exports = (function() {
       console.log(`[Nodo] ${message}`);
     }
   }
-  
+
+  async function import_module(specifier) {
+    return await import(specifier);
+  }
+
   const core = {
     run: (socket) => {
       debug('Starting up...');
@@ -60,12 +67,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 +99,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);
               });
             }
@@ -119,5 +139,5 @@ module.exports = (function() {
     }
   };
   
-  return { core: core, debug: debug };
+  return { core: core, debug: debug, import: import_module };
 })();

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.6.0'
+  VERSION = '1.6.4'
 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.6.0
+  version: 1.6.4
 platform: ruby
 authors:
 - Matthias Grosser