julewire-core 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caa063f4c5d3e39efe092df078811e29ec8ace41ab8b459d9f77276ba16bbee9
-  data.tar.gz: 1af9d19915aee53ff7abfcd6532cfb7d2f0aa836d1ee3a953f3f28217280b189
+  metadata.gz: 1706c04d0b1576af41d10b18b1e7288b2e9a80f3ab599298cf7fafefa9c6887b
+  data.tar.gz: 7e7a34704951f6e420dbf0a91d5eab8bad5ce099f4c70e5913e14d4f585ef8e4
 SHA512:
-  metadata.gz: a9577774281e4a434eed8862a93b08551ed8ef634f89bea232ce90165ccdc640275c039546a4df847bb01eba2d6049833957873d83c6dd13ec9b30f93328dbfb
-  data.tar.gz: c1e6ba4c5c6ecbd33cd611063de5a8f2f12f9062654ae8cce586c7d8a0dbb2c6dd41f183f4d061ff5905d1842f01b4cedaf6660ed8ef6b9a121e5891185754b0
+  metadata.gz: e5aaa3aeec9061a87b47d54a1b5a36ff4c7b901492f450325a9f3e91d10857700c648e837f88b50f0c3b9dd7c75f9810ebaaff196c8c96235d13a655788d234e
+  data.tar.gz: 2f7dc4648b5587e2e498005204b5af7e9f02757336d89524a2309a3515c22e08e151063d41b531a28f14efd3716d338817f090fb8cdfcb47e328bc2f746d42e2

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Unreleased
 
+## 1.1.3 - 2026-08-09
+
+- Add fail-loud pre-fork hooks with shared timeout budgets and reverse rollback.
+- Refresh development tooling and compatibility locksets.
+
 ## 1.1.2 - 2026-08-02
 
 - Refresh development and compatibility dependency locksets.

data/docs/contracts.md

@@ -9,7 +9,9 @@ These APIs are for application code and scripts:
 
 - Runtime configuration and lifecycle: `Julewire.configure`,
   `Julewire.config`, `Julewire.reset!`, `Julewire.flush`, `Julewire.close`,
-  `Julewire.after_fork!`, and `Julewire.health`.
+  `Julewire.before_fork!`, `Julewire.after_fork!`, and `Julewire.health`.
+- `Julewire::UnsafeForkError` for pre-fork safety failures that must abort
+  process creation.
 - `Julewire.runtime` for explicit secondary pipelines with independent
   configuration, destinations, processors, health, and lifecycle.
 - `Julewire.labels` for process labels shared by the active runtime.
@@ -91,7 +93,8 @@ but they are not intended as general application API:
 - `Julewire::Core::Integration::Values::Shape` for normalized timestamps, payload
   normalization, field appends, and source-location shaping.
 - `Julewire::Core::Integration::Lifecycle` for optional require containment and
-  process-local `after_fork` hooks.
+  process-local before/after-fork hooks. Hook identifiers are strict Symbols;
+  before-fork failures propagate while after-fork failures are health-contained.
 - `Julewire::Core::Integration` helper classes/modules for one-time ivar state,
   subscriber install helpers, event-subscriber health wrappers, config settings
   helpers, and subscription handles.

data/docs/extensions-and-api.md

@@ -281,10 +281,12 @@ return without raising unless they return `false`.
 dropped record; a plain `false` is a rejected record and calls `on_drop` with
 `:destination_rejected`.
 
-Custom destinations may also implement `after_fork!` for fork reset and
-`resource_identity` when multiple destinations share the same closeable
-resource. Transport adapters may expose adapter-specific lifecycle methods such
-as `reopen`.
+Custom destinations may implement `before_fork!(timeout:)` to drain and stop
+resources that cannot survive a process fork. Returning `false` rejects fork
+preparation; raising reports the failure and aborts preparation. Destinations
+may also implement `after_fork!` for fork reset and `resource_identity` when
+multiple destinations share the same closeable resource. Transport adapters
+may expose adapter-specific lifecycle methods such as `reopen`.
 
 The registered `:tail_sampling` destination kind wraps another destination for
 execution-level tail sampling. It buffers execution records until a summary
@@ -399,12 +401,17 @@ should accept keyword metadata.
 `contracts.md` owns the public facade inventory. This section covers usage
 details that extension and integration authors usually need.
 
