cuboid 0.3.5 → 0.4

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

@@ -1,80 +1,35 @@
+require_relative '../../server/instance_helpers'
+
 module Cuboid
 module Rest
 class Server
 
+# Sinatra-coupled supplement to `Cuboid::Server::InstanceHelpers` —
+# the methods that read `env`, call `handle_error` (a Sinatra helper
+# defined on `Rest::Server`), or prune `session` entries belonging to
+# scheduler-removed instances. 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
-
-    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
+    include ::Cuboid::Server::InstanceHelpers
 
-    def connect_to_instance( url, token )
-        RPC::Client::Instance.new( url, token )
+    # 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
 
+    # Adds Sinatra-session cleanup for IDs the scheduler has dropped.
+    # The shared `update_from_scheduler` already removes them from the
+    # instance map; this override prunes the matching session keys so a
+    # second request from the same browser doesn't try to reach a dead
+    # instance.
     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
+        pruned = scheduler.failed.keys | scheduler.completed.keys
+        super
+        pruned.each { |id| session.delete id }
     end
 
     def instance_for( id, &block )
@@ -84,14 +39,10 @@ module InstanceHelpers
         end
 
         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
@@ -110,8 +110,6 @@ 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

data/lib/cuboid/rest/server.rb

@@ -2,6 +2,11 @@ require 'puma'
 require 'puma/minissl'
 require 'sinatra/base'
 require 'sinatra/contrib'
+# Rack 3 gemified Rack::Session out into the rack-session gem; sinatra-contrib
+# pulls it in transitively, but the Rack::Session::Pool constant only loads
+# when the session-pool file is required directly. Without this the
+# `use Rack::Session::Pool` line below NameErrors at boot.
+require 'rack/session/pool'
 
 module Cuboid
 module Rest
@@ -13,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|
@@ -34,9 +39,26 @@ class Server < Sinatra::Base
 
     enable :logging
 
-    VALID_REPORT_FORMATS = %w(json xml yaml html.zip)
+    # sinatra-contrib's default `:json_encoder` is `MultiJson`, and its
+    # `resolve_encoder_action` tries `:encode` before `:generate`. Under
+    # multi_json 1.20+, `MultiJson.encode` is a deprecated alias to
+    # `dump` and emits a warning on every call. Pin the encoder to
+    # stdlib `JSON` (which exposes `generate`) to bypass the alias and
+    # silence the deprecation without a downstream gem bump.
+    set :json_encoder, ::JSON
 
     before do
+        # Rack 3 reads and consumes `rack.input` to build the params hash
+        # for known content types (application/x-www-form-urlencoded,
+        # multipart/...) BEFORE the route handler runs. After that
+        # consumption `request.body.read` returns "" until the IO is
+        # rewound. Cuboid's REST routes hand-parse JSON via
+        # `JSON.load(request.body.read)`, so without this rewind every
+        # PUT/POST that ships a JSON body silently looks empty under
+        # Rack 3 — `Options.scheduler.url`, scan options, etc. never get
+        # set and downstream routes 404. Idempotent under Rack 2.
+        request.body.rewind if request.body.respond_to?(:rewind)
+
         protected!
         content_type :json
     end

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

@@ -226,6 +226,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 +264,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

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.5
+0.4

data/spec/cuboid/mcp/auth_spec.rb

@@ -0,0 +1,179 @@
+require 'spec_helper'
+require "#{Cuboid::Options.paths.lib}/mcp/auth"
+
+describe Cuboid::MCP::Auth do
+    # Inner app: any time the middleware passes a request through, the
+    # inner app records the env it saw and replies 200 OK. Lets us
+    # check that env['cuboid.mcp.auth'] is populated AND that
+    # short-circuited (401) requests never reach it.
+    let(:inner_app) do
+        seen = []
+        app = ->(env) {
+            seen << env
+            [200, { 'content-type' => 'text/plain' }, ['ok']]
+        }
+        # Expose `seen` for assertions.
+        app.singleton_class.send(:define_method, :seen_envs) { seen }
+        app
+    end
+
+    let(:middleware) { described_class.new(inner_app) }
+
+    # Each test installs a fresh anonymous Application subclass so we
+    # don't leak validators across examples.
+    let(:fake_application) { Class.new(Cuboid::Application) }
+
+    before(:each) do
+        @prev_application = Cuboid::Application.application
+        Cuboid::Application.application = fake_application
+    end
+
+    after(:each) do
+        Cuboid::Application.application = @prev_application
+    end
+
+    def env(headers = {})
+        # Minimum env Rack expects; HTTP_AUTHORIZATION is the only
+        # header the middleware reads.
+        {
+            'REQUEST_METHOD'    => 'POST',
+            'PATH_INFO'         => '/mcp',
+            'rack.input'        => StringIO.new('{}'),
+            'rack.errors'       => StringIO.new
+        }.merge(headers)
+    end
+
+    context 'when no validator is registered' do
+        it 'passes the request through unchanged' do
+            status, _, _ = middleware.call(env)
+            status.should == 200
+            inner_app.seen_envs.size.should == 1
+        end
+
+        it 'does not populate cuboid.mcp.auth' do
+            middleware.call(env)
+            inner_app.seen_envs.first['cuboid.mcp.auth'].should be_nil
+        end
+    end
+
+    context 'when a validator is registered' do
+        before do
+            fake_application.mcp_authenticate_with do |token|
+                token == 'good-token' ? { user: 'alice' } : nil
+            end
+        end
+
+        context 'and the Authorization header is missing' do
+            it 'responds 401 with invalid_request' do
+                status, headers, body = middleware.call(env)
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_request"'
+
+                JSON.parse(body.first)['error']['message'].should == 'invalid_request'
+            end
+
+            it 'never reaches the inner app' do
+                middleware.call(env)
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Authorization header is not a Bearer scheme' do
+            it 'responds 401 with invalid_request' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Basic dXNlcjpwYXNz')
+                )
+                status.should == 401
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Bearer token is wrong' do
+            it 'responds 401 with invalid_token' do
+                status, headers, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer not-the-token')
+                )
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_token"'
+
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Bearer token is correct' do
+            it 'passes the request through' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer good-token')
+                )
+                status.should == 200
+            end
+
+            it "stashes the validator's return value in env['cuboid.mcp.auth']" do
+                middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer good-token')
+                )
+
+                inner_app.seen_envs.first['cuboid.mcp.auth']
+                    .should == { user: 'alice' }
+            end
+
+            it 'is case-insensitive on the Bearer keyword' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'bearer good-token')
+                )
+                status.should == 200
+            end
+
+            it 'tolerates extra whitespace between Bearer and the token' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => "Bearer    good-token")
+                )
+                status.should == 200
+            end
+        end
+
+        context 'and the validator raises' do
+            before do
+                fake_application.mcp_authenticate_with do |_token|
+                    raise 'database is down'
+                end
+            end
+
+            it 'responds 401 (not 500) so internals never leak' do
+                status, headers, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer whatever')
+                )
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_token"'
+
+                inner_app.seen_envs.should be_empty
+            end
+        end
+    end
+
+    context 'when the validator is replaced after the middleware was instantiated' do
+        # Important property: the middleware reads the validator at
+        # request time, not at construction time, so applications can
+        # swap implementations during a long-running process.
+        it 'picks up the new validator on the next request' do
+            mw = middleware
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer x'))
+            status.should == 200   # no validator yet → pass-through
+
+            fake_application.mcp_authenticate_with { |t| t == 'x' }
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer x'))
+            status.should == 200
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer y'))
+            status.should == 401
+        end
+    end
+end