siding 0.0.1

data/lib/siding/server.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "fileutils"
+require "rbconfig"
+
+require_relative "error"
+require_relative "version"
+require_relative "project_key"
+require_relative "runtime"
+require_relative "logger"
+require_relative "protocol"
+require_relative "life_cycle"
+require_relative "load_manifest"
+require_relative "staleness"
+require_relative "restarter"
+require_relative "worker"
+
+module Siding
+  class Server
+    BOOTSTRAP = <<~RUBY
+      begin
+        Process.setsid
+      rescue SystemCallError
+        begin
+          Process.setpgrp
+        rescue SystemCallError
+          nil
+        end
+      end
+      require ARGV.shift
+      Siding::Server.start(app_root: ARGV.shift, digest: ARGV.shift)
+    RUBY
+
+    class << self
+      def spawn(project_key:, runtime:, env:)
+        log = File.open(runtime.boot_log_path, File::WRONLY | File::CREAT | File::TRUNC, 0o600)
+        begin
+          Process.spawn(
+            spawn_env(project_key, env),
+            RbConfig.ruby, "-e", BOOTSTRAP, "--",
+            __FILE__, project_key.app_root, project_key.digest,
+            chdir: project_key.app_root,
+            in: File::NULL, out: log, err: log
+          )
+        ensure
+          log.close
+        end
+      end
+
+      def spawn_env(project_key, env)
+        vars = { "SIDING_SERVER" => "1" }
+        gemfile = File.join(project_key.app_root, "Gemfile")
+        vars["BUNDLE_GEMFILE"] = gemfile if File.file?(gemfile)
+        vars["RAILS_ENV"] = project_key.app_env
+        vars["RACK_ENV"] = project_key.app_env
+        vars
+      end
+
+      def start(app_root:, digest:)
+        key = ProjectKey.for(app_root)
+        if key.digest != digest
+          warn("siding: project key mismatch (client #{digest}, server #{key.digest})")
+          exit 1
+        end
+
+        new(project_key: key, runtime: Runtime.for(key)).run
+      end
+    end
+
+    DRAIN_INTERVAL = 0.05
+    SELECT_INTERVAL = 1.0
+    DEFAULT_IDLE_TIMEOUT = 900.0
+
+    attr_reader :project_key, :runtime, :logger, :manifest, :events, :restarter
+
+    def initialize(project_key:, runtime:, logger: nil, env: ENV)
+      @project_key = project_key
+      @runtime = runtime
+      @logger = logger || Logger.new(log_path: runtime.log_path)
+      @env = env
+      @events = Staleness::Events.new(path: runtime.events_path)
+      @workers = {}
+      @workers_mutex = Mutex.new
+      @shutting_down = false
+      @withdrawn = false
+      @served = 0
+      @idle_timeout = self.class.idle_timeout_from(env)
+      touch
+    end
+
+    def self.idle_timeout_from(env)
+      timeout = env["SIDING_IDLE_TIMEOUT"].to_f
+      timeout.positive? ? timeout : DEFAULT_IDLE_TIMEOUT
+    end
+
+    def run
+      boot_application
+      listen
+      publish
+      install_signal_handlers
+      start_restarter
+      accept_loop
+    ensure
+      drain_workers
+      shutdown
+    end
+
+    def start_restarter
+      @restarter = Restarter.new(manifest: manifest, project_key: project_key, runtime: runtime,
+                                 logger: logger,
+                                 busy: -> { busy? },
+                                 superseded: -> { !published_by_us? },
+                                 on_superseded: -> { retire })
+      @restarter.start
+    end
+
+    def busy?
+      @shutting_down || @workers_mutex.synchronize { !@workers.empty? }
+    end
+
+    def retire
+      logger.debug("standing down; a replacement has taken over #{project_key.label}")
+      @shutting_down = true
+      wake
+    end
+
+    private
+
+    def boot_application
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @manifest = LoadManifest.around_boot(app_root: project_key.app_root) do
+        require "bundler/setup" if File.file?(File.join(project_key.app_root, "Gemfile"))
+        require File.join(project_key.app_root, "config", "environment")
+      end
+      @boot_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      @booted_at = Time.now.to_f
+      touch
+      logger.debug("booted #{manifest.revision_label} in #{(@boot_seconds * 1000).round}ms, watching #{manifest.file_entries.size} files")
+    end
+
+    def listen
+      staging = "#{runtime.socket_path}.#{Process.pid}"
+      File.unlink(staging) if File.exist?(staging)
+      @server_socket = UNIXServer.new(staging)
+      File.chmod(0o600, staging)
+      File.rename(staging, runtime.socket_path)
+    end
+
+    def publish
+      payload = {
+        "pid" => Process.pid,
+        "protocol_version" => Protocol::VERSION,
+        "tool_version" => Siding::VERSION,
+        "app_root" => project_key.app_root,
+        "app_env" => project_key.app_env,
+        "booted_at" => @booted_at,
+        "boot_seconds" => @boot_seconds&.round(3),
+        "revision_label" => manifest.revision_label
+      }
+      staging = "#{runtime.server_info_path}.#{Process.pid}"
+      File.write(staging, JSON.generate(payload))
+      File.chmod(0o600, staging)
+      File.rename(staging, runtime.server_info_path)
+    end
+
+    def install_signal_handlers
+      @wake_read, @wake_write = IO.pipe
+      LifeCycle::SERVER_SIGNALS.each do |signal|
+        previous = trap(signal) do
+          @forced = true if @shutting_down
+          @shutting_down = true
+          wake
+        end
+        LifeCycle.remember_signal_handler(signal, previous)
+      end
+    end
+
+    def wake
+      @wake_write.write_nonblock(".")
+    rescue StandardError
+      nil
+    end
+
+    def accept_loop
+      until @shutting_down
+        ready = IO.select([@server_socket, @wake_read], nil, nil, SELECT_INTERVAL)
+        if ready.nil?
+          expire_if_idle
+          next
+        end
+        break if ready[0].include?(@wake_read)
+
+        connection = accept
+        next if connection.nil?
+
+        handle(connection)
+      end
+    end
+
+    def expire_if_idle
+      return if busy?
+      return if idle_seconds < idle_timeout
+
+      logger.debug("idle for #{idle_seconds.round}s; leaving")
+      @shutting_down = true
+      unpublish
+      close_quietly(@server_socket)
+    end
+
+    def idle_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_activity
+    def idle_timeout = @idle_timeout
+
+    def touch
+      @last_activity = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @last_activity_at = Time.now
+    end
+
+    def accept
+      @server_socket.accept_nonblock
+    rescue IO::WaitReadable, Errno::EINTR
+      nil
+    end
+
+    def handle(connection)
+      return connection.close unless Protocol.server_handshake(connection)
+
+      message = Protocol.read_message(connection)
+      return connection.close if message.nil?
+
+      case message.type
+      when Protocol::RUN then dispatch(connection, message)
+      when Protocol::STATUS then respond_status(connection)
+      when Protocol::STOP then stop(connection)
+      else connection.close
+      end
+    rescue Protocol::ProtocolError => e
+      logger.debug("dropping connection: #{e.message}")
+      close_quietly(connection)
+    end
+
+    def dispatch(connection, message)
+      restarter&.busy!
+      touch
+      @served += 1
+      verdict = Staleness.validate(manifest, env: invocation_env(message))
+      return supersede(connection, verdict) if verdict.reboot?
+
+      serve(connection, message, verdict)
+    end
+
+    def invocation_env(message)
+      env = message["env"]
+      env.is_a?(Hash) ? env : ENV
+    end
+
+    def serve(connection, message, verdict)
+      events.record(verdict)
+
+      pid = quiesced do
+        LifeCycle.prepare_for_fork
+
+        fork do
+          @server_socket.close
+          @wake_read.close
+          @wake_write.close
+          Worker.new(connection: connection, message: message, project_key: project_key, manifest: manifest, verdict: verdict, boot_seconds: @boot_seconds).run
+        end
+      end
+
+      Protocol.write_message(connection, Protocol::STARTED, pid: pid)
+      reap(pid, connection)
+    rescue LifeCycle::HookError => e
+      Protocol.write_message(connection, Protocol::BOOT_FAILED, output: "#{e.message}\n")
+      close_quietly(connection)
+    end
+
+    def supersede(connection, verdict)
+      logger.debug("superseded: #{verdict.summary} (#{verdict.reasons.join(', ')})")
+      events.record(verdict, resolution: "rebuild")
+      @shutting_down = true
+      unpublish
+
+      Protocol.write_message(connection, Protocol::BOOTING,
+                             reason: verdict.summary,
+                             restart: true,
+                             replacement_pid: restarter&.replacement_pid,
+                             estimated_seconds: estimated_boot_seconds)
+      close_quietly(connection)
+    end
+
+    def quiesced(&block)
+      return yield if restarter.nil?
+
+      restarter.around_fork(&block)
+    end
+
+    def estimated_boot_seconds = @boot_seconds&.round(1)
+
+    def reap(pid, connection)
+      @workers_mutex.synchronize { @workers[pid] = connection }
+
+      Thread.new do
+        _, status = Process.waitpid2(pid)
+        Protocol.write_message(connection, Protocol::FINISHED,
+                               exit_code: status.exitstatus || 0, signal: status.termsig)
+      rescue StandardError => e
+        logger.debug("lost track of worker #{pid}: #{e.message}")
+      ensure
+        @workers_mutex.synchronize { @workers.delete(pid) }
+        # The idle clock starts when the last worker finishes, not when it started: a two-hour test
+        # run is not two hours of idleness.
+        touch
+        restarter&.idle!
+        close_quietly(connection)
+      end
+    end
+
+    def respond_status(connection)
+      touch
+      Protocol.write_message(connection, Protocol::STATUS_REPORT,
+                             pid: Process.pid,
+                             workers: @workers_mutex.synchronize { @workers.keys },
+                             tool_version: Siding::VERSION,
+                             revision_label: manifest&.revision_label,
+                             booted_at: @booted_at,
+                             boot_seconds: @boot_seconds&.round(3),
+                             served: @served,
+                             last_activity_at: @last_activity_at.to_f,
+                             idle_timeout: idle_timeout,
+                             watch: restarter&.watch_mode,
+                             events: notable_events)
+      close_quietly(connection)
+    end
+
+    def notable_events
+      events.to_a.reject { |event| event.resolution == "fresh" }.last(10).map(&:to_h)
+    end
+
+    def stop(connection)
+      @shutting_down = true
+      unpublish
+      terminate_workers
+      Protocol.write_message(connection, Protocol::FINISHED, exit_code: 0, signal: nil)
+      close_quietly(connection)
+    end
+
+    def terminate_workers
+      @workers_mutex.synchronize { @workers.keys }.each do |pid|
+        Process.kill("TERM", -pid)
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    # The `draining` state, which is where every departure passes through. Workers outlive
+    # the accept loop.
+    def drain_workers
+      sleep(DRAIN_INTERVAL) until @forced || @workers_mutex.synchronize { @workers.empty? }
+    rescue StandardError
+      nil
+    end
+
+    def shutdown
+      restarter&.stop
+      @server_socket&.close
+      unpublish
+      logger.close
+    end
+
+    def unpublish
+      return if @withdrawn
+
+      @withdrawn = true
+      return unless published_by_us?
+
+      [runtime.socket_path, runtime.server_info_path].each do |path|
+        File.unlink(path)
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    def published_by_us?
+      pid = JSON.parse(File.read(runtime.server_info_path))["pid"]
+      pid.nil? || pid == Process.pid
+    rescue StandardError
+      true
+    end
+
+    def close_quietly(io)
+      io.close unless io.nil? || io.closed?
+    rescue IOError
+      nil
+    end
+  end
+end

