woods 1.6.1 → 2.0.0.beta2

data/lib/woods/index_artifact.rb

@@ -4,6 +4,7 @@ require 'pathname'
 require 'json'
 require 'fileutils'
 require 'tempfile'
+require 'woods/atomic_file'
 
 module Woods
   # Whole Value for the on-disk artifact layout under +output_dir+.
@@ -75,23 +76,57 @@ module Woods
     def latest_dump_path
       return nil unless latest_pointer_path.exist?
 
-      dirname = latest_pointer_path.read.strip
+      # AtomicFile.read, never a bare Pathname#read (H1): the pointer sits on
+      # the load_or_empty path of both snapshotters, and a bare read tags its
+      # content with Encoding.default_external. The pointer content is
+      # generated (a strftime dirname), so ASCII by construction — the guard
+      # keeps the pattern out of the artifact-read surface rather than fixing
+      # an observed failure.
+      dirname = Woods::AtomicFile.read(latest_pointer_path).strip
       return nil if dirname.empty?
 
       dir = dumps_root.join(dirname)
       dir.exist? ? dir : nil
     end
 
-    # Reads and parses +woods.json+, returning the raw hash.
+    # Path to a config snapshot embedded inside a dump directory.
     #
-    # Returns +nil+ when the file does not exist. Schema-version validation
-    # is the caller's responsibility (typically {Woods::ResolvedConfig.from_hash}).
+    # The vector/metadata dump and the root +woods.json+ used to be written
+    # as two independent atomic operations (dump, then +write_config+, then
+    # +promote+) — a crash between +write_config+ and +promote+ published a
+    # new config against the old dump. Writing the config snapshot here, as
+    # part of the dump itself, and promoting is what makes +promote+ the
+    # single commit point for both. See {#read_config}.
+    #
+    # @param dump_dir [Pathname, String] a dump directory (need not yet be promoted)
+    # @return [Pathname]
+    def dump_config_path(dump_dir)
+      Pathname.new(dump_dir.to_s).join('woods.json')
+    end
+
+    # Reads and parses the resolved config, returning the raw hash.
+    #
+    # Prefers the config embedded in the *promoted* dump ({#latest_dump_path})
+    # over the root +woods.json+ — the dump's own copy is guaranteed to
+    # describe the vectors that dump holds, since {#promote} is the single
+    # commit point for both. Falls back to the root file for two cases: no
+    # dump has been promoted yet, or the promoted dump predates this fix and
+    # carries no embedded config at all (back-compat for existing dumps).
+    #
+    # Returns +nil+ when neither is present. Schema-version validation is the
+    # caller's responsibility (typically {Woods::ResolvedConfig.from_hash}).
     #
     # @return [Hash, nil]
     def read_config
+      dump_dir = latest_dump_path
+      if dump_dir
+        embedded = dump_config_path(dump_dir)
+        return JSON.parse(embedded.read(encoding: Encoding::UTF_8)) if embedded.exist?
+      end
+
       return nil unless config_path.exist?
 
-      JSON.parse(config_path.read)
+      JSON.parse(config_path.read(encoding: Encoding::UTF_8))
     end
 
     # Creates a new timestamped dump directory and returns its path.
@@ -112,6 +147,35 @@ module Woods
       dir
     end
 
+    # Validate that an existing dump directory resolves beneath
+    # {#dumps_root}. Both paths are resolved through realpath before the
+    # boundary comparison, so a symlinked alias of the artifact root remains
+    # valid while a child symlink escaping the root is rejected.
+    #
+    # This is the shared write/promotion boundary for the Snapshotter pair and
+    # {#promote}; keeping it here prevents their path policies from drifting.
+    #
+    # @param dump_dir [Pathname, String] existing dump directory to validate
+    # @param allow_root [Boolean] whether +dumps_root+ itself is an accepted target
+    # @return [Pathname] the caller-supplied path as a Pathname
+    # @raise [ArgumentError] if the path does not exist or resolves outside dumps_root
+    def validate_dump_dir!(dump_dir, allow_root: false)
+      target = Pathname.new(dump_dir.to_s)
+      root = dumps_root
+      target_real = target.exist? ? target.realpath.to_s : ''
+      root_real = root.exist? ? root.realpath.to_s : root.expand_path.to_s
+      contained = target_real.start_with?("#{root_real}#{File::SEPARATOR}")
+      contained ||= allow_root && target_real == root_real
+
+      unless target.exist? && contained
+        raise ArgumentError,
+              'dump_dir must exist inside dumps_root. ' \
+              "Got: #{dump_dir.inspect}, dumps_root: #{dumps_root}"
+      end
+
+      target
+    end
+
     # Atomically flips the +latest+ pointer to the given dump directory.
     #
     # Uses a temp file + +File.rename+ so a crash mid-flip leaves the previous
