cuboid 0.3.6 → 0.5

data/lib/cuboid/rest/server/instance_helpers.rb

@@ -1,97 +1,31 @@
+require_relative '../../server/instance_helpers'
+
 module Cuboid
 module Rest
 class Server
 
+# Sinatra-coupled supplement to `Cuboid::Server::InstanceHelpers` —
+# the methods that read `env` or call `handle_error` (a Sinatra helper
+# defined on `Rest::Server`). Everything that doesn't need Sinatra
+# stays on the shared module above.
 module InstanceHelpers
 
-    @@instances   = {}
-    @@agents = {}
-
-    def get_instance
-        if agent
-            options = {
-              owner:   self.class.to_s,
-              helpers: {
-                    owner: {
-                        url: env['HTTP_HOST']
-                    }
-                }
-            }
-
-            if (info = agent.spawn( options ))
-                connect_to_instance( info['url'], info['token'] )
-            end
-        else
-            Processes::Instances.spawn( application: Options.paths.application, daemonize: true )
-        end
-    end
-
-    def agents
-        @@agents.keys
-    end
+    include ::Cuboid::Server::InstanceHelpers
 
-    def agent
-        return if !Options.agent.url
-        @agent ||= connect_to_agent( Options.agent.url )
-    end
-
-    def unplug_agent( url )
-        connect_to_agent( url ).node.unplug
-
-        c = @@agents.delete( url )
-        c.close if c
-    end
-
-    def connect_to_agent( url )
-        @@agents[url] ||= RPC::Client::Agent.new( url )
-    end
-
-    def connect_to_instance( url, token )
-        RPC::Client::Instance.new( url, token )
-    end
-
-    def update_from_scheduler
-        return if !scheduler
-
-        scheduler.running.each do |id, info|
-            instances[id] ||= connect_to_instance( info['url'], info['token'] )
-        end
-
-        (scheduler.failed.keys | scheduler.completed.keys).each do |id|
-            session.delete id
-            client = instances.delete( id )
-            client.close if client
-        end
-    end
-
-    def scheduler
-        return if !Options.scheduler.url
-        @scheduler ||= connect_to_scheduler( Options.scheduler.url )
-    end
-
-    def connect_to_scheduler( url )
-        RPC::Client::Scheduler.new( url )
-    end
-
-    def instances
-        @@instances
+    # Forward the request host to the shared spawner so the Agent can
+    # log who asked for the instance.
+    def spawn( owner_url: env['HTTP_HOST'] )
+        super
     end
 
     def instance_for( id, &block )
-        cleanup = proc do
-            instances.delete( id ).close
-            session.delete id
-        end
+        cleanup = proc { instances.delete( id ).close }
 
         handle_error cleanup do
-            block.call @@instances[id]
+            block.call instances[id]
         end
     end
 
-    def exists?( id )
-        instances.include? id
-    end
-
 end
 
 end

data/lib/cuboid/rest/server/routes/instances.rb

@@ -20,7 +20,7 @@ module Instances
 
             options = ::JSON.load( request.body.read ) || {}
 
-            instance = get_instance
+            instance = self.spawn
             max_utilization! if !instance
 
             handle_error proc { (instance.shutdown rescue nil) } do
@@ -36,20 +36,19 @@ module Instances
         app.get '/instances/:instance' do
             ensure_instance!
 
-            session[params[:instance]] ||= {
-                seen_errors:  0,
-            }
+            # The Sinatra session is per-cookie, but its id isn't
+            # exposed; lazy-init a per-client UUID and pass it as
+            # the RPC `session:` token so the engine tracks the
+            # error-line offset server-side.
+            require 'securerandom' unless defined?( SecureRandom )
+            session[:rpc_session_id] ||= SecureRandom.uuid
 
             data = instance_for( params[:instance] ) do |instance|
                 instance.progress(
-                    with:    [
-                                 errors:  session[params[:instance]][:seen_errors],
-                             ]
+                  session: "#{session[:rpc_session_id]}:#{params[:instance]}"
                 )
             end
 
-            session[params[:instance]][:seen_errors] += data[:errors].size
-
             json data
         end
 
@@ -110,14 +109,10 @@ module Instances
         app.delete '/instances/:instance' do
             ensure_instance!
             id = params[:instance]
-
-            instance = instances[id]
             handle_error { (instance.shutdown rescue nil) }
 
             instances.delete( id ).close
 