data/lib/siding/staleness.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "load_manifest"
+
+module Siding
+  module Staleness
+    FRESH = :fresh
+    RELOADABLE = :reloadable
+    REBOOT = :reboot
+
+    DEPENDENCIES_CHANGED = :dependencies_changed
+    SOURCE_CHANGED = :source_changed
+    SOURCE_ADDED_OR_REMOVED = :source_added_or_removed
+    ENVIRONMENT_CHANGED = :environment_changed
+
+    MAX_TRIGGER_PATHS = 25
+
+    Verdict = Struct.new(:strategy, :reasons, :trigger_paths, :revision_label, keyword_init: true) do
+      def fresh? = strategy == FRESH
+      def stale? = !fresh?
+      def reloadable? = strategy == RELOADABLE
+      def reboot? = strategy == REBOOT
+
+      def resolution
+        case strategy
+        when FRESH then "fresh"
+        when RELOADABLE then "reloaded_in_worker"
+        else "rebuild"
+        end
+      end
+
+      def summary
+        return "up to date" if fresh?
+
+        detail = trigger_paths.first
+        reason = reasons.first
+        detail ? "#{reason}: #{File.basename(detail)}" : reason.to_s
+      end
+    end
+
+    module_function
+
+    def validate(manifest, env: ENV)
+      reasons = []
+      triggers = []
+      changed_scopes = []
+
+      bundle_token = LoadManifest.token_for(manifest.bundle_files)
+      if bundle_token != manifest.bundle_token
+        reasons << DEPENDENCIES_CHANGED
+        triggers.concat(manifest.bundle_files)
+        changed_scopes << LoadManifest::REBOOT
+      end
+
+      files = manifest.file_entries.map do |entry|
+        stamp = LoadManifest.stamp_for(entry.path)
+        unless stamp == stamp_of(entry)
+          reasons << SOURCE_CHANGED
+          triggers << entry.path
+          changed_scopes << entry.scope
+        end
+        [entry.path, stamp]
+      end
+
+      directories = manifest.directory_entries.map do |entry|
+        digest = LoadManifest.entry_digest_for(entry.path, recursive: entry.recursive)
+        unless digest == entry.entry_digest
+          reasons << SOURCE_ADDED_OR_REMOVED
+          triggers << entry.path
+          changed_scopes << entry.scope
+        end
+        [entry.path, digest]
+      end
+
+      envs = manifest.env_entries.map do |entry|
+        digest = LoadManifest.digest_env_value(env[entry.key])
+        unless digest == entry.value_digest
+          reasons << ENVIRONMENT_CHANGED
+          triggers << entry.key
+          # Always reboot-class: a value consumed at boot is already inside a constant, and no
+          # reloader can reach in there and change it.
+          changed_scopes << LoadManifest::REBOOT
+        end
+        [entry.key, digest]
+      end
+
+      Verdict.new(
+        strategy: strategy_for(changed_scopes),
+        reasons: reasons.uniq,
+        trigger_paths: triggers.first(MAX_TRIGGER_PATHS),
+        revision_label: LoadManifest.label_for(bundle_token:, files:, directories:, envs:)
+      )
+    end
+
+    def strategy_for(changed_scopes)
+      return FRESH if changed_scopes.empty?
+      return RELOADABLE if changed_scopes.all? { |scope| scope == LoadManifest::RELOADABLE }
+
+      REBOOT
+    end
+
+    def stamp_of(entry) = "#{entry.size}:#{format('%.6f', entry.mtime)}"
+
+    class Events
+      LIMIT = 50
+
+      # When the file is rewritten rather than appended to. Rewriting on every record would turn a
+      # short append into a full read-modify-write for no benefit.
+      COMPACT_AT = LIMIT * 4
+
+      Event = Struct.new(:at, :reason, :trigger_paths, :resolution, :developer_wait,
+                         keyword_init: true) do
+        def to_h
+          {
+            "at" => at.iso8601(3),
+            "reason" => reason.to_s,
+            "trigger_paths" => trigger_paths,
+            "resolution" => resolution,
+            "developer_wait" => developer_wait
+          }
+        end
+
+        def self.from_h(hash)
+          new(at: Time.iso8601(hash["at"]), reason: hash["reason"],
+              trigger_paths: Array(hash["trigger_paths"]), resolution: hash["resolution"],
+              developer_wait: hash["developer_wait"])
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+
+      def initialize(limit: LIMIT, path: nil)
+        @limit = limit
+        @path = path
+        @events = load_recorded
+        @mutex = Mutex.new
+      end
+
+      def record(verdict, resolution: nil, developer_wait: nil, at: Time.now)
+        event = Event.new(at: at, reason: verdict.reasons.first,
+                          trigger_paths: verdict.trigger_paths,
+                          resolution: resolution || verdict.resolution,
+                          developer_wait: developer_wait)
+        @mutex.synchronize do
+          @events << event
+          @events.shift while @events.size > @limit
+        end
+        persist(event)
+        event
+      end
+
+      def to_a = @mutex.synchronize { @events.dup }
+      def last = @mutex.synchronize { @events.last }
+      def size = @mutex.synchronize { @events.size }
+
+      private
+
+      def persist(event)
+        return if @path.nil?
+
+        File.open(@path, "a") { |file| file.write("#{JSON.generate(event.to_h)}\n") }
+        compact if File.size(@path) > COMPACT_AT * 512
+      rescue SystemCallError, JSON::GeneratorError
+        nil
+      end
+
+      def compact
+        lines = File.readlines(@path).last(@limit)
+        File.write(@path, lines.join)
+      rescue SystemCallError
+        nil
+      end
+
+      def load_recorded
+        return [] if @path.nil? || !File.file?(@path)
+
+        File.readlines(@path).last(@limit).filter_map do |line|
+          parsed = JSON.parse(line)
+          Event.from_h(parsed) if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          nil
+        end
+      rescue SystemCallError
+        []
+      end
+    end
+  end
+end