+Integrations can register a fail-loud safety hook with
+`Julewire::Core::Integration::Lifecycle.register_before_fork(:integration_name,
+component: :component_name) { ... }`. It runs after destinations have quiesced;
+an exception aborts preparation and resumes destinations already prepared.
+
 Integrations that keep process-local state can register a reset hook with
 `Julewire::Core::Integration::Lifecycle.register_after_fork(:integration_name,
 component: :component_name) { ... }`. The hook runs after core has refreshed its
 own process-local state and after the active pipeline has forwarded
 `after_fork!` to destinations.
-Both hook names are strict integration identifiers: pass non-empty Symbols.
+All integration and component hook names are strict identifiers: pass non-empty Symbols.
 String or non-Symbol names raise at registration and are never normalized.
 
 `Julewire.observe_self!(runtime_name = :default, target: :meta)` starts a
@@ -431,6 +438,8 @@ Lifecycle:
 
 - `Integration::Lifecycle.require_optional(path)` for contained optional
   requires.
+- `Integration::Lifecycle.register_before_fork(:integration_name,
+  component: :component_name) { ... }` for fail-loud process preparation.
 - `Integration::Lifecycle.register_after_fork(:integration_name,
   component: :component_name) { ... }` for process-local integration state.
 - `Integration::IvarState` for idempotent framework subscriber state.

data/docs/outputs-and-lifecycle.md

@@ -151,6 +151,11 @@ attempts later destinations after a previous lifecycle call returns.
 out, `Julewire.close` returns `false`, but later emits still drop as
 `runtime_closed` until the next `configure` or `reset!`.
 
+`Julewire.before_fork!` gives destinations a bounded opportunity to drain and
+quiesce resources that cannot safely survive `Process.fork`. Preparation
+failures propagate so the process manager can abort the fork. Stop application
+work that can emit or create process-local workers before calling it.
+
 `Julewire.after_fork!` resets process-local counters, failure snapshots,
 current context, warning state, schedulers, and registries that cannot be
 shared with the child process. It also forwards `after_fork!` to destinations
@@ -159,6 +164,16 @@ registered through core. File, socket, queue, and async transports should
 reopen worker-local resources from their destination or output `after_fork!`
 method.
 
+Forking servers must pair the lifecycle calls around the actual fork:
+
+```ruby
+before_fork { Julewire.before_fork! }
+on_worker_boot { Julewire.after_fork! }
+```
+
+The parent may also call `Julewire.after_fork!` when it must resume destinations
+between worker forks.
+
 Core does not install an `at_exit` hook. Small scripts should call close from
 their own shutdown path:
 

data/lib/julewire/core/destinations/chaos_output.rb

@@ -48,6 +48,13 @@ module Julewire
           self
         end
 
+        def before_fork!(timeout: nil)
+          return self unless @output.respond_to?(:before_fork!)
+          return false if @output.before_fork!(timeout: timeout) == false
+
+          self
+        end
+
         def resource_identity = @output
 
         private

data/lib/julewire/core/destinations/collection.rb

@@ -9,6 +9,7 @@ module Julewire
           @destinations = destinations.dup.freeze
           @on_drop = on_drop
           @on_failure = on_failure
+          @prepared_destinations = []
         end
 
         class << self
@@ -41,6 +42,21 @@ module Julewire
           @destinations.each do |destination|
             call_destination_after_fork(destination)
           end
+          @prepared_destinations = []
+          self
+        end
+
+        def before_fork!(timeout:)
+          Validation.validate_timeout!(timeout, name: :timeout)
+          return self unless @prepared_destinations.empty?
+
+          prepare_destinations_before_fork(timeout)
+          self
+        end
+
+        def cancel_before_fork!
+          @prepared_destinations.reverse_each { call_destination_after_fork(it) }
+          @prepared_destinations = []
           self
         end
 
@@ -64,6 +80,23 @@ module Julewire
 
         private
 
+        def prepare_destinations_before_fork(timeout)
+          deadline = Scheduling::Deadline.for(timeout)
+          prepared = []
+          @destinations.each do |destination|
+            next unless destination.respond_to?(:before_fork!)
+
+            remaining = Scheduling::Deadline.remaining(deadline)
+            prepared << destination
+            result = destination.before_fork!(timeout: remaining)
+            raise Error, "destination #{destination_name(destination)} rejected before_fork" if result == false
+          end
+          @prepared_destinations = prepared
+        rescue StandardError
+          prepared.reverse_each { call_destination_after_fork(it) }
+          raise
+        end
+
         def call_lifecycle(method_name, timeout:, skip_resource_identities: nil)
           Validation.validate_timeout!(timeout, name: :timeout)
           call_lifecycle_safely(method_name, timeout, skip_resource_identities)
