julewire-ractor 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d166b07720f0d37eb7b80d8bc7c3e5bcc3b00c83c14f2ce991e5931bbf0272b
+  data.tar.gz: 89bcff708f1fd8c0a22843ce4c74a8e49d99f39bed8f82f328d0115ba20216e9
+SHA512:
+  metadata.gz: 91bd26a0399339393e0c075ae1752180ae058b449af0563b4a044073d62f5506b86dca06b6e649cc50c024a9a289bc0ca2142aea51a703fc349e45e196d0a893
+  data.tar.gz: 12dc746f9b15eeadc5c26f3566f83e042317632fee4fbed5281265a0f9ace8ce20ced5e1605d8a425158bcaf71de2b9ee985b8c8977766cbaf6101da128c486b

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Unreleased
+
+## 1.0.0 - 2026-06-21
+
+- Initial release: Ruby 4 ractor bridge, child-runtime forwarding, remote
+  summaries, fanout, and ractor destination workers.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexander Grebennik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# Julewire Ractor
+
+`julewire-ractor` is the experimental Ractor bridge for Julewire.
+
+It requires Ruby 4.0 or newer. Code inside `Julewire.ractor` can emit through
+the parent runtime while the parent keeps configuration, processors,
+destinations, outputs, and labels authoritative.
+
+## Install
+
+```ruby
+gem "julewire-ractor"
+```
+
+## Quickstart
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(:default, output: $stdout)
+end
+
+Julewire.enable_experimental_ractor!
+
+ractor = Julewire.ractor do
+  Julewire.emit(message: "from ractor")
+  Julewire.flush
+end
+
+ractor.value
+```
+
+This is best-effort logging infrastructure, not durable transport.
+
+Child-side send failures are visible from inside the child:
+
+```ruby
+Julewire.ractor do
+  Julewire.emit(message: "from ractor")
+  Julewire::Ractor.child_stats
+end.value
+```
+
+For CPU-heavy formatting/encoding experiments, the gem can make the normal
+`:default` destination kind ractor-backed. The parent pipeline stays synchronous
+up to the immutable record boundary, then the worker ractor owns formatter,
+encoder, and output:
+
+```ruby
+Julewire::Ractor.enable_default_destination_workers!
+
+Julewire.configure do |config|
+  config.destinations.use(:default, output: MyRactorCopyableOutput.new)
+end
+```
+
+Use the explicit `:ractor` kind when a second ractor-backed destination should
+sit beside another destination. Formatter, encoder, and output must be
+ractor-copyable or shareable under Ruby's Ractor rules.
+
+## Docs
+
+- [Bridge](docs/bridge.md)

data/docs/bridge.md

@@ -0,0 +1,159 @@
+# Bridge
+
+`julewire-ractor` adds two facade methods:
+
+- `Julewire.enable_experimental_ractor!`
+- `Julewire.ractor`
+
+The opt-in is deliberate. Ractor support is Ruby-version-sensitive, bridge
+emits use an unbounded port queue, and the bridge is outside the stable core
+application API. Core documents the narrow Bridge SPI used by this gem.
+
+## Flow
+
+```text
+child ractor emit
+  -> remote runtime serializes input, context, carry, and scope
+  -> Ractor::Port message
+  -> parent bridge thread
+  -> bridge reconstructs a core scope snapshot
+  -> parent runtime emit_envelope
+  -> core processors, destinations, formatter, encoder, output
+```
+
+The parent runtime owns all policy. The child does not install configuration,
+outputs, processors, labels, or event definitions. Parent static labels still
+apply to records emitted by the child.
+
+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 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.
+
+## Available in Child
+
+`Julewire.emit` sends a fire-and-forget message to the parent bridge.
+Child-side emits serialize and cross the ractor port before the parent runtime
+applies its level threshold.
+
+Child-side send loss is visible inside the child runtime:
+
+```ruby
+Julewire::Ractor.child_stats
+Julewire::Ractor.reset_child_stats!
+```
+
+These counters cover child-to-parent port sends, lifecycle requests, request
+timeouts, and the last local send error class. Parent bridge health still lives
+at `Julewire::Ractor.health`.
+
+Integration code can call `RuntimeLocator.current.emit_without_level` inside
+the child when it has already applied its own level gate.
+
+`Julewire.with_execution`, `Julewire.context`, `Julewire.carry`,
+`Julewire.attributes`, and `Julewire.summary` work against the child-local
+context store. Summary records are sent to the parent when execution scopes
+finish.
+
+`Julewire.flush` sends a request/reply message to the parent bridge. The default
+remote request timeout is one second. `timeout: nil` remains unbounded.
+
+`Julewire.reset!` clears only the child-local context store.
+
+## Parent Only
+
+- `Julewire.configure`
+- `Julewire.config`
+- `Julewire.labels`
+- `Julewire.health`
+- `Julewire.close`
+
+These belong to the parent runtime.
+
+## Health
+
+Bridge health is available through:
+
+```ruby
+Julewire::Ractor.health
+```
+
+It reports bridge thread counts, received message count, and the last bridge
+thread error class. It is diagnostic state, not a delivery guarantee.
+
+## Ractor Destination
+
+`julewire-ractor` can make the normal `:default` destination kind ractor-backed:
+
+```ruby
+Julewire::Ractor.enable_default_destination_workers!
+
+Julewire.configure do |config|
+  config.destinations.use(:default, output: MyRactorCopyableOutput.new)
+end
+```
+
+It also registers `:ractor` for additional ractor-backed destinations.
+
+The parent pipeline still normalizes, processes, and freezes records
+synchronously. The destination then sends each immutable record to a worker
+ractor. The worker owns formatter, encoder, byte-limit checks, and output
+writes.
+
+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.
+
+Formatter, encoder, and output must be ractor-copyable or shareable. Avoid
+singleton-method/proc-backed output objects; plain class instances with
+ractor-safe state are the intended shape.
+Record payload values sent through `Julewire::Ractor::Destination` must also be
+ractor-copyable or shareable. Non-copyable values are dropped at the parent-side
+send boundary and counted as `send_error`.
+
+Use `Julewire::Ractor::Fanout` when one core destination should fan out to
+multiple ractor-backed destination workers:
+
+```ruby
+config.destinations.add(
+  Julewire::Ractor.fanout(
+    destinations: [
+      { name: :stdout, output: $stdout },
+      { name: :audit, output: audit_io }
+    ]
+  )
+)
+```
+
+The parent pipeline still processes once. Each fanout child formats, encodes,
+and writes in its own destination worker.
+
+## Raw Ractors
+
+Raw `Ractor.new` does not install the bridge. Use `Julewire.ractor` when child
+code needs Julewire facade calls to reach the parent runtime.
+
+## Forking
+
+Do not fork a process with live Julewire ractor bridges. After a process fork,
+core calls the ractor integration after-fork hook and clears inherited bridge
+thread health. Create new ractors in the worker process after fork.
+
+## Runtime Promise
+
+Inside `Julewire.ractor`, `Julewire.emit` is best-effort fire-and-forget. Use
+`Julewire.flush` when the child wants to ask the parent bridge to drain.
+
+The bridge uses Ruby's ractor message-passing model and an unbounded
+`Ractor::Port`. It should not be used as a reliable inter-ractor queue.

data/docs/development.md

@@ -0,0 +1,42 @@
+# Development
+
+Install dependencies:
+
+```sh
+bundle install
+```
+
+Run the default checks:
+
+```sh
+bundle exec rake
+```
+
+The default task runs:
+
+- Minitest
+- RuboCop
+- Flay
+- Debride
+- Bundler Audit
+
+## Coverage
+
+Tests can run with SimpleCov:
+
+```sh
+COVERAGE=true bundle exec rake test
+```
+
+The gem supports Ruby 4.0 and newer. Tests exercise the Ruby 4.0
+`Ractor::Port` bridge directly.
+
+## Lockfile
+
+`Gemfile.lock` is committed for reproducible local development and CI. Runtime
+dependencies still belong in the gemspec.
+
+## Packaging Notes
+
+The gemspec is the runtime dependency contract. `Gemfile` is for development
+tooling and the local path dependency on `julewire-core`.

data/julewire-ractor.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/julewire/ractor/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "julewire-ractor"
+  spec.version = Julewire::Ractor::VERSION
+  spec.authors = ["Alexander Grebennik"]
+  spec.email = ["slbug@users.noreply.github.com", "sl.bug.sl@gmail.com"]
+
+  spec.summary = "Experimental Ractor bridge for julewire-core."
+  spec.description = "Opt-in Ractor bridge that forwards records from worker ractors to a parent Julewire runtime."
+  spec.homepage = "https://github.com/slbug/julewire"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 4.0"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/slbug/julewire/tree/main/gems/ractor"
+  spec.metadata["changelog_uri"] = "https://github.com/slbug/julewire/blob/main/gems/ractor/CHANGELOG.md"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "CHANGELOG.md",
+      "LICENSE.txt",
+      "README.md",
+      "docs/**/*.md",
+      "julewire-ractor.gemspec",
+      "lib/**/*.rb"
+    ]
+  end
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "julewire-core", ">= 1.0"
+  spec.add_dependency "zeitwerk", ">= 2.8.1"
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    module Bridge
+      module BridgeThread
+        THREAD_NAME = "julewire-ractor-bridge"
+        MONITOR_MESSAGES = %i[aborted exited].freeze
+
+        class << self
+          def start(port:, monitor_port: nil, &handler)
+            Thread.new { run(port: port, monitor_port: monitor_port, handler: handler) }.tap do |thread|
+              thread.name = THREAD_NAME
+              thread.report_on_exception = true
+            end
+          end
+
+          def run(port:, handler:, monitor_port: nil)
+            bridge_error = nil
+            Stats.bridge_started
+            loop do
+              message = receive_message(port, monitor_port)
+              Stats.message_received
+              break if close_message?(message) || monitor_message?(message)
+
+              handler.call(message)
+            rescue StandardError => e
+              bridge_error = e
+              warn_bridge_stopped(e)
+              Julewire::Ractor::PortLifecycle.close(port)
+              break
+            end
+          ensure
+            Stats.bridge_stopped(bridge_error)
+          end
+
+          def close_message?(message)
+            message.is_a?(Hash) && message[:command] == :close
+          end
+
+          def monitor_message?(message)
+            MONITOR_MESSAGES.include?(message)
+          end
+
+          def receive_message(port, monitor_port)
+            return port.receive unless monitor_port
+
+            _selected_port, message = ::Ractor.select(port, monitor_port)
+            message
+          end
+
+          def warn_bridge_stopped(error)
+            Warning.warn("julewire ractor bridge stopped: #{error.class}\n")
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Ractor
+    module Bridge
+      module RuntimeValidation
+        REQUIRED_METHODS = %i[
+          emit_envelope
+          emit_summary_record
+          flush
+        ].freeze
+
+        class << self
+          def validate!(runtime)
+            missing = REQUIRED_METHODS.reject { runtime.respond_to?(it) }
+            return if missing.empty?
+
+            raise ArgumentError, "Julewire.ractor requires a bridge-compatible runtime " \
+                                 "(missing: #{missing.join(", ")})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_fixnum"
+require "concurrent/atomic/atomic_reference"
+
+module Julewire
+  module Ractor
+    module Bridge
+      module Stats
+        @active_threads = Concurrent::AtomicFixnum.new(0)
+        @failure_count = Concurrent::AtomicFixnum.new(0)
+        @last_error = Concurrent::AtomicReference.new
+        @message_count = Concurrent::AtomicFixnum.new(0)
+        @started_threads = Concurrent::AtomicFixnum.new(0)
+        @stopped_threads = Concurrent::AtomicFixnum.new(0)
+
+        class << self
+          def bridge_started
+            @active_threads.increment
+            @started_threads.increment
+          end
+
+          def bridge_stopped(error = nil)
+            @active_threads.decrement if @active_threads.value.positive?
+            @stopped_threads.increment
+            record_failure(error) if error
+          end
+
+          def message_received
+            @message_count.increment
+          end
+
+          def message_failed(error)
+            record_failure(error)
+          end
+
+          def health
+            {
+              active_threads: @active_threads.value,
+              experimental: true,
+              failure_count: @failure_count.value,
+              last_error_class: @last_error.get&.fetch(:class),
+              messages: @message_count.value,
+              started_threads: @started_threads.value,
+              stopped_threads: @stopped_threads.value
+            }.compact
+          end
+
+          def reset!
+            # Active bridge threads are live state; reset history without
+            # forcing a running bridge to later decrement a cleared counter.
+            @failure_count.value = 0
+            @last_error.set(nil)
+            @message_count.value = 0
+            @started_threads.value = 0
+            @stopped_threads.value = 0
+            nil
+          end
+
+          def after_fork!
+            @active_threads.value = 0
+            reset!
+          end
+
+          private
+
+          def record_failure(error)
+            @failure_count.increment
+            @last_error.set({ class: error.class.name })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/ractor/bridge.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_reference"
+
+module Julewire
+  module Ractor
+    # @api internal
+    # Experimental bridge that forwards ractor records back to a parent runtime.
+    module Bridge
+      ENABLED = Concurrent::AtomicReference.new(false)
+      private_constant :ENABLED
+
+      class << self
+        def opt_in!
+          ENABLED.set(true)
+        end
+
+        def enabled? = ENABLED.get
+
+        def spawn(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
+          body = ::Ractor.shareable_proc(&)
+          port = ::Ractor::Port.new
+          ractor = spawn_ractor(
+            args: args,
+            name: name,
+            port: port,
+            envelope: envelope,
+            body: body,
+            emit_non_standard_exception_summaries: runtime.config.emit_non_standard_exception_summaries
+          )
+          start_bridge(port: port, runtime: runtime, ractor: ractor)
+          ractor
+        end
+
+        def health = Stats.health
+
+        def reset!
+          ENABLED.set(false)
+          Stats.reset!
+        end
+
+        def after_fork! = Stats.after_fork!
+
+        private
+
+        def start_bridge(port:, runtime:, ractor: nil)
+          monitor_port = monitor_ractor(ractor)
+          BridgeThread.start(port: port, monitor_port: monitor_port) { handle_message(runtime, it) }
+        end
+
+        def monitor_ractor(ractor)
+          return unless ractor
+
+          ::Ractor::Port.new.tap { ractor.monitor(it) }
+        rescue StandardError
+          nil
+        end
+
+        def spawn_ractor(args:, name:, port:, envelope:, body:, emit_non_standard_exception_summaries:)
+          # :nocov:
+          ::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(
+              port: bridge_port, emit_non_standard_exception_summaries: emit_non_standard_summaries
+            )
+            Julewire::Core::Propagation.restore(captured_envelope) do
+              callable.call(*call_args)
+            end
+          ensure
+            # Tell the bridge thread to exit even when the child body raises.
+            begin
+              bridge_port.send({ command: :close })
+            rescue StandardError
+              nil
+            end
+          end
+          # :nocov:
+        end
+
+        def handle_message(runtime, message)
+          return unless message.is_a?(Hash)
+
+          response = dispatch(runtime, message)
+          reply_to(message, response)
+        rescue StandardError => e
+          Stats.message_failed(e)
+          reply_to(message, nil)
+        end
+
+        def dispatch(runtime, message)
+          case message[:command]
+          when :emit
+            dispatch_emit(runtime, message, enforce_level: true)
+          when :emit_without_level
+            dispatch_emit(runtime, message, enforce_level: false)
+          when :emit_record
+            runtime.emit_summary_record(
+              RemoteSummaryRecord.new(RemotePayload.hash_value(message, :payload))
+            )
+          when :flush
+            runtime.flush(timeout: message.dig(:payload, :timeout))
+          end
+        end
+
+        def dispatch_emit(runtime, message, enforce_level:)
+          payload = RemotePayload.hash_value(message, :payload)
+          arguments = RemotePayload.extract(payload)
+          arguments[:enforce_level] = false unless enforce_level
+          runtime.emit_envelope(**arguments)
+        end
+
+        def reply_to(message, response)
+          reply = message[:reply]
+          reply.send(response) if reply_port?(reply)
+        rescue StandardError => e
+          Stats.message_failed(e)
+          nil
+        end
+
+        def reply_port?(reply)
+          reply.is_a?(::Ractor::Port)
+        end
+      end
+    end
+  end
+end