@@ -122,20 +186,7 @@ module Woods
     # @return [void]
     # @raise [ArgumentError] if +dump_dir+ does not exist or is outside +dumps_root+
     def promote(dump_dir)
-      target = Pathname.new(dump_dir.to_s)
-      root_real = dumps_root.expand_path.to_s
-      target_real = target.exist? ? target.realpath.to_s : ''
-      # Resolve symlinks on both sides before comparing (handles macOS /tmp → /private/var)
-      root_resolved = Pathname.new(root_real).exist? ? Pathname.new(root_real).realpath.to_s : root_real
-      # Prefix must end at a path boundary — a bare start_with? would accept
-      # sibling directories like "dumps-backup" or "dumpsevil", and the
-      # basename-only pointer written below would then name a directory that
-      # doesn't exist under dumps_root.
-      unless target.exist? && target_real.start_with?("#{root_resolved}#{File::SEPARATOR}")
-        raise ArgumentError,
-              'dump_dir must exist inside dumps_root. ' \
-              "Got: #{dump_dir.inspect}, dumps_root: #{dumps_root}"
-      end
+      target = validate_dump_dir!(dump_dir)
 
       atomic_write(latest_pointer_path, target.basename.to_s)
     end
@@ -149,17 +200,32 @@ module Woods
     # @param resolved_config_hash [#to_snapshot_json, Hash]
     # @return [void]
     def write_config(resolved_config_hash)
+      atomic_write(config_path, serialize_config(resolved_config_hash))
+    end
+
+    # Atomically writes a resolved config hash INSIDE a dump directory, as
+    # part of the dump — see {#dump_config_path} for why. Callers write this
+    # before {#promote}, so the config a promoted dump carries is exactly the
+    # config that produced it.
+    #
+    # @param dump_dir [Pathname, String] a dump directory (need not yet be promoted)
+    # @param resolved_config_hash [#to_snapshot_json, Hash]
+    # @return [void]
+    def write_dump_config(dump_dir, resolved_config_hash)
+      atomic_write(dump_config_path(dump_dir), serialize_config(resolved_config_hash))
+    end
+
+    private
+
+    def serialize_config(resolved_config_hash)
       raw = if resolved_config_hash.respond_to?(:to_snapshot_json)
               resolved_config_hash.to_snapshot_json
             else
               resolved_config_hash
             end
-      json = raw.is_a?(String) ? raw : JSON.pretty_generate(raw)
-      atomic_write(config_path, json)
+      raw.is_a?(String) ? raw : JSON.pretty_generate(raw)
     end
 
-    private
-
     def atomic_write(path, content)
       FileUtils.mkdir_p(path.dirname)
       tmp = Tempfile.new('.woods-', path.dirname.to_s)
@@ -168,6 +234,10 @@ module Woods
       tmp.fsync
       tmp.close
       File.rename(tmp.path, path.to_s)
+      # The class doc promises the dump directory is fully fsynced before the
+      # latest pointer flips; a renamed-but-unflushed directory entry would
+      # break that promise on a crash (M11).
+      Woods::AtomicFile.fsync_directory(path.dirname.to_s)
     rescue StandardError
       tmp&.close
       tmp&.unlink

data/lib/woods/mcp/bearer_auth.rb

@@ -9,6 +9,14 @@ module Woods
     #
     # Uses Rack::Utils.secure_compare for constant-time comparison to avoid
     # leaking token bytes via response-time side channels.
+    #
+    # The token may be a String (validated at construction — the standalone
+    # `woods-mcp-http` path) or a callable resolved on every request (the
+    # Rails railtie path, where the token is typically set in
+    # `config/initializers/woods.rb` and therefore does not exist yet when
+    # the middleware is inserted — see #183). A deferred token that resolves
+    # to nothing usable (nil, empty, or shorter than {MIN_TOKEN_LENGTH})
+    # fails closed: every guarded request gets 401.
     class BearerAuth
       UNAUTHORIZED_BODY = { jsonrpc: '2.0', error: { code: -32_001, message: 'Unauthorized' }, id: nil }.to_json.freeze
 