data/lib/siding/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Siding
+  VERSION = "0.0.1"
+end

data/lib/siding/watch.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+#
+require "watchcat"
+
+module Siding
+  class Watch
+    EVENTS = :events
+    POLL = :poll
+
+    RootEntry = Struct.new(:path, :recursive)
+
+    class << self
+      def mode_from(env, logger: nil)
+        value = env["SIDING_WATCH"]
+        return POLL if value == "poll"
+        return EVENTS if value.nil? || value == "events"
+
+        logger&.debug("restarter watch: unrecognized SIDING_WATCH=#{value.inspect}; using events")
+        EVENTS
+      end
+
+      def roots_for(manifest)
+        recursive_paths = manifest.directory_entries.map(&:path).uniq
+
+        file_dirs = manifest.file_entries.map { |entry| File.dirname(entry.path) }
+        bundle_dirs = manifest.bundle_files.map { |path| File.dirname(path) }
+        non_recursive_paths = (file_dirs + bundle_dirs).uniq.reject do |path|
+          under_recursive_root?(path, recursive_paths)
+        end
+
+        entries = recursive_paths.map { |path| RootEntry.new(path, true) } + non_recursive_paths.map { |path| RootEntry.new(path, false) }
+        entries.uniq(&:path).select { |entry| File.directory?(entry.path) }
+      end
+
+      def start(manifest:, env:, logger:, &on_change)
+        mode = mode_from(env, logger: logger)
+        entries = roots_for(manifest)
+        return nil if entries.empty?
+
+        begin
+          executor = build_executor(entries, on_change, force_polling: mode == POLL)
+        rescue StandardError => e
+          logger.debug("restarter watch: could not start watchcat (#{e.class}: #{e.message}); using poll")
+          return Watcher.unavailable("#{e.class}: #{e.message}")
+        end
+
+        Watcher.active(executor, mode)
+      end
+
+      private
+
+      def under_recursive_root?(path, recursive_paths)
+        recursive_paths.any? { |root| path == root || path.start_with?("#{root}#{File::SEPARATOR}") }
+      end
+
+      def build_executor(entries, on_change, force_polling:)
+        recursive = entries.select(&:recursive).map(&:path)
+        non_recursive = entries.reject(&:recursive).map(&:path)
+        callback = proc { on_change.call }
+
+        filters = { ignore_access: true }
+
+        if recursive.any?
+          executor = Watchcat.watch(recursive, recursive: true, force_polling:, filters:, &callback)
+          # `force_polling` is fixed at construction and applies to the whole executor, so a
+          # second call to add the non-recursive roots inherits it -- there is no per-path knob.
+          executor.watch(non_recursive, recursive: false) if non_recursive.any?
+        else
+          executor = Watchcat.watch(non_recursive, recursive: false, force_polling:, filters:, &callback)
+        end
+
+        executor
+      end
+    end
+
+    class Watcher
+      def self.active(executor, mode)
+        label = mode == POLL ? "poll (watchcat)" : "events (watchcat)"
+        new(executor:, label:, attempted: true)
+      end
+
+      def self.unavailable(reason) = new(executor: nil, label: "poll -- watchcat could not start: #{reason}", attempted: false)
+
+      def initialize(executor:, label:, attempted:)
+        @executor = executor
+        @label = label
+        @attempted = attempted
+      end
+
+      def watching?
+        @attempted && alive?
+      end
+
+      def mode_label
+        return @label if @attempted && alive?
+        return @label unless @attempted
+
+        "poll -- watchcat watcher thread died"
+      end
+
+      def stop
+        @executor&.stop
+      end
+
+      private
+
+      def alive?
+        return true if @executor.nil?
+        @executor.alive?
+      rescue StandardError
+        true
+      end
+    end
+  end
+end