wp2txt 2.3.2 → 2.3.4

data/lib/wp2txt/corpus.rb

@@ -14,6 +14,7 @@ require_relative "metadata_index"
 require_relative "fts_index"
 require_relative "section_extractor"
 require_relative "version"
+require_relative "output_path"
 
 module Wp2txt
   # Facade over a local dump: single-article access (Tier 0, multistream),
@@ -324,7 +325,7 @@ module Wp2txt
                        title_match: nil, limit: 0, titles: nil,
                        chunk_size: nil, chunk_overlap: 0,
                        max_articles: DEFAULT_MAX_SYNC_ARTICLES, num_processes: 4,
-                       progress: nil, cancel_check: nil)
+                       progress: nil, cancel_check: nil, overwrite: false)
       if content == "sections" && Array(sections).empty? && alias_set.nil?
         raise ArgumentError, "content: \"sections\" requires sections or alias_set"
       end
@@ -394,46 +395,50 @@ module Wp2txt
       titles_done = 0
       sample = []
 
-      File.open(output_path, "w") do |f|
-        titles.each_slice(EXTRACT_BATCH_SIZE) do |batch|
-          raise Cancelled if cancel_check&.call
-
-          pages = reader.extract_articles_parallel(batch, num_processes: num_processes)
-          batch.each do |t|
-            page = pages[t]
-            next unless page
-
-            records = build_records(page, content, resolved_sections, chunk_size, chunk_overlap)
-            next if records.empty?
-
-            articles_extracted += 1
-            records.each do |record|
-              f.puts(JSON.generate(record))
-              records_written += 1
-              sample << record if sample.size < 3
+      meta_path = "#{output_path}.meta.json"
+      OutputPath.write_pair(output_path, overwrite: overwrite) do |staged_output, staged_meta|
+        File.open(staged_output, "w") do |f|
+          titles.each_slice(EXTRACT_BATCH_SIZE) do |batch|
+            raise Cancelled if cancel_check&.call
+
+            # Forked workers inherit this file's buffer and would write it again on exit
+            f.flush
+            pages = reader.extract_articles_parallel(batch, num_processes: num_processes)
+            batch.each do |t|
+              page = pages[t]
+              next unless page
+
+              records = build_records(page, content, resolved_sections, chunk_size, chunk_overlap)
+              next if records.empty?
+
+              articles_extracted += 1
+              records.each do |record|
+                f.puts(JSON.generate(record))
+                records_written += 1
+                sample << record if sample.size < 3
+              end
             end
+            titles_done += batch.size
+            progress&.call(titles_done, titles.size)
           end
-          titles_done += batch.size
-          progress&.call(titles_done, titles.size)
         end
-      end
 
-      meta_path = "#{output_path}.meta.json"
-      File.write(meta_path, JSON.pretty_generate(
-        tool: "wp2txt #{Wp2txt::VERSION}",
-        dump: dump_name,
-        generated_at: Time.now.utc.iso8601,
-        query: (titles_record || filters.compact).merge(
-          content: content, resolved_sections: resolved_sections,
-          chunk_size: chunk_size, chunk_overlap: chunk_size ? chunk_overlap : nil
-        ).compact,
-        alias_set_contents: alias_contents,
-        total_matching: total,
-        articles_extracted: articles_extracted,
-        records_written: records_written,
-        truncated: truncated,
-        not_found: not_found
-      ))
+        File.write(staged_meta, JSON.pretty_generate(
+          tool: "wp2txt #{Wp2txt::VERSION}",
+          dump: dump_name,
+          generated_at: Time.now.utc.iso8601,
+          query: (titles_record || filters.compact).merge(
+            content: content, resolved_sections: resolved_sections,
+            chunk_size: chunk_size, chunk_overlap: chunk_size ? chunk_overlap : nil
+          ).compact,
+          alias_set_contents: alias_contents,
+          total_matching: total,
+          articles_extracted: articles_extracted,
+          records_written: records_written,
+          truncated: truncated,
+          not_found: not_found
+        ))
+      end
 
       { output_path: output_path, meta_path: meta_path, dump: dump_name,
         total_matching: total, articles_extracted: articles_extracted,
@@ -661,15 +666,19 @@ module Wp2txt
     def run_sql_on(db, sql, limit)
       columns = nil
       rows = []
+      truncated = false
       db.query(sql) do |result|
         columns = result.columns
         result.each do |row|
-          break if rows.size >= limit
+          if rows.size >= limit
+            truncated = true
+            break
+          end
 
           rows << row.map { |v| v.is_a?(String) && v.length > SQL_CELL_LIMIT ? "#{v[0, SQL_CELL_LIMIT]}…" : v }
         end
       end
-      { columns: columns, rows: rows, row_count: rows.size, truncated: rows.size >= limit }
+      { columns: columns, rows: rows, row_count: rows.size, truncated: truncated }
     end
 
     # Execute the query in a forked child with a hard deadline: the child opens
@@ -727,38 +736,24 @@ module Wp2txt
       end
     end
 
-    # Write the full query result to output_path as JSONL. Atomicity: the
-    # child (or inline fallback) writes "#{output_path}.partial"; the parent
-    # renames it into place only on success and removes it on every failure
-    # path (child crash, timeout kill, error over the pipe) — a partially
-    # written file is never presented as a result. The .meta.json sidecar is
-    # written by the parent after the rename succeeds.
+    # Stage JSONL and provenance in unique files, then publish on success.
+    # OutputPath owns exclusive destination reservations and failure cleanup.
     def query_sql_to_file(sql, timeout, attachments, output_path, overwrite)
-      if File.exist?(output_path) && !overwrite
-        raise ArgumentError, "output file already exists: #{output_path} (pass overwrite: true to replace it)"
-      end
-
-      partial = "#{output_path}.partial"
-      FileUtils.rm_f(partial)
-      outcome = begin
-        if Process.respond_to?(:fork)
-          run_sql_file_in_subprocess(sql, timeout, attachments, partial)
-        else
-          db = build_readonly_connection(attach_fts: fts.built?, attachments: attachments)
-          begin
-            run_sql_file_on(db, sql, partial)
-          ensure
-            db.close
-          end
-        end
-      rescue StandardError
-        FileUtils.rm_f(partial)
-        raise
+      outcome = OutputPath.write_pair(output_path, overwrite: overwrite) do |partial, staged_meta|
+        result = if Process.respond_to?(:fork)
+                   run_sql_file_in_subprocess(sql, timeout, attachments, partial)
+                 else
+                   db = build_readonly_connection(attach_fts: fts.built?, attachments: attachments)
+                   begin
+                     run_sql_file_on(db, sql, partial)
+                   ensure
+                     db.close
+                   end
+                 end
+        write_sql_sidecar(staged_meta, sql, attachments, result)
+        result
       end
 
-      File.rename(partial, output_path)
-      write_sql_sidecar(output_path, sql, attachments, outcome)
-
       result = { output_path: output_path, meta_path: "#{output_path}.meta.json",
                  columns: outcome[:columns], row_count: outcome[:row_count],
                  truncated: outcome[:truncated], cells_clipped: outcome[:cells_clipped],
@@ -772,6 +767,7 @@ module Wp2txt
     # subprocess path: the 30s SIGKILL deadline covers the writing too.
     def run_sql_file_on(db, sql, partial_path)
       columns = nil
+      column_mapping = nil
       row_count = 0
       cells_clipped = 0
       truncated = false
@@ -779,7 +775,11 @@ module Wp2txt
 
       File.open(partial_path, "w") do |f|
         db.query(sql) do |result|
-          columns = unique_columns(result.columns)
+          original_columns = result.columns
+          columns = unique_columns(original_columns)
+          column_mapping = original_columns.each_with_index.map do |name, ordinal|
+            { ordinal: ordinal, original_name: name, output_name: columns[ordinal] }
+          end
           result.each do |row|
             if row_count >= SQL_FILE_ROW_LIMIT
               truncated = true
@@ -788,8 +788,8 @@ module Wp2txt
 
             record = {}
             row.each_with_index do |value, i|
-              if value.is_a?(String) && value.length > SQL_FILE_CELL_LIMIT
-                value = "#{value[0, SQL_FILE_CELL_LIMIT]}…"
+              if value.is_a?(String) && value.bytesize > SQL_FILE_CELL_LIMIT
+                value = clip_file_cell(value)
                 cells_clipped += 1
               end
               record[columns[i]] = value
@@ -801,20 +801,37 @@ module Wp2txt
         end
       end
 
-      { columns: columns, row_count: row_count, truncated: truncated,
+      { columns: columns, column_mapping: column_mapping, row_count: row_count, truncated: truncated,
         cells_clipped: cells_clipped, sample: sample }
     end
 
     # Duplicate result column names (SELECT 1 AS x, 2 AS x) are suffixed
     # (_2, _3, ...) so every JSONL record key is unique
     def unique_columns(columns)
-      seen = Hash.new(0)
-      columns.map do |c|
-        seen[c] += 1
-        seen[c] == 1 ? c : "#{c}_#{seen[c]}"
+      reserved = columns.to_h { |name| [name, true] }
+      used = {}
+      columns.map do |name|
+        candidate = name
+        suffix = 2
+        while used[candidate] || (candidate != name && reserved[candidate])
+          candidate = "#{name}_#{suffix}"
+          suffix += 1
+        end
+        used[candidate] = true
+        candidate
       end
     end
 
+    # SQL_FILE_CELL_LIMIT is a byte ceiling INCLUDING the UTF-8 ellipsis.
+    # Remove only the incomplete UTF-8 suffix after a byte-based cut.
+    def clip_file_cell(value)
+      utf8 = value.dup.force_encoding(Encoding::UTF_8)
+      raise JSON::GeneratorError, "SQL cell contains invalid UTF-8" unless utf8.valid_encoding?
+
+      prefix = utf8.byteslice(0, SQL_FILE_CELL_LIMIT - "…".bytesize).force_encoding(Encoding::UTF_8)
+      "#{prefix.scrub("")}…"
+    end
+
     # Subprocess driver for file-output mode; same fork/pipe/SIGKILL
     # structure as run_sql_in_subprocess, but the child writes the rows to
     # partial_path and ships back only the summary
@@ -856,9 +873,9 @@ module Wp2txt
       reader_io&.close
     end
 
-    # Reproducibility sidecar, written by the parent after the atomic rename
-    def write_sql_sidecar(output_path, sql, attachments, outcome)
-      File.write("#{output_path}.meta.json", JSON.pretty_generate(
+    # Reproducibility sidecar, staged by the parent before publication.
+    def write_sql_sidecar(meta_path, sql, attachments, outcome)
+      File.write(meta_path, JSON.pretty_generate(
         tool: "query_sql",
         dump: dump_name,
         built_with: @metadata.stats&.dig(:built_with),
@@ -867,6 +884,8 @@ module Wp2txt
         row_count: outcome[:row_count],
         truncated: outcome[:truncated],
         cells_clipped: outcome[:cells_clipped],
+        column_mapping: outcome[:column_mapping],
+        cell_byte_limit: SQL_FILE_CELL_LIMIT,
         generated_at: Time.now.utc.iso8601,
         wp2txt_version: Wp2txt::VERSION
       ))

data/lib/wp2txt/corpus_jobs.rb

@@ -22,22 +22,24 @@ module Wp2txt
     # unbounded concurrent jobs would multiply workers against the same dump.
     # @return [Hash] { job_id:, status: "running" } or { error: ... }
     def start_extract(params)
-      running = @mutex.synchronize { @jobs.values.find { |s| s[:status] == "running" } }
-      if running
-        return { error: "another job is already running (#{running[:job_id]}); " \
-                        "poll job_status or cancel_job before starting a new one" }
+      job_id = @mutex.synchronize do
+        running = @jobs.values.find { |state| state[:status] == "running" }
+        if running
+          return { error: "another job is already running (#{running[:job_id]}); " \
+                          "poll job_status or cancel_job before starting a new one" }
+        end
+        id = format("job-%04d", @seq += 1)
+        @jobs[id] = {
+          job_id: id, status: "running", started_at: Time.now.utc.iso8601,
+          params: params, titles_done: 0, titles_total: nil, cancel: false
+        }
+        id
       end
 
-      job_id = @mutex.synchronize { format("job-%04d", @seq += 1) }
-      state = {
-        job_id: job_id, status: "running", started_at: Time.now.utc.iso8601,
-        params: params, titles_done: 0, titles_total: nil, cancel: false
-      }
-      @mutex.synchronize { @jobs[job_id] = state }
-
       thread = Thread.new do
-        corpus = @factory.call
+        corpus = nil
         begin
+          corpus = @factory.call
           result = corpus.extract_corpus(
             **params,
             max_articles: nil,
@@ -52,7 +54,7 @@ module Wp2txt
         rescue StandardError => e
           update(job_id) { |s| s[:status] = "error"; s[:error] = "#{e.class}: #{e.message}"; s[:finished_at] = Time.now.utc.iso8601 }
         ensure
-          corpus.close
+          corpus&.close
         end
       end
       thread.report_on_exception = false

data/lib/wp2txt/extractor.rb

@@ -111,6 +111,8 @@ module Wp2txt
 
         if page
           article = Article.new(page[:text], page[:title], !config[:marker])
+          article.page_id = page[:id]
+          article.revision_id = page[:revision_id]
           result = format_article(article, config)
           writer.write(result)
           extracted_count += 1
@@ -480,6 +482,8 @@ module Wp2txt
 
         pages.each do |page|
           article = Article.new(page[:text], page[:title], !config[:marker])
+          article.page_id = page[:id]
+          article.revision_id = page[:revision_id]
           result = format_article(article, config)
           writer.write(result)
           extracted_count += 1
@@ -493,6 +497,8 @@ module Wp2txt
 
           if page
             article = Article.new(page[:text], page[:title], !config[:marker])
+            article.page_id = page[:id]
+            article.revision_id = page[:revision_id]
             result = format_article(article, config)
             writer.write(result)
             extracted_count += 1

data/lib/wp2txt/formatter.rb

@@ -14,6 +14,24 @@ module Wp2txt
 
     # Format article based on configuration and output format
     def format_article(article, config)
+      with_page_ids(format_article_body(article, config), article)
+    end
+
+    # JSON records carry the dump's page and revision IDs right after the title,
+    # when the reader supplied them, so a record can be traced back to its source.
+    def with_page_ids(result, article)
+      return result unless result.is_a?(Hash) && (article.page_id || article.revision_id)
+
+      result.each_with_object({}) do |(key, value), out|
+        out[key] = value
+        next unless key == "title"
+
+        out["page_id"] = article.page_id
+        out["revision_id"] = article.revision_id
+      end
+    end
+
+    def format_article_body(article, config)
       # Store original title for magic word expansion in content
       original_title = article.title.dup
       article.title = format_wiki(article.title, config)

data/lib/wp2txt/fts_index.rb

@@ -19,6 +19,12 @@ module Wp2txt
   # Queries ATTACH the Tier 1 metadata DB so category/section/redirect
   # filters compose with MATCH in plain SQL.
   class FtsIndex
+    class ShortQueryError < ArgumentError
+      def code
+        "query_too_short"
+      end
+    end
+
     SCHEMA_VERSION = 2
     CACHE_SUFFIX = "_fts.sqlite3"
 
@@ -206,6 +212,9 @@ module Wp2txt
     # @return [Hash] { total:, total_is_capped:, hits: [{page_id:, title:, heading:, ord:}] }
     def search(query, mode: "phrase", sections: nil, category: nil, depth: 0,
                limit: 20, offset: 0, count: "capped", count_cap: 1000)
+      if mode == "phrase" && tokenizer == "trigram" && query.length < 3
+        raise ShortQueryError, "trigram phrase searches require at least 3 Unicode characters"
+      end
       match_expr = mode == "query" ? query : phrase_query(query)
 
       conds = ["fts_sections MATCH ?", "p.namespace = 0", "p.redirect_to IS NULL"]
@@ -386,10 +395,10 @@ module Wp2txt
       batches = pairs.each_slice(STREAMS_PER_BATCH).to_a
       done = 0
 
-      Parallel.map(
+      Parallel.each(
         batches,
         in_processes: @num_processes,
-        finish: lambda { |_item, _idx, rows|
+                finish: lambda { |_item, _idx, rows|
           index.insert_batch(rows)
           done += 1
           progress&.call(done, batches.size)
@@ -423,7 +432,7 @@ module Wp2txt
       title = block[MetadataIndexBuilder::TITLE_REGEX, 1]
       return unless title && !title.empty?
 
-      ns = (block[MetadataIndexBuilder::NS_REGEX, 1] || "0").to_i
+      ns = Wp2txt.namespace_id(block[MetadataIndexBuilder::NS_REGEX, 1])
       return unless ns.zero?
 
       page_id = block[MetadataIndexBuilder::ID_REGEX, 1]&.to_i

data/lib/wp2txt/metadata_index.rb

@@ -640,10 +640,10 @@ module Wp2txt
       batches = pairs.each_slice(STREAMS_PER_BATCH).to_a
       done = 0
 
-      Parallel.map(
+      Parallel.each(
         batches,
         in_processes: @num_processes,
-        finish: lambda { |_item, _idx, result|
+                finish: lambda { |_item, _idx, result|
           index.insert_batch(result)
           done += 1
           progress&.call(done, batches.size)
@@ -686,7 +686,7 @@ module Wp2txt
       return unless page_id
 
       title = unescape_xml(title)
-      ns = (block[NS_REGEX, 1] || "0").to_i
+      ns = Wp2txt.namespace_id(block[NS_REGEX, 1])
       text = block[TEXT_REGEX, 1] || ""
       text = unescape_xml(text)
       # Strip HTML comments before scanning, matching what the Article parser

data/lib/wp2txt/multistream.rb

@@ -95,6 +95,11 @@ module Wp2txt
       @early_terminated == true
     end
 
+    # Where the stream holding the last found article ends. Scanning stops as
+    # soon as every target is found, so without this the reader cannot tell how
+    # far that stream extends and would read the dump to its end.
+    attr_reader :stream_end_offset
+
     def find_by_title(title)
       @entries_by_title[title]
     end
@@ -179,6 +184,14 @@ module Wp2txt
       end
     end
 
+    def next_stream_offset_after(io, offset)
+      io.each_line do |line|
+        next_offset = line.split(":", 2).first.to_i
+        return next_offset if next_offset > offset
+      end
+      nil
+    end
+
     def parse_index_stream(io)
       count = 0
       io.each_line do |line|
@@ -205,6 +218,7 @@ module Wp2txt
           @found_targets << title if @target_titles.include?(title)
           if @found_targets.size == @target_titles.size
             @early_terminated = true
+            @stream_end_offset = next_stream_offset_after(io, offset)
             print "\r  Found all #{@target_titles.size} target articles" if @show_progress
             puts if @show_progress
             break
@@ -223,6 +237,10 @@ module Wp2txt
 
   # Reads articles from multistream bz2 files
   class MultistreamReader
+    # A single multistream bz2 stream holds about 100 pages; anything this large
+    # past the last known offset is several streams, not one.
+    MAX_TAIL_STREAM_BYTES = 64 * 1024 * 1024
+
     attr_reader :multistream_path, :index
 
     # Initialize reader with multistream file and index
@@ -357,7 +375,14 @@ module Wp2txt
         if next_offset
           compressed_data = f.read(next_offset - offset)
         else
-          # Last stream - read to end
+          # Last stream of the dump: the rest of the file is that one stream.
+          # A large remainder means the end was never recorded, and reading it
+          # in one call fails outright on some platforms (EINVAL on macOS).
+          remaining = File.size(@multistream_path) - offset
+          if remaining > MAX_TAIL_STREAM_BYTES
+            raise Wp2txt::Error, "cannot locate the end of the stream at offset #{offset} " \
+                                 "(#{remaining} bytes to end of file); the index may be incomplete"
+          end
           compressed_data = f.read
         end
 
@@ -372,7 +397,9 @@ module Wp2txt
       # here would silently read gigabytes to EOF, so fail fast instead
       raise "Stream offset #{current_offset} not found in index (#{offsets.size} streams known)" unless idx
 
-      offsets[idx + 1]
+      return offsets[idx + 1] if idx + 1 < offsets.size
+
+      @index.respond_to?(:stream_end_offset) ? @index.stream_end_offset : nil
     end
 
     def decompress_bz2(data)
@@ -394,6 +421,7 @@ module Wp2txt
           return {
             title: page_title,
             id: page_node.at_xpath("id")&.text&.to_i,
+            revision_id: page_node.at_xpath("revision/id")&.text&.to_i,
             text: page_node.at_xpath(".//text")&.text || ""
           }
         end
@@ -409,6 +437,7 @@ module Wp2txt
         page = {
           title: page_node.at_xpath("title")&.text,
           id: page_node.at_xpath("id")&.text&.to_i,
+          revision_id: page_node.at_xpath("revision/id")&.text&.to_i,
           text: page_node.at_xpath(".//text")&.text || ""
         }
         yield page if page[:title]

data/lib/wp2txt/output_path.rb

@@ -1,27 +1,87 @@
 # frozen_string_literal: true
 
+require "tempfile"
+require "tmpdir"
+
 module Wp2txt
-  # Server-side output path confinement shared by the file-writing tools
-  # (extract_corpus / start_extract_job / query_sql with output_path).
-  # Paths must resolve under the server's output directory — an agent mixing
-  # up paths must not be able to clobber arbitrary user files — and existing
-  # files are not replaced unless overwrite is set.
+  # Output directories are dedicated, trusted directories. Reject links below
+  # the trusted platform temp root (whose ancestors may be OS aliases on macOS).
+  # This does not defend against an attacker replacing parent directories.
   module OutputPath
     module_function
 
-    # @return [String] the confined, absolute output path
-    # @raise [ArgumentError] when the path escapes base_dir or the file exists
+    def reject_symlinks!(path)
+      current = File.expand_path(path)
+      temp_roots = [File.expand_path(Dir.tmpdir), File.realpath(Dir.tmpdir)]
+      loop do
+        raise ArgumentError, "symbolic links are not allowed in output paths: #{current}" if File.symlink?(current)
+        parent = File.dirname(current)
+        break if parent == current || temp_roots.include?(current)
+
+        current = parent
+      end
+    end
+
+    def validate_pair!(path, overwrite: false)
+      [path, "#{path}.meta.json"].each do |destination|
+        reject_symlinks!(destination)
+        if File.exist?(destination) && !overwrite
+          raise ArgumentError, "output file already exists: #{destination} (pass overwrite: true to replace it)"
+        end
+        if File.exist?(destination) && !File.file?(destination)
+          raise ArgumentError, "output destination must be a file: #{destination}"
+        end
+      end
+    end
+
+    # Return the confined absolute path; the writer repeats validation and
+    # reserves both destinations with EXCL to close the check/create race.
     def confine(output_path, base_dir, overwrite: false)
       path = File.expand_path(output_path, base_dir)
       base = File.expand_path(base_dir)
-      unless path == base || path.start_with?(base + File::SEPARATOR)
+      unless path.start_with?(base + File::SEPARATOR)
         raise ArgumentError, "output_path must stay within the server output directory (#{base})"
       end
-      if File.exist?(path) && !overwrite
-        raise ArgumentError, "output file already exists: #{path} (pass overwrite: true to replace it)"
-      end
-
+      validate_pair!(path, overwrite: overwrite)
       path
     end
+
+    # Reserve destinations, stage both files, then publish with rename. EXCL
+    # reservations are empty until publication; the pair is not a transaction.
+    # Failure removes only reservations owned by this call, never prior output.
+    def write_pair(path, overwrite: false)
+      validate_pair!(path, overwrite: overwrite)
+      destinations = [path, "#{path}.meta.json"]
+      reservations = {}
+      temporary = []
+      begin
+        unless overwrite
+          destinations.each do |destination|
+            File.open(destination, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+              reservations[destination] = file.stat
+            end
+          end
+        end
+        destinations.each do |destination|
+          temporary << Tempfile.create([".wp2txt-", ".partial"], File.dirname(destination))
+          temporary.last.close
+        end
+        result = yield(*temporary.map(&:path))
+        destinations.each_with_index do |destination, index|
+          reject_symlinks!(destination)
+          File.rename(temporary[index].path, destination)
+          reservations.delete(destination)
+        end
+        result
+      rescue Errno::EEXIST => e
+        raise ArgumentError, "output file already exists: #{e.message} (pass overwrite: true to replace it)"
+      ensure
+        temporary.each { |file| File.unlink(file.path) if File.exist?(file.path) }
+        reservations.each do |destination, stat|
+          current = File.lstat(destination) rescue nil
+          File.unlink(destination) if current && current.dev == stat.dev && current.ino == stat.ino
+        end
+      end
+    end
   end
 end

data/lib/wp2txt/output_writer.rb

@@ -100,6 +100,14 @@ module Wp2txt
       raise Wp2txt::FileIOError, "Write failed: #{e.message}"
     end
 
+    # Push buffered output to the file. Call before forking: a child process
+    # inherits the buffer and writes it out again when it exits.
+    def flush
+      @mutex.synchronize do
+        @current_file.flush if @current_file && !@current_file.closed?
+      end
+    end
+
     # Close current file and finalize
     def close
       @mutex.synchronize do