julewire-ractor 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d166b07720f0d37eb7b80d8bc7c3e5bcc3b00c83c14f2ce991e5931bbf0272b
-  data.tar.gz: 89bcff708f1fd8c0a22843ce4c74a8e49d99f39bed8f82f328d0115ba20216e9
+  metadata.gz: a0b295ac53d6eea75e9313e6274e039cf88f0c6b9d990b3152035f7cd193b3cf
+  data.tar.gz: d3992f7083c8b612d59d8104dd46d76f58c94db851c7c4a8cfa090de45de8618
 SHA512:
-  metadata.gz: 91bd26a0399339393e0c075ae1752180ae058b449af0563b4a044073d62f5506b86dca06b6e649cc50c024a9a289bc0ca2142aea51a703fc349e45e196d0a893
-  data.tar.gz: 12dc746f9b15eeadc5c26f3566f83e042317632fee4fbed5281265a0f9ace8ce20ced5e1605d8a425158bcaf71de2b9ee985b8c8977766cbaf6101da128c486b
+  metadata.gz: 819d50753851ad531bb413f593173b6c4b6cd08fda9f5a1bfdfcd3f72d6c9ef12aebe980cbdde9bed2f9f7234865a39162b3e488b8ef05544f3703403900a65a
+  data.tar.gz: 6880dca6536397902cd131d0f9f2243336bde72df17ddbcbd89918f11429795d0eba5924acf58c651a3edcad341718bd2ccb154bf26f2313a85dcdfb3e415008

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## Unreleased
 
+## 1.1.0 - 2026-07-20
+
+- Require finite request timeouts and bound destination worker startup and
+  shutdown so lifecycle operations cannot wait forever.
+- Harden queue accounting, fanout validation, worker stats, and Ractor-safe
+  reply-timeout cleanup.
+- Discard inherited Ractor handles before rebuilding destination workers in a
+  forked child process.
+- Normalize application emit input before strict bridge serialization while
+  keeping integration-owned emits on a non-normalizing Symbol-key path.
+- Require julewire-core 1.1.0.
+
+## 1.0.1 - 2026-06-25
+
+- Reserve ractor destination queue slots before send and roll them back on
+  send failure.
+- Count impossible queue-slot over-release events for destination health
+  debugging.
+- Require julewire-core 1.0.1.
+
 ## 1.0.0 - 2026-06-21
 
 - Initial release: Ruby 4 ractor bridge, child-runtime forwarding, remote

data/docs/bridge.md

@@ -29,11 +29,18 @@ Values are serialized before crossing the ractor boundary. Parent-side
 processors see log-safe scalar values rather than the child object's original
 identity or class.
 
+The child public facade canonicalizes application input, including nested
+String keys and unknown top-level payload fields, before strict bridge
+serialization. Integration facade emits use a separate owned path: every key
+must already be a Symbol and unknown record fields are rejected. The serializer
+never decides which contract applies and never normalizes bridge data.
+
 The serialized envelope is a ractor concern. Core keeps only the narrow
 `emit_envelope` hook that accepts already-extracted input, context, carry, and
 a scope snapshot. Payload parsing and scope reconstruction stay in this gem.
-That hook is parent-runtime SPI; the child `RemoteRuntime` exposes the normal
-facade emit methods instead of a detached-envelope API.
+That hook is parent-runtime SPI; the bridge marks ractor wire data as owned, and
+the child `RemoteRuntime` exposes the normal facade emit methods instead of a
+detached-envelope API.
 
 ## Available in Child
 
@@ -105,15 +112,28 @@ synchronously. The destination then sends each immutable record to a worker
 ractor. The worker owns formatter, encoder, byte-limit checks, and output
 writes.
 
+All hashes exchanged between Julewire gems, the parent bridge, and worker
+ractors use Symbol keys at every depth. This is an internal protocol, not an
+input-normalization boundary: String keys and malformed or unknown commands are
+protocol errors. They are raised and recorded at the owning bridge/worker
+lifecycle boundary instead of being converted, ignored, or replaced with empty
+values. String-key normalization remains limited to public application input
+and decoded propagation carriers.
+
 The destination has a bounded parent-side in-flight queue. When `max_queue` is
 full, new records are dropped and counted in destination health. `flush` sends a
 request to the worker and waits for all earlier records to finish. `close`
 flushes or closes the worker-owned output and stops the worker.
 