@@ -101,6 +134,8 @@ module Julewire
 
         def call_destination_after_fork(destination)
           destination.after_fork! if destination.respond_to?(:after_fork!)
+        rescue UnsafeForkError
+          raise
         rescue StandardError => e
           notify_failure(
             e,

data/lib/julewire/core/destinations/destination.rb

@@ -74,6 +74,8 @@ module Julewire
           initialize_tracking
           @output.after_fork!
           self
+        rescue UnsafeForkError
+          raise
         rescue StandardError => e
           notify_failure(
             e,
@@ -84,6 +86,12 @@ module Julewire
           self
         end
 
+        def before_fork!(timeout: nil)
+          return false if @output.before_fork!(timeout: timeout) == false
+
+          self
+        end
+
         def resource_identity
           @output.resource_identity
         end

data/lib/julewire/core/destinations/synchronized_output.rb

@@ -22,6 +22,17 @@ module Julewire
           self
         end
 
+        def before_fork!(timeout: nil)
+          result = @lifecycle_mutex.synchronize do
+            @mutex.synchronize do
+              @output.before_fork!(timeout: timeout) if @output.respond_to?(:before_fork!)
+            end
+          end
+          return false if result == false
+
+          self
+        end
+
         def output_class_name = @output.class.name
 
         def resource_identity = @output

data/lib/julewire/core/destinations/tail_sampling.rb

@@ -86,11 +86,28 @@ module Julewire
           @mutex.synchronize { initialize_buffer }
           @destination.after_fork! if @destination.respond_to?(:after_fork!)
           self
+        rescue UnsafeForkError
+          raise
         rescue StandardError => e
           record_failure(e, nil, phase: :after_fork)
           self
         end
 
+        def before_fork!(timeout: nil)
+          return self unless @destination.respond_to?(:before_fork!)
+
+          Validation.validate_timeout!(timeout, name: :timeout)
+          deadline = Scheduling::Deadline.for(timeout)
+          unless flush(timeout: Scheduling::Deadline.remaining(deadline))
+            raise Error, "tail-sampling destination could not flush before fork"
+          end
+
+          result = @destination.before_fork!(timeout: Scheduling::Deadline.remaining(deadline))
+          return false if result == false
+
+          self
+        end
+
         def resource_identity = self
 
         def health

data/lib/julewire/core/facade_methods.rb

@@ -152,6 +152,11 @@ module Julewire
 
       def labels = runtime.labels
       def after_fork! = runtime.after_fork!
+
+      def before_fork!(timeout: nil)
+        runtime.before_fork!(timeout: timeout)
+      end
+
       def reset! = runtime.reset_facade!
 
       def close(timeout: UNSET)

data/lib/julewire/core/integration/before_fork_hooks.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module Julewire
+  module Core
+    module Integration
+      module BeforeForkHooks
+        @entries = Concurrent::Map.new
+
+        class << self
+          def register(integration, component:, &callback)
+            raise ArgumentError, "block required" unless callback
+
+            HookNames.validate!(integration, name: :integration)
+            HookNames.validate!(component, name: :component)
+            entries[[integration, component]] = callback
+          end
+
+          def run
+            entries.each_value(&:call)
+            nil
+          end
+
+          private
+
+          attr_reader :entries
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/integration/fork_hooks.rb

@@ -15,8 +15,8 @@ module Julewire
           def register(integration, component:, &callback)
             raise ArgumentError, "block required" unless callback
 
-            validate_symbol_name!(integration, name: :integration)
-            validate_symbol_name!(component, name: :component)
+            HookNames.validate!(integration, name: :integration)
+            HookNames.validate!(component, name: :component)
             register_entry(integration, component, callback)
           end
 
@@ -43,11 +43,6 @@ module Julewire
               component: entry.component
             )
           end
-
-          def validate_symbol_name!(value, name:)
-            raise TypeError, "#{name} must be a Symbol" unless value.instance_of?(Symbol)
-            raise ArgumentError, "#{name} is required" if value == :""
-          end
         end
       end
     end

data/lib/julewire/core/integration/hook_names.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      module HookNames
+        class << self
+          def validate!(value, name:)
+            raise TypeError, "#{name} must be a Symbol" unless value.instance_of?(Symbol)
+            raise ArgumentError, "#{name} is required" if value == :""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/integration/lifecycle.rb

@@ -15,6 +15,10 @@ module Julewire
           def register_after_fork(integration, component:, &)
             ForkHooks.register(integration, component: component, &)
           end
+
+          def register_before_fork(integration, component:, &)
+            BeforeForkHooks.register(integration, component: component, &)
+          end
         end
       end
     end

data/lib/julewire/core/processing/pipeline.rb

@@ -69,6 +69,10 @@ module Julewire
           self
         end
 
+        def before_fork!(timeout:) = @destinations.before_fork!(timeout: timeout)
+
+        def cancel_before_fork! = @destinations.cancel_before_fork!
+
         def flush(timeout: nil)
           @destinations.flush(timeout: timeout)
         end

data/lib/julewire/core/runtime.rb

@@ -155,6 +155,19 @@ module Julewire
         RuntimeRegistry.reset_after_fork(primary: self)
       end
 
+      def before_fork!(timeout: nil)
+        reject_runtime_call_during_configure!(:before_fork!)
+        RuntimeRegistry.prepare_before_fork(primary: self, timeout: timeout)
+      end
+
+      def before_fork_runtime!(timeout:)
+        runtime_state.pipeline.before_fork!(timeout: timeout)
+      end
+
+      def cancel_before_fork_runtime!
+        runtime_state.pipeline.cancel_before_fork!
+      end
+
       def reset_after_fork_runtime!
         reset_after_fork_state!
         runtime_state.pipeline.after_fork!

data/lib/julewire/core/runtime_registry.rb

@@ -47,6 +47,22 @@ module Julewire
           runtimes.each(&:reset_after_fork_runtime!)
           Integration::ForkHooks.run
         end
+
+        def prepare_before_fork(primary:, timeout:)
+          Validation.validate_timeout!(timeout, name: :timeout)
+          runtimes = [primary] + @runtimes.get.values
+          deadline = Scheduling::Deadline.for(timeout)
+
+          begin
+            runtimes.each do |runtime|
+              runtime.before_fork_runtime!(timeout: Scheduling::Deadline.remaining(deadline))
+            end
+            Integration::BeforeForkHooks.run
+          rescue StandardError
+            runtimes.reverse_each(&:cancel_before_fork_runtime!)
+            raise
+          end
+        end
       end
     end
   end

data/lib/julewire/core/unsafe_fork_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    # @api integration_spi
+    class UnsafeForkError < Error; end
+  end
+end

data/lib/julewire/core/version.rb

@@ -2,6 +2,6 @@
 
 module Julewire
   module Core
-    VERSION = "1.1.2"
+    VERSION = "1.1.3"
   end
 end

data/lib/julewire/core.rb

@@ -65,6 +65,7 @@ module Julewire
   Tail = Core::Diagnostics::Tail
   TailSampling = Core::Destinations::TailSampling
   TextEncoder = Core::Serialization::TextEncoder
+  UnsafeForkError = Core::UnsafeForkError
 
   Core::Processing.register(:sampling) do |rate:, key: nil|
     Core::Processing::Sampling.head(rate: rate, key: key)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: julewire-core
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
 platform: ruby
 authors:
 - Alexander Grebennik
@@ -132,12 +132,14 @@ files:
 - lib/julewire/core/fields/stack_set.rb
 - lib/julewire/core/fields/static_labels.rb
 - lib/julewire/core/fields/summary_proxy.rb
+- lib/julewire/core/integration/before_fork_hooks.rb
 - lib/julewire/core/integration/configurable.rb
 - lib/julewire/core/integration/destination_health.rb
 - lib/julewire/core/integration/event_subscriber.rb
 - lib/julewire/core/integration/facade.rb
 - lib/julewire/core/integration/fork_hooks.rb
 - lib/julewire/core/integration/health.rb
+- lib/julewire/core/integration/hook_names.rb
 - lib/julewire/core/integration/ivar_state.rb
 - lib/julewire/core/integration/lifecycle.rb
 - lib/julewire/core/integration/protocol.rb
@@ -194,6 +196,7 @@ files:
 - lib/julewire/core/serialization/value_copy.rb
 - lib/julewire/core/serialization/value_traversal.rb
 - lib/julewire/core/testing.rb
+- lib/julewire/core/unsafe_fork_error.rb
 - lib/julewire/core/validation.rb
 - lib/julewire/core/version.rb
 - lib/julewire/error.rb