cuboid 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51212d2d1adc9ffb33f4838212d9bbddcb88466a12e8e1b5522a2baff6b233f0
-  data.tar.gz: e4721af5a566266882fea5320129f58d01c667a03956d79300a3b3a3b652edc1
+  metadata.gz: 28dd253a7fd5dc33e5f8d62a9ae2fae905a46a786bb21d57cb8c47f9792ba821
+  data.tar.gz: 319fcbba6a3a5ed6b41eec3dbcde53c7e4f7d43c658df4657e660339e2198933
 SHA512:
-  metadata.gz: c2cec6fd1a808c0fc1473a61a7f93a0e3ed7a974562df6c44b55e4e450461cef29320d82a252de344eb1d21ceec94f6e4e8bd7bfd7f7301ccb05f15561c3255e
-  data.tar.gz: c7f15a7207fa170a0874c9931a75533bb6ba37dda9a0b2a0b2946a019ea90f16258b5051ab523fbc5ca59795c0f948ff18fac1434c55ca7ae7b860198576b94e
+  metadata.gz: 859207bc319b54b3eaff619dcdc1aa770e7136fe30cea8dcc86556595a204711190c0a463398038ee30a5ce8a9be25eea3637fc79676daa150b045f8b4ab880e
+  data.tar.gz: 64c5901b28b942d2771dca8ec22af4ad893a8d11c53acf1d094a7c65882c9199105d18b5bbc8872b094a1447896d07897b1bf1db8b85e808a569a2ae92e19cbc

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

@@ -5,9 +5,8 @@ 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
+# 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
 
@@ -19,24 +18,8 @@ module InstanceHelpers
         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
-
-        pruned = scheduler.failed.keys | scheduler.completed.keys
-        super
-        pruned.each { |id| session.delete id }
-    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]

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

@@ -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
 
@@ -114,8 +113,6 @@ module Instances
 
             instances.delete( id ).close
 
-            session.delete params[:instance]
-
             json nil
         end
 

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
@@ -294,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
+
+        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 ))
 
-        options = {
+        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/version

@@ -1 +1 @@
-0.4
+0.5

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuboid
 version: !ruby/object:Gem::Version
-  version: '0.4'
+  version: '0.5'
 platform: ruby
 authors:
 - Tasos Laskos
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print