railwatch 0.9.4 → 1.0.0

data/lib/puma/plugin/railwatch.rb

@@ -1,215 +0,0 @@
-# frozen_string_literal: true
-
-require "puma/plugin"
-
-# `plugin :railwatch` in config/puma.rb. In embedded mode, forks one
-# Railwatch::Writer from the Puma process once it has booted, restarts it if
-# it dies, and stops it with Puma. Same shape as Solid Queue's
-# `solid_queue_mode :fork`, in both cluster and single mode: a default Rails
-# 8 app runs Puma in single mode (no WEB_CONCURRENCY), and that app's
-# batches belong off its request threads just as much. The fork happens
-# from the plugin's background thread with the app loaded and Rails'
-# ForkTracker resetting every Railwatch thread in the child, exactly as it
-# does for a Puma cluster worker. A no-op when Railwatch is off or the
-# transport is not :local, so it is safe to leave in place.
-#
-# Nothing in `start` may touch Railwatch: `bundle exec puma` fires plugin
-# starts BEFORE it loads the Rack app, so the constant may not exist yet.
-# Every decision that needs the app is made from the background supervisor,
-# which waits for after_booted.
-Puma::Plugin.create do
-  attr_reader :log_writer, :writer_pid
-
-  POLL = 2
-  # How often a stopping writer is checked for, and how long a KILL is given
-  # to take before the pid is abandoned (a process stuck in disk I/O cannot
-  # die until the I/O returns, and Puma's exit should not wait for that).
-  REAP_POLL = 0.05
-  KILL_REAP = 1
-
-  def start(launcher)
-    @log_writer = launcher.log_writer
-    @puma_pid = $$
-    @launcher = launcher
-    @shutting_down = false
-    @booted = false
-    @warned = false
-
-    # When the app is already loaded (`bin/rails server` loads it before
-    # handing over to Puma), mark a writer expected now: cluster workers fork
-    # from this process after start and inherit the flag, so they retain
-    # batches while the writer is starting instead of writing them in-process.
-    # Under bare `puma` this is false and the workers find the writer on
-    # their transport's next re-check instead (Transport::Socket).
-    ::Railwatch::Writer.expected! if active?
-
-    # in_background blocks are collected at plugin start and started by the
-    # runner once, so this has to be registered here, not from after_booted
-    # (by then they have already been fired and a late block never runs). It
-    # waits for boot itself.
-    in_background { supervise }
-
-    launcher.events.after_booted { booted! }
-    # A phased restart fires before_restart and then, once the new workers
-    # are up, after_booted again. The writer is stopped for the restart and
-    # the supervisor, which is still running, respawns it when @booted flips
-    # back. Only a real stop latches shutdown.
-    launcher.events.before_restart { restart_writer }
-    # after_stopped only latches. It is NOT where the writer is stopped:
-    # Puma's SIGTERM trap fires it BEFORE `stop_blocked` drains in-flight
-    # requests, so stopping here would take the writer away from requests
-    # that are still running. at_exit runs after the whole run loop.
-    launcher.events.after_stopped { @shutting_down = true }
-    at_exit { shutdown_writer if Process.pid == @puma_pid }
-  end
-
-  private
-
-  def booted!
-    @booted = true
-    ::Railwatch::Writer.expected! if active?
-  end
-
-  # Whether this process should run a writer. Answered fresh each time, and
-  # safe before the app is loaded: `defined?(Railwatch)` is true as soon as
-  # the gem's entrypoint has been required (Bundler.require), but a bare
-  # `puma` on an app that has not required it yet sees neither, and must not
-  # raise out of Puma's boot.
-  def active?
-    return false unless defined?(::Railwatch) && ::Railwatch.respond_to?(:enabled?)
-    return false unless ::Railwatch.enabled? && ::Railwatch.config.local?
-
-    path = ::Railwatch.config.writer_socket_path
-    return false if path.nil?
-    return true if ::Railwatch::Writer.usable_path?(path)
-
-    unless @warned
-      @warned = true
-      log "Railwatch writer not started: socket path #{path} is #{path.bytesize} bytes, over the " \
-          "#{::Railwatch::Writer::MAX_SOCKET_PATH}-byte limit; set RAILWATCH_WRITER_SOCKET to a shorter path. " \
-          "Batches are written in-process meanwhile."
-    end
-    false
-  end
-
-  def spawn_writer
-    @writer_pid = ::Railwatch::Writer.fork_writer! do
-      ::Railwatch::Writer.run!(parent: @puma_pid)
-    end
-    log "Railwatch writer started (pid #{@writer_pid})"
-  rescue SystemCallError => e
-    @writer_pid = nil
-    log "Railwatch writer could not be forked (#{e.class}: #{e.message}); retrying"
-  end
-
-  # Puma's cluster reaps every child with wait2(-1), the writer included, so
-  # waitpid on the writer's pid raises ECHILD after it has died. Liveness is
-  # asked with signal 0 instead, which works whoever reaped it.
-  def supervise
-    loop do
-      sleep POLL
-      break if @shutting_down
-      next unless @booted && active?
-      next if writer_alive?
-
-      log "Railwatch writer (pid #{@writer_pid}) is gone; starting" if @writer_pid
-      spawn_writer
-    end
-  end
-
-  def writer_alive?
-    return false unless @writer_pid
-
-    Process.kill(0, @writer_pid)
-    # A zombie the cluster has not reaped yet still answers signal 0.
-    !Process.waitpid(@writer_pid, Process::WNOHANG)
-  rescue Errno::ESRCH
-    false
-  rescue Errno::ECHILD
-    # Already reaped by the cluster: alive iff it still exists for kill 0.
-    begin
-      Process.kill(0, @writer_pid)
-      true
-    rescue Errno::ESRCH
-      false
-    end
-  end
-
-  # For a restart: stop the writer and mark the cluster as not booted, so the
-  # supervisor spawns a fresh one once after_booted fires again.
-  def restart_writer
-    @booted = false
-    stop_writer
-  end
-
-  # Runs from at_exit, after Puma's run loop has returned and every request
-  # has been served, in both single and cluster mode. Flushes this process's
-  # own reporter (its process and health records, and in single mode the
-  # requests' records) while the writer is still listening, then stops it.
-  def shutdown_writer
-    @shutting_down = true
-    if defined?(::Railwatch) && ::Railwatch.respond_to?(:enabled?) && ::Railwatch.enabled? && ::Railwatch.config.local?
-      ::Railwatch.reporter.shutdown
-    end
-    stop_writer
-  rescue StandardError => e
-    log "Railwatch writer shutdown failed (#{e.class}: #{e.message})"
-  end
-
-  # TERM closes the writer's listener; it finishes what it is holding and
-  # exits on its own. Waited for with a deadline, not Process.wait, which
-  # has none: a writer wedged in a SQLite write or on a full disk would hold
-  # Puma's exit open for as long as it stayed wedged. KILL past the deadline.
-  # Reaped either way, so a cluster master never leaves a zombie behind.
-  def stop_writer
-    return unless @writer_pid
-
-    Process.kill(:TERM, @writer_pid)
-    return if reaped_within?(stop_timeout)
-
-    log "Railwatch writer (pid #{@writer_pid}) did not exit within #{stop_timeout}s of TERM; killing it"
-    Process.kill(:KILL, @writer_pid)
-    log "Railwatch writer (pid #{@writer_pid}) did not exit on KILL; leaving it" unless reaped_within?(KILL_REAP)
-  rescue Errno::ECHILD, Errno::ESRCH
-    nil
-  ensure
-    @writer_pid = nil
-  end
-
-  # shutdown_timeout: the same allowance this process gives its own
-  # reporter, and deliberately NOT the writer's full theoretical exit time
-  # (a sequential SHUTDOWN_DRAIN join per worker thread, its maintenance
-  # join, then its own reporter shutdown -- 13s at the defaults). Waiting
-  # that long would buy nothing: a writer killed mid-batch loses no data,
-  # because the transaction rolls back and the worker retries the batch by
-  # id against the next writer (Writer#serve says so). Exit time spent
-  # waiting for the drain is spent for nothing. An idle writer is gone in
-  # well under a second either way.
-  #
-  # This runs from at_exit, inside the container's TERM-to-KILL grace. Under
-  # Kamal that is Docker's 10s default for a proxied role that has not set
-  # `stop_timeout`, or whatever `stop_timeout` says when it has; an app that
-  # wants the writer given longer can raise RAILWATCH_SHUTDOWN_TIMEOUT to
-  # match its grace, and this bound rises with it.
-  def stop_timeout
-    [ ::Railwatch.config.shutdown_timeout.to_f, 0.0 ].max
-  end
-
-  # Non-blocking waits on a short poll; Process.wait has no timeout and a
-  # child that never exits would hold it forever. ECHILD (the cluster's
-  # wait2(-1) reaped it first) propagates to stop_writer, which reads it as
-  # gone.
-  def reaped_within?(seconds)
-    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
-    loop do
-      return true if Process.waitpid(@writer_pid, Process::WNOHANG)
-      return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-
-      sleep REAP_POLL
-    end
-  end
-
-  def log(message)
-    log_writer.log(message)
-  end
-end