-            session.delete params[:instance]
-
             json nil
         end
 

data/lib/cuboid/rest/server.rb

@@ -18,7 +18,7 @@ class Server < Sinatra::Base
 
     Dir.glob( "#{File.dirname( __FILE__ )}/server/routes/*.rb" ).each { |f| require f }
 
-    helpers InstanceHelpers
+    helpers ::Cuboid::Rest::Server::InstanceHelpers
 
     register Sinatra::Namespace
     Cuboid::Application.application.rest_services.each do |name, service|

data/lib/cuboid/rpc/server/agent.rb

@@ -320,12 +320,17 @@ class Agent
     end
 
     def spawn_instance( options = {}, &block )
+        # `detached: true` opts the spawned engine out of the
+        # base.rb parent-death watchdog: an agent restarting / dying
+        # must NOT take the engine with it (grid pattern — the
+        # instance is owned by whoever connects, not the agent).
         Processes::Instances.spawn( options.merge(
             address:     @server.address,
             port_range:  Options.agent.instance_port_range,
             token:       Utilities.generate_token,
             application: Options.paths.application,
-            daemonize:   true
+            daemonize:   true,
+            detached:    true
         )) do |client|
             block.call(
                 'token'       => client.token,

data/lib/cuboid/rpc/server/instance.rb

@@ -152,51 +152,38 @@ class Instance
     #   In addition, ask to **not** be served data you already have, like
     #   error messages.
     #
-    #   To be kept completely up to date on the progress of a scan (i.e. receive
-    #   new issues and error messages asap) in an efficient manner, you will need
-    #   to keep track of the error messages you already have and explicitly tell
-    #   the method to not send the same data back to you on subsequent calls.
+    #   Pass a `session:` token (any caller-chosen string) and the
+    #   server returns only error lines past the previous offset
+    #   under that token. Reuse the same token across polls for
+    #   the same logical view; pick a fresh one to start fresh.
     #
-    # ## Retrieving errors (`:errors` option) without duplicate data
-    #
-    #   This is done by telling the method how many error messages you already
-    #   have and you will be served the errors from the error-log that are past
-    #   that line.
-    #   So, if you were to use a loop to get fresh progress data it would look
-    #   like so:
-    #
-    #     error_cnt = 0
-    #     i = 0
+    #     token = SecureRandom.uuid
     #     while sleep 1
-    #         # Test method, triggers an error log...
-    #         instance.error_test "BOOM! #{i+=1}"
-    #
-    #         # Only request errors we don't already have
-    #         errors = instance.progress( with: { errors: error_cnt } )[:errors]
-    #         error_cnt += errors.size
-    #
-    #         # You will only see new errors
-    #         puts errors.join("\n")
+    #         errors = instance.progress( session: token )[:errors]
+    #         puts errors.join( "\n" )
     #     end
     #
-    # @param  [Hash]  options
-    #   Options about what progress data to retrieve and return.
-    # @option options [Array<Symbol, Hash>]  :with
-    #   Specify data to include:
-    #
-    #   * :errors -- Errors and the line offset to use for {#errors}.
-    #     Pass as a hash, like: `{ errors: 10 }`
-    # @option options [Array<Symbol, Hash>]  :without
-    #   Specify data to exclude:
+    #   Without `session`, callers must opt into errors via
+    #   `with: [:errors]` and will receive the full set every poll.
     #
-    #   * :statistics -- Don't include runtime statistics.
+    # @param  [Hash]  options
+    # @option options [String, Symbol] :session
+    #   Caller-chosen session token. When provided, the response
+    #   carries only errors past the previously emitted offset.
+    # @option options [Array<Symbol>]  :with
+    #   Block names to include when no session is in use. Currently
+    #   only `:errors` is delta-able.
+    # @option options [Array<Symbol>]  :without
+    #   Block names to exclude. One or more of `:statistics`,
+    #   `:errors`. Takes precedence over `with:` and over the
+    #   session-on-by-default blocks.
     #
     # @return [Hash]
     #   * `statistics` -- General runtime statistics (merged when part of Grid)
     #       (enabled by default)
     #   * `status` -- {#status}
     #   * `busy` -- {#busy?}
-    #   * `errors` -- {#errors} (disabled by default)
+    #   * `errors` -- {#errors}
     def progress( options = {} )
         progress_handler( options.merge( as_hash: true ) )
     end
@@ -226,6 +213,27 @@ class Instance
     end
 
     # Makes the server go bye-bye...Lights out!
+    #
+    # `shutdown` must reliably take the Ruby process with it. Stopping
+    # the reactor + RPC server alone leaves the Application's non-daemon
+    # threads (audit workers, browser cluster manager, etc.) blocking
+    # the runtime — historically this leaked engine subprocesses every
+    # time `kill_instance` was called over MCP, and showed up in the
+    # cuboid spec suite as leftover ruby processes after the run.
+    # The `instance.shutdown` RPC returned success but the daemonised
+    # process never actually exited.
+    #
+    # Two-stage exit:
+    #   1. Raise SystemExit on the **main thread** so the at_exit
+    #      chain runs (Cuboid_<pid> tmpdir cleanup, live-plugin's
+    #      `exited` push). SystemExit raised on a non-main thread
+    #      only kills that thread — must hit the main one.
+    #   2. Watchdog SIGKILL after a grace window in case a
+    #      non-daemon Application thread refuses to release. The
+    #      Paths boot-sweep reaps the orphaned tmpdir on the next
+    #      cuboid process launch even when at_exit didn't run.
+    SHUTDOWN_GRACE_SECONDS = 5.0
+
     def shutdown( &block )
         if @shutdown
             block.call if block_given?
@@ -243,6 +251,17 @@ class Instance
             @server.shutdown
             @raktr.stop
             block.call true if block_given?
+
+            # Stage 1 — graceful: SystemExit on the main thread so
+            # at_exit handlers run.
+            main = Thread.main
+            if main && main.alive? && main != Thread.current
+                main.raise( SystemExit.new( 0 ) ) rescue nil
+            end
+
+            # Stage 2 — watchdog: hammer if main can't unwind.
+            sleep SHUTDOWN_GRACE_SECONDS
+            Process.kill( 'KILL', Process.pid ) rescue nil
         end
 
         true
@@ -262,49 +281,50 @@ class Instance
         [Process.pid]
     end
 
-    def self.parse_progress_opts( options, key )
-        parsed = {}
-        [options.delete( key ) || options.delete( key.to_s )].compact.each do |w|
-            case w
-                when Array
-                    w.compact.flatten.each do |q|
-                        case q
-                            when String, Symbol
-                                parsed[q.to_sym] = nil
-
-                            when Hash
-                                parsed.merge!( q.my_symbolize_keys )
-                        end
-                    end
-
-                when String, Symbol
-                    parsed[w.to_sym] = nil
-
-                when Hash
-                    parsed.merge!( w.my_symbolize_keys )
-            end
-        end
-
-        parsed
+    def self.parse_block_names( raw )
+        return [] if raw.nil?
+        Array( raw ).flatten.compact.map(&:to_sym)
     end
 
     private
 
+    # Server-side state for `session:`-tracked progress polls.
+    # Keyed off a caller-supplied token so RPC clients don't have
+    # to re-transmit the error line offset on every poll.
+    def progress_sessions
+        @progress_sessions ||= {}
+    end
+
+    def progress_session_for( id )
+        progress_sessions[id] ||= { seen_errors: 0 }
+    end
+
     def progress_handler( options = {}, &block )
-        with    = self.class.parse_progress_opts( options, :with )
-        without = self.class.parse_progress_opts( options, :without )
+        options = options.my_symbolize_keys
+
+        session_id = options.delete( :session )
+        session    = progress_session_for( session_id ) if session_id
 
-        options = {
+        with    = self.class.parse_block_names( options[:with] )
+        without = self.class.parse_block_names( options[:without] )
+
+        # Under a session, errors are on by default; without a
+        # session, callers opt in via `with: [:errors]`.
+        include_errors = !without.include?( :errors ) && (session || with.include?( :errors ))
+
+        wrapper_options = {
             as_hash:    options[:as_hash],
             statistics: !without.include?( :statistics )
         }
+        wrapper_options[:errors] = session ? session[:seen_errors] : 0 if include_errors
 
-        if with[:errors]
-            options[:errors] = with[:errors]
-        end
-
-        @application.progress( options ) do |data|
+        @application.progress( wrapper_options ) do |data|
             data[:busy] = busy?
+
+            if session && data[:errors]
+                session[:seen_errors] += data[:errors].size
+            end
+
             block.call( data )
         end
     end

data/lib/cuboid/server/instance_helpers.rb

@@ -0,0 +1,131 @@
+module Cuboid
+module Server
+
+# Shared registry + lookup helpers for the running engine instances
+# any front-end (REST, MCP, scheduler-sync) drives. The two
+# class-variables (`@@instances`, `@@agents`) are intentionally
+# module-level so every includer sees the same map without explicit
+# cross-process plumbing.
+#
+# `spawn` here picks an Agent if one is configured (so grid mode keeps
+# working) or falls back to local `Processes::Instances.spawn`.
+# Sinatra-only surface — `instance_for`, REST-side scheduler-session
+# cleanup, and the env-derived owner URL on `spawn` — lives on
+# `Cuboid::Rest::Server::InstanceHelpers`, which mixes this in.
+module InstanceHelpers
+
+    @@instances = {}
+    @@agents    = {}
+
+    def self.instances
+        @@instances
+    end
+
+    # Spawn a new engine instance. If an Agent URL is configured the
+    # instance is provisioned via the Agent (grid path); otherwise we
+    # fork a local one via `Processes::Instances.spawn`.
+    #
+    # `owner_url` is forwarded to the Agent as `helpers.owner.url` —
+    # purely metadata identifying who asked. Sinatra/REST callers pass
+    # `env['HTTP_HOST']`; MCP and other non-Rack callers can leave it
+    # nil or pass whatever they have. Module-level so callers without
+    # an includer context (e.g. `MCP::CoreTools::SpawnInstance`) can
+    # use it as `Cuboid::Server::InstanceHelpers.spawn`.
+    def self.spawn( owner_url: nil )
+        if (a = agent)
+            options = {
+              owner:   name,
+              helpers: { owner: { url: owner_url } }
+            }
+
+            if (info = a.spawn( options ))
+                connect_to_instance( info['url'], info['token'] )
+            end
+        else
+            ::Cuboid::Processes::Instances.spawn(
+                application: ::Cuboid::Options.paths.application,
+                daemonize:   true
+            )
+        end
+    end
+
+    def self.agent
+        return if !::Cuboid::Options.agent.url
+        @@agents[::Cuboid::Options.agent.url] ||=
+            ::Cuboid::RPC::Client::Agent.new( ::Cuboid::Options.agent.url )
+    end
+
+    def self.connect_to_agent( url )
+        @@agents[url] ||= ::Cuboid::RPC::Client::Agent.new( url )
+    end
+
+    def self.connect_to_instance( url, token )
+        ::Cuboid::RPC::Client::Instance.new( url, token )
+    end
+
+    def agents
+        @@agents.keys
+    end
+
+    def agent
+        InstanceHelpers.agent
+    end
+
+    def spawn( owner_url: nil )
+        InstanceHelpers.spawn( owner_url: owner_url )
+    end
+
+    def unplug_agent( url )
+        InstanceHelpers.connect_to_agent( url ).node.unplug
+
+        c = @@agents.delete( url )
+        c.close if c
+    end
+
+    def connect_to_agent( url )
+        InstanceHelpers.connect_to_agent( url )
+    end
+
+    def connect_to_instance( url, token )
+        InstanceHelpers.connect_to_instance( url, token )
+    end
+
+    # Pulls scheduler-tracked running instances into the local map and
+    # closes/removes any that the scheduler reports failed or completed.
+    # Sinatra-side session cleanup for the same IDs is the responsibility
+    # of `Cuboid::Rest::Server::InstanceHelpers#update_from_scheduler`,
+    # which calls super then prunes its session.
+    def update_from_scheduler
+        return if !scheduler
+
+        scheduler.running.each do |id, info|
+            instances[id] ||= connect_to_instance( info['url'], info['token'] )
+        end
+
+        (scheduler.failed.keys | scheduler.completed.keys).each do |id|
+            client = instances.delete( id )
+            client.close if client
+        end
+    end
+
+    def scheduler
+        return if !Options.scheduler.url
+        @scheduler ||= connect_to_scheduler( Options.scheduler.url )
+    end
+
+    def connect_to_scheduler( url )
+        RPC::Client::Scheduler.new( url )
+    end
+
+    def instances
+        InstanceHelpers.instances
+    end
+
+    def exists?( id )
+        instances.include? id
+    end
+
+end
+
+end
+end

data/lib/version

@@ -1 +1 @@
-0.3.6
+0.5