@@ -16,30 +24,111 @@ module Woods
       # Matches OWASP "session ID entropy" guidance (>= 128 bits ≈ 32 hex chars).
       MIN_TOKEN_LENGTH = 32
 
-      def initialize(app, token:)
-        raise ArgumentError, 'token must be a non-empty string' if token.nil? || token.empty?
-        if token.to_s.length < MIN_TOKEN_LENGTH
-          raise ArgumentError,
-                "bearer token must be at least #{MIN_TOKEN_LENGTH} characters " \
-                "(got #{token.to_s.length}); generate with `SecureRandom.hex(32)`"
-        end
-
+      # @param app [#call] The next Rack app in the middleware stack
+      # @param token [String, #call] Bearer token, or a callable returning it.
+      #   String tokens are validated eagerly (raises on nil/empty/short);
+      #   callables are resolved on each request so a token configured after
+      #   the middleware was inserted still takes effect.
+      # @param path [String, nil] When set, only requests whose PATH_INFO
+      #   starts with this prefix are guarded — everything else passes
+      #   straight through to the app. Nil (the default) guards every request.
+      # @param enabled [#call, nil] Optional request-time predicate. When it
+      #   returns falsy the request passes through unguarded. Nil (the
+      #   default) means always guard.
+      def initialize(app, token:, path: nil, enabled: nil)
         @app = app
-        @token = token.to_s
+        @path = path
+        @enabled = enabled
+        @warned_unusable_token = false
+
+        if token.respond_to?(:call)
+          @token_source = token
+        else
+          validate_static_token!(token)
+          static_token = token.to_s
+          @token_source = -> { static_token }
+        end
       end
 
+      # Rack entry point. Out-of-scope requests (non-matching `path:` prefix
+      # or a falsy `enabled:` predicate) pass through untouched; guarded
+      # requests require a matching `Authorization: Bearer <token>` header.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triple
       def call(env)
+        return @app.call(env) unless guard?(env)
+
+        expected = resolve_token
         header = env['HTTP_AUTHORIZATION'].to_s
         presented = header.start_with?('Bearer ') ? header.sub(/\ABearer /, '') : nil
 
-        if presented && Rack::Utils.secure_compare(@token, presented)
+        if expected && presented && Rack::Utils.secure_compare(expected, presented)
           @app.call(env)
         else
-          [401,
-           { 'content-type' => 'application/json', 'www-authenticate' => 'Bearer realm="woods-mcp-http"' },
-           [UNAUTHORIZED_BODY]]
+          unauthorized
         end
       end
+
+      private
+
+      # @param env [Hash] Rack environment
+      # @return [Boolean] whether this request falls under the guard
+      def guard?(env)
+        return false if @path && !env['PATH_INFO'].to_s.start_with?(@path)
+        return false if @enabled && !@enabled.call
+
+        true
+      end
+
+      # Resolve the expected token for this request. Static tokens were
+      # validated at construction; deferred tokens are re-checked here and
+      # an unusable value fails closed (nil => 401 for every request).
+      #
+      # @return [String, nil]
+      def resolve_token
+        token = @token_source.call.to_s
+        return token if token.length >= MIN_TOKEN_LENGTH
+
+        warn_unusable_token(token)
+        nil
+      end
+
+      # @param token [String] the eagerly-supplied token
+      # @raise [ArgumentError] on nil, empty, or too-short tokens
+      def validate_static_token!(token)
+        raise ArgumentError, 'token must be a non-empty string' if token.nil? || token.empty?
+        return unless token.to_s.length < MIN_TOKEN_LENGTH
+
+        raise ArgumentError,
+              "bearer token must be at least #{MIN_TOKEN_LENGTH} characters " \
+              "(got #{token.to_s.length}); generate with `SecureRandom.hex(32)`"
+      end
+
+      # Warn (once per instance) that a deferred token is unusable, so the
+      # resulting wall of 401s is explicable from the logs.
+      #
+      # @param token [String] the resolved (unusable) token
+      # @return [void]
+      def warn_unusable_token(token)
+        return if @warned_unusable_token
+
+        @warned_unusable_token = true
+        reason = if token.empty?
+                   'no bearer token is configured'
+                 else
+                   "the configured bearer token is shorter than #{MIN_TOKEN_LENGTH} characters"
+                 end
+        warn "[Woods::MCP::BearerAuth] refusing guarded requests (401): #{reason}. " \
+             'Set a 32+ character token (e.g. `SecureRandom.hex(32)`).'
+      end
+
+      # @return [Array] 401 Rack response triple
+      def unauthorized
+        [401,
+         { 'content-type' => 'application/json', 'www-authenticate' => 'Bearer realm="woods-mcp-http"' },
+         [UNAUTHORIZED_BODY]]
+      end
     end
   end
 end

data/lib/woods/mcp/bootstrap_state.rb

@@ -41,12 +41,85 @@ module Woods
       #   {Woods.configuration}.
       attr_accessor :resolved_config
 
+      # Store-hydration soft failures recorded during boot, keyed by store
+      # component (+:vector+, +:metadata+, +:graph+) with the exception that
+      # caused each. A recorded failure leaves the retriever serving empty
+      # stores; {#hydration_failed?} is the signal +woods_status+ and
+      # +codebase_retrieve+ use to stop presenting that as healthy (M6).
+      attr_reader :hydration_failures
+
+      # Reload-phase degraded condition (M7), or +nil+. Shape:
+      # +{ phase: 'reload', generation:, stores:, reason: }+ — the generation
+      # still being served, the store component(s) whose refresh failed, and
+      # the formatted reason. Deliberately separate from {#hydration_failures}
+      # and from +status+: a failed reload leaves the PREVIOUS fully aligned
+      # generation being served, so the boot degraded state must not flip and
+      # +codebase_retrieve+ must keep answering from the still-healthy old
+      # stores. +woods_status+ exposes this additively; a successful reload
+      # clears it.
+      attr_reader :reload_failure
+
       def initialize
         @status = :initializing
         @reason = nil
         @hydrated_at = nil
         @degraded_since = nil
         @resolved_config = nil
+        @hydration_failures = {}
+        @reload_failure = nil
+      end
+
+      # Record a store-hydration soft failure. Kept separately from {#reason}
+      # so a provider-unreachable degradation and a hydration degradation can
+      # coexist without overwriting each other's evidence.
+      #
+      # @param component [Symbol, String] which store failed to hydrate
+      # @param error [Exception] the rescued hydration error
+      # @return [self]
+      def record_hydration_failure(component, error)
+        @hydration_failures[component.to_sym] = error
+        self
+      end
+
+      # Did any store fail to hydrate at boot?
+      #
+      # @return [Boolean]
+      def hydration_failed?
+        !@hydration_failures.empty?
+      end
+
+      # Record a failed reload attempt (M7). The reload transaction is
+      # all-or-nothing: the failure means the previous generation is still
+      # being served, which is what +generation+ names.
+      #
+      # @param generation [Integer] generation still being served
+      # @param stores [Array<Symbol, String>] store component(s) whose
+      #   refresh failed
+      # @param reason [String] formatted failure reason (+Class: message+)
+      # @return [self]
+      def record_reload_failure(generation:, stores:, reason:)
+        @reload_failure = {
+          phase: 'reload',
+          generation: generation,
+          stores: Array(stores).map(&:to_s),
+          reason: reason
+        }
+        self
+      end
+
+      # Clear the reload-phase degraded condition after a successful reload.
+      #
+      # @return [self]
+      def clear_reload_failure!
+        @reload_failure = nil
+        self
+      end
+
+      # Did the most recent reload attempt fail? Cleared by the next success.
+      #
+      # @return [Boolean]
+      def reload_failed?
+        !@reload_failure.nil?
       end
 
       # Transition to a new status.
@@ -87,6 +160,10 @@ module Woods
         h[:reason] = "#{@reason.class}: #{@reason.message}" if @reason
         h[:hydrated_at] = @hydrated_at.iso8601 if @hydrated_at
         h[:degraded_since] = @degraded_since.iso8601 if @degraded_since
+        if hydration_failed?
+          h[:hydration_failures] = @hydration_failures.transform_values { |e| "#{e.class}: #{e.message}" }
+        end
+        h[:reload_failure] = @reload_failure.dup if @reload_failure
         h
       end
     end