-Unlike direct core destinations, ractor-backed destinations treat
-`flush(timeout: nil)` and `close(timeout: nil)` as the configured request timeout
-instead of an unbounded wait. Worker ractors can die or stop replying; the parent
-must not park forever while draining diagnostics.
+Unlike direct core destinations, ractor-backed destinations require a finite
+configured request timeout. `flush(timeout: nil)` and `close(timeout: nil)` use
+that configured timeout instead of creating an unbounded wait. Worker ractors
+can die or stop replying; the parent observes worker termination as well as the
+reply and must not park forever while draining diagnostics.
+
+Worker startup has a fixed one-second bound, independent of the request timeout.
+A worker that does not hand back its command port raises
+`Julewire::Core::Error` instead of blocking construction.
 
 Formatter, encoder, and output must be ractor-copyable or shareable. Avoid
 singleton-method/proc-backed output objects; plain class instances with

data/julewire-ractor.gemspec

@@ -32,6 +32,6 @@ Gem::Specification.new do |spec|
   spec.executables = []
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "julewire-core", ">= 1.0"
+  spec.add_dependency "julewire-core", ">= 1.1.0"
   spec.add_dependency "zeitwerk", ">= 2.8.1"
 end

data/lib/julewire/ractor/bridge/bridge_thread.rb

@@ -27,7 +27,7 @@ module Julewire
             rescue StandardError => e
               bridge_error = e
               warn_bridge_stopped(e)
-              Julewire::Ractor::PortLifecycle.close(port)
+              PortLifecycle.close(port)
               break
             end
           ensure
@@ -35,7 +35,7 @@ module Julewire
           end
 
           def close_message?(message)
-            message.is_a?(Hash) && message[:command] == :close
+            message.instance_of?(Hash) && message[:command] == :close
           end
 
           def monitor_message?(message)

data/lib/julewire/ractor/bridge/stats.rb

@@ -40,6 +40,7 @@ module Julewire
               experimental: true,
               failure_count: @failure_count.value,
               last_error_class: @last_error.get&.fetch(:class),
+              last_error_message: @last_error.get&.fetch(:message),
               messages: @message_count.value,
               started_threads: @started_threads.value,
               stopped_threads: @stopped_threads.value
@@ -66,7 +67,7 @@ module Julewire
 
           def record_failure(error)
             @failure_count.increment
-            @last_error.set({ class: error.class.name })
+            @last_error.set({ class: error.class.name, message: error.message })
           end
         end
       end

data/lib/julewire/ractor/bridge.rb

@@ -17,14 +17,14 @@ module Julewire
 
         def enabled? = ENABLED.get
 
-        def spawn(args:, name:, runtime:, &)
+        def start(args:, name:, runtime:, &)
           unless enabled?
             raise Core::Error, "Julewire.ractor is experimental; call Julewire.enable_experimental_ractor! first"
           end
 
           RuntimeValidation.validate!(runtime)
 
-          envelope = Core::Propagation.capture
+          envelope = Core::Propagation.capture_local
           body = ::Ractor.shareable_proc(&)
           port = ::Ractor::Port.new
           ractor = spawn_ractor(
@@ -58,19 +58,23 @@ module Julewire
         def monitor_ractor(ractor)
           return unless ractor
 
-          ::Ractor::Port.new.tap { ractor.monitor(it) }
+          monitor_port = ::Ractor::Port.new
+          return unless monitor_port.instance_of?(::Ractor::Port)
+
+          ractor.monitor(monitor_port)
+          monitor_port
         rescue StandardError
           nil
         end
 
         def spawn_ractor(args:, name:, port:, envelope:, body:, emit_non_standard_exception_summaries:)
-          # :nocov:
+          # simplecov:disable
           ::Ractor.new(port, envelope, body, emit_non_standard_exception_summaries, *args, name: name) do
             |bridge_port, captured_envelope, callable, emit_non_standard_summaries, *call_args|
-            Julewire::Core::RuntimeLocator.current = Julewire::Ractor::RemoteRuntime.new(
+            Core::RuntimeLocator.current = RemoteRuntime.new(
               port: bridge_port, emit_non_standard_exception_summaries: emit_non_standard_summaries
             )
-            Julewire::Core::Propagation.restore(captured_envelope) do
+            Core::Propagation.restore(captured_envelope, owned: true) do
               callable.call(*call_args)
             end
           ensure
@@ -81,12 +85,10 @@ module Julewire
               nil
             end
           end
-          # :nocov:
+          # simplecov:enable
         end
 
         def handle_message(runtime, message)
-          return unless message.is_a?(Hash)
-
           response = dispatch(runtime, message)
           reply_to(message, response)
         rescue StandardError => e
@@ -95,7 +97,9 @@ module Julewire
         end
 
         def dispatch(runtime, message)
-          case message[:command]
+          validate_message!(message)
+          command = message.fetch(:command)
+          case command
           when :emit
             dispatch_emit(runtime, message, enforce_level: true)
           when :emit_without_level
@@ -105,7 +109,9 @@ module Julewire
               RemoteSummaryRecord.new(RemotePayload.hash_value(message, :payload))
             )
           when :flush
-            runtime.flush(timeout: message.dig(:payload, :timeout))
+            runtime.flush(timeout: message.fetch(:payload).fetch(:timeout))
+          else
+            raise ArgumentError, "unknown ractor bridge command: #{command.inspect}"
           end
         end
 
@@ -113,12 +119,18 @@ module Julewire
           payload = RemotePayload.hash_value(message, :payload)
           arguments = RemotePayload.extract(payload)
           arguments[:enforce_level] = false unless enforce_level
-          runtime.emit_envelope(**arguments)
+          runtime.emit_envelope(**arguments, owned: true)
         end
 
         def reply_to(message, response)
+          return unless message.is_a?(Hash)
+
           reply = message[:reply]
-          reply.send(response) if reply_port?(reply)
+          return unless reply
+
+          raise TypeError, "ractor bridge reply must be a Ractor::Port" unless reply_port?(reply)
+
+          reply.send(response)
         rescue StandardError => e
           Stats.message_failed(e)
           nil
@@ -127,6 +139,10 @@ module Julewire
         def reply_port?(reply)
           reply.is_a?(::Ractor::Port)
         end
+
+        def validate_message!(message)
+          Core::Integration::Protocol.validate_symbol_hash(message)
+        end
       end
     end
   end

data/lib/julewire/ractor/child_stats.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "concurrent/atomic/atomic_fixnum"
+require "concurrent/atomic/atomic_reference"
+
 module Julewire
   module Ractor
     class ChildStats
@@ -13,8 +16,8 @@ module Julewire
       private_constant :COUNTER_KEYS
 
       def initialize
-        @mutex = Mutex.new
-        @counters = COUNTER_KEYS.to_h { [it, 0] }
+        @counters = COUNTER_KEYS.to_h { [it, Concurrent::AtomicFixnum.new] }
+        @last_error_class = Concurrent::AtomicReference.new
       end
 
       def message_sent = increment(:messages_sent)
@@ -32,34 +35,27 @@ module Julewire
       def request_timed_out = increment(:requests_timed_out)
 
       def reset!
-        @mutex.synchronize do
-          @counters.each_key { @counters[it] = 0 }
-          @last_error_class = nil
-        end
-        nil
+        @counters.each_value { it.value = 0 }
+        @last_error_class.set(nil)
       end
 
       def to_h
-        @mutex.synchronize do
-          {
-            counts: @counters.dup.freeze,
-            last_error_class: @last_error_class
-          }.compact.freeze
-        end
+        {
+          counts: @counters.transform_values(&:value).freeze,
+          last_error_class: @last_error_class.get
+        }.compact.freeze
       end
 
       private
 
       def increment(key)
-        @mutex.synchronize { @counters[key] += 1 }
+        @counters.fetch(key).increment
         nil
       end
 
       def record_error(key, error)
-        @mutex.synchronize do
-          @counters[key] += 1
-          @last_error_class = error.class.name
-        end
+        @counters.fetch(key).increment
+        @last_error_class.set(error.class.name)
         nil
       end
     end