data/lib/railwatch/dashboard_assets.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require "rack/files"
-
-module Railwatch
-  # Serves the prebuilt dashboard bundle the gem ships under public/railwatch.
-  # Vite wrote every asset URL with base /railwatch/assets/, so a request for
-  # /railwatch/assets/assets/app-abc123.js maps to public/railwatch/assets/
-  # app-abc123.js. Files are content-hashed, so they are immutable. The
-  # favicon is the one unhashed file, served with a short cache instead.
-  class DashboardAssets
-    PREFIX = "/railwatch/assets/"
-    ICONS = { "/railwatch/icon.svg" => "/icon.svg", "/railwatch/icon.png" => "/icon.png" }.freeze
-
-    # Put this middleware in the host's stack. Before ActionDispatch::Static
-    # when the host has it, which is what keeps a same-named file in the
-    # app's own public/ from shadowing the dashboard's. An app that serves
-    # static files from nginx, a CDN or Thruster sets
-    # `config.public_file_server.enabled = false` and has no such middleware:
-    # inserting relative to it would raise and take the whole application
-    # down at boot, so go to the front instead, which is the same position
-    # relative to everything that remains.
-    def self.install!(app, root:)
-      if app.config.public_file_server.enabled
-        app.middleware.insert_before ActionDispatch::Static, self, root: root
-      else
-        app.middleware.insert 0, self, root: root
-      end
-    end
-
-    def initialize(app, root:)
-      @app = app
-      @files = Rack::Files.new(root, { "cache-control" => "public, max-age=31536000, immutable" })
-      @icons = Rack::Files.new(root, { "cache-control" => "public, max-age=86400" })
-    end
-
-    def call(env)
-      path = env["PATH_INFO"]
-      return @icons.call(env.merge("PATH_INFO" => ICONS[path])) if ICONS.key?(path)
-      return @app.call(env) unless path.start_with?(PREFIX) && !path.include?("..")
-
-      @files.call(env.merge("PATH_INFO" => path.delete_prefix("/railwatch/assets")))
-    end
-  end
-end

data/lib/railwatch/embedded.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  # Process-local state for the embedded (in-process) mode and the stand-ins
-  # the platform's code expects from its account layer.
-  module Embedded
-    # Relation-shaped empty set for platform associations an embedded install
-    # does not have (Linear links, integrations). Every scope returns itself.
-    NONE = Class.new do
-      def method_missing(*) = self
-      def respond_to_missing?(*) = true
-      def to_a = []
-      def each(&) = [].each(&)
-      def first = nil
-      def map(&) = []
-      def count = 0
-      def any? = false
-      def none? = true
-      def exists?(*) = false
-      def empty? = true
-      def limit(*) = self
-      def where(*) = self
-      def find_each(&) = nil
-    end.new.freeze
-
-    # The platform scopes everything by account (plan, quota, retention,
-    # members). One embedded install is one account with none of that.
-    module Account
-      module_function
-
-      def id = 1
-      def name = Rails.application.class.module_parent_name
-      def slug = name.parameterize
-      def plan = "embedded"
-      def retention_days = Railwatch.config.retention_days
-      def auto_resolve_after_days = 14
-      # Whoever the host's resolver named for this request, not the anonymous
-      # placeholder: an embedded install has no member list, so the account's
-      # one "member" is the person looking at it.
-      def users = [ User.current || User.default ]
-      def members = users
-      def memberships = NONE
-      def integrations = NONE
-      def applications = [ Application.current ]
-      def environments = [ Environment.current ]
-      def quota_exhausted? = false
-      def as_json(*) = { id: id, name: name, slug: slug, plan: plan }
-    end
-  end
-end

data/lib/railwatch/export/client.rb

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Export
-    # Speaks the receipt protocol: names the delivery so the receiver can
-    # recognise a repeat of it, and turns the answer into something the queue
-    # can act on.
-    #
-    # It makes one attempt and has no opinion about when to try again. That
-    # belongs to the queue, which is the thing with durable storage.
-    class Client
-      Outcome = Struct.new(:disposition, :status, :reason, :retry_after_at, :ack, keyword_init: true)
-
-      # The queue is bound to a fingerprint of the export credential, so the
-      # request has to be made with that credential: authenticating as someone
-      # else would deliver these bytes to a tenant that never admitted them.
-      def initialize(config)
-        @config = config
-        @transports = {}
-      end
-
-      # Not `send`: shadowing Object#send on a class makes it impossible to
-      # reach the real one, and reads as a coincidence rather than a verb.
-      def deliver(claim, producer_id:)
-        # Snapshot once, then verify and use those exact bytes. Configuration
-        # can change after Outbox#claim! checked the destination binding.
-        token = @config.resolved_export_token.to_s.dup.freeze
-        unless Digest::SHA256.hexdigest(token) == claim.token_digest
-          return Outcome.new(disposition: :deferred, status: 401, reason: "export credential changed after claim")
-        end
-
-        result = transport_for(claim, token: token).deliver_encoded(
-          body: claim.body, expected_count: claim.record_count, batch_id: claim.delivery_id,
-          dropped: claim.metadata.fetch("dropped", 0).to_i,
-          dropped_bytes: claim.metadata.fetch("dropped_bytes", 0).to_i,
-          # Stored with the delivery, not read from the reporter now: this is
-          # what the batch was carrying when it was queued.
-          backpressure_factor: claim.metadata.fetch("backpressure_factor", 1.0).to_f,
-          gem_version: claim.metadata.fetch("version", Railwatch::VERSION),
-          headers: headers(claim, producer_id)
-        )
-        interpret(result)
-      end
-
-      def reset_after_fork!
-        @transports = {}
-        self
-      end
-
-      # Drops any latch the transports have picked up. After a credential
-      # problem is fixed, the next send must be an actual send.
-      def reset!
-        @transports = {}
-        self
-      end
-
-      private
-
-      # Keyed on the destination this delivery is FOR, not on whatever the
-      # configuration says right now. A process reconfigured mid-flight would
-      # otherwise post bytes admitted for one receiver to another one -- and,
-      # if they belong to different tenants, hand a customer's telemetry to
-      # somebody else while marking it delivered.
-      def transport_for(claim, token:)
-        key = [ claim.url, claim.token_digest ]
-        @transports[key] ||= begin
-          credentialed = @config.dup
-          credentialed.token = token
-          Transport::Http.new(credentialed, endpoint: claim.url)
-        end
-      end
-
-      def headers(claim, producer_id)
-        {
-          "X-Railwatch-Producer-Id" => producer_id,
-          "X-Railwatch-Body-SHA256" => Digest::SHA256.hexdigest(claim.body),
-          "X-Railwatch-Policy" => claim.metadata.fetch("policy", Policy::Everything::VERSION)
-        }
-      end
-
-      # The receiver's answer, reduced to what the queue needs to decide.
-      # Anything it cannot read is treated as "not stored": keeping bytes we
-      # might not need costs a retry, discarding bytes that never arrived
-      # costs the telemetry.
-      STORED = %w[committed already_committed].freeze
-      REJECTING_STATUSES = [ 400, 409, 410, 413, 422 ].freeze
-
-      def interpret(result)
-        return Outcome.new(disposition: :stored, status: result.status, ack: result.to_h) if stored?(result)
-        return Outcome.new(disposition: :rejected, status: result.status, reason: reason_for(result)) if rejected?(result)
-
-        Outcome.new(disposition: :deferred, status: result.status, reason: reason_for(result),
-                    retry_after_at: result.retry_after_at)
-      end
-
-      # A 200 that stored the records, or a duplicate the receiver already
-      # holds. When the receiver names what it did, we believe the name and
-      # not the arithmetic: counts that happen to add up are not a receipt.
-      def stored?(result)
-        return false unless result.ok && !result.deferred?
-        return STORED.include?(result.ack_disposition) if result.ack_disposition
-
-        true
-      end
-
-      # Permanently unacceptable TO THE RECEIVER: sending it again cannot
-      # change the answer. 409 is a delivery id reused for different bytes,
-      # 410 one too old to be recognised.
-      #
-      # Deliberately not our own refusals. `:permanent` from the transport
-      # means we declined to send -- a latched credential failure, a
-      # configuration we will not use -- and throwing the bytes away because
-      # of something on this side would destroy telemetry that was never
-      # offered to anyone.
-      def rejected?(result)
-        REJECTING_STATUSES.include?(result.status)
-      end
-
-      def reason_for(result)
-        (result.reason || result.error || result.status).to_s[0, 64]
-      end
-    end
-  end
-end

data/lib/railwatch/export/lease.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Export
-    # Which process is allowed to send, right now.
-    #
-    # Every eligible process runs a sender; the lease decides which one does
-    # anything. It is held for a short time and renewed, so a process that
-    # dies holding it blocks the queue for seconds rather than forever.
-    #
-    # The generation is a fence. A holder that stalls past its expiry may wake
-    # and finish a request it had already started -- the receipt at the other
-    # end makes that harmless -- but it must not then be able to overwrite
-    # what the new holder has since recorded. Every write it attempts carries
-    # the generation it was granted, and a stale one matches nothing.
-    module Lease
-      TTL = 30
-      # Renewed well inside the TTL: a renewal that has to wait on the write
-      # lock still has room to land before the lease it is extending lapses.
-      RENEW_EVERY = 10
-
-      module_function
-
-      # Takes the lease, or extends it if we already hold it. Returns the
-      # generation we hold it under, or nil if someone else has it.
-      def acquire(destination_id, owner:, now: Time.current)
-        taken = Telemetry::ExportDestination
-          .where(id: destination_id)
-          .where("lease_owner IS NULL OR lease_owner = ? OR lease_expires_at < ?", owner, now)
-          .update_all([
-            "lease_owner = ?, lease_expires_at = ?, lease_generation = lease_generation + 1, updated_at = ?",
-            owner, now + TTL, now
-          ])
-        return nil if taken.zero?
-
-        Telemetry::ExportDestination.where(id: destination_id).pick(:lease_generation)
-      end
-
-      # Extends a lease we still hold. Cannot revive an expired one: taking it
-      # again is acquire's job, and that increments the generation so anything
-      # in flight under the old one is fenced out.
-      def renew(destination_id, owner:, generation:, now: Time.current)
-        Telemetry::ExportDestination
-          .where(id: destination_id, lease_owner: owner, lease_generation: generation)
-          .where(lease_expires_at: now..)
-          .update_all([ "lease_expires_at = ?, updated_at = ?", now + TTL, now ]) == 1
-      end
-
-      def release(destination_id, owner:, generation:, now: Time.current)
-        Telemetry::ExportDestination
-          .where(id: destination_id, lease_owner: owner, lease_generation: generation)
-          .update_all([ "lease_owner = NULL, lease_expires_at = NULL, updated_at = ?", now ]) == 1
-      end
-    end
-  end
-end