siding 0.0.1

data/lib/siding/protocol.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+require_relative "error"
+
+module Siding
+  module Protocol
+    VERSION = 1
+
+    LENGTH_BYTES = 4
+    LENGTH_FORMAT = "N"
+
+    MAX_MESSAGE_BYTES = 1024 * 1024
+
+    # Client -> server.
+    HELLO = "Hello"
+    RUN = "Run"
+    SIGNAL = "Signal"
+    STATUS = "Status"
+    STOP = "Stop"
+
+    # Server -> client.
+    WELCOME = "Welcome"
+    VERSION_MISMATCH = "VersionMismatch"
+    BOOTING = "Booting"
+    BOOT_FAILED = "BootFailed"
+    STARTED = "Started"
+    FINISHED = "Finished"
+    STATUS_REPORT = "StatusReport"
+
+    class ProtocolError < Error; end
+    class TruncatedMessage < ProtocolError; end
+    class MessageTooLarge < ProtocolError; end
+
+    class VersionMismatch < ProtocolError
+      attr_reader :server_version, :client_version
+
+      def initialize(server_version:, client_version: VERSION)
+        @server_version = server_version
+        @client_version = client_version
+        super("server speaks protocol version #{server_version}, this client speaks #{client_version}")
+      end
+    end
+
+    Message = Struct.new(:type, :payload, keyword_init: true) do
+      def [](key) = payload[key]
+    end
+
+    module_function
+
+    def write_message(io, type, payload = {})
+      body = JSON.generate({ "type" => type }.merge(stringify(payload)))
+      raise MessageTooLarge, "message of #{body.bytesize} bytes exceeds #{MAX_MESSAGE_BYTES}" if body.bytesize > MAX_MESSAGE_BYTES
+
+      # Length and body in a single write. Two writes would give a reader a window in which a
+      # crash leaves a valid-looking prefix with nothing behind it -- exactly the state the
+      # framing is here to make unrepresentable.
+      io.write([body.bytesize].pack(LENGTH_FORMAT) + body)
+      io.flush if io.respond_to?(:flush)
+      body.bytesize
+    end
+
+    def read_message(io)
+      header = read_exactly(io, LENGTH_BYTES, allow_eof: true)
+      return nil if header.nil?
+
+      length = header.unpack1(LENGTH_FORMAT)
+      raise MessageTooLarge, "peer announced #{length} bytes, over the #{MAX_MESSAGE_BYTES} limit" if
+        length > MAX_MESSAGE_BYTES
+
+      body = read_exactly(io, length)
+      parsed = begin
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise ProtocolError, "malformed message body: #{e.message}"
+      end
+
+      raise ProtocolError, "message has no type" unless parsed.is_a?(Hash) && parsed["type"]
+
+      Message.new(type: parsed.delete("type"), payload: parsed)
+    end
+
+    def read_exactly(io, count, allow_eof: false)
+      return +"" if count.zero?
+
+      buffer = +""
+      while buffer.bytesize < count
+        chunk = read_some(io, count - buffer.bytesize)
+        if chunk.nil? || chunk.empty?
+          return nil if buffer.empty? && allow_eof
+
+          raise TruncatedMessage, "peer sent #{buffer.bytesize} of #{count} bytes before closing"
+        end
+        buffer << chunk
+      end
+      buffer
+    end
+
+    def read_some(io, count)
+      io.respond_to?(:recv) ? io.recv(count) : io.read(count)
+    end
+
+    def stringify(payload)
+      payload.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    STREAM_ORDER = %i[stdin stdout stderr].freeze
+
+    def send_streams(io, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      [stdin, stdout, stderr].each { |stream| io.send_io(stream) }
+      STREAM_ORDER
+    end
+
+    def receive_streams(io)
+      STREAM_ORDER.each_with_object({}) { |name, streams| streams[name] = io.recv_io }
+    rescue EOFError, SocketError, SystemCallError => e
+      # A peer that dies mid-pass surfaces as `SocketError` ("file descriptor was not passed")
+      # rather than as EOF, because the control message arrives empty rather than not at all.
+      # Both mean the same thing here: the descriptors we were promised are not coming.
+      raise TruncatedMessage, "peer closed while passing descriptors: #{e.message}"
+    end
+
+    def client_handshake(io)
+      write_message(io, HELLO, protocol_version: VERSION)
+      reply = read_message(io)
+      raise TruncatedMessage, "server closed during handshake" if reply.nil?
+
+      case reply.type
+      when WELCOME
+        reply["protocol_version"]
+      when VERSION_MISMATCH
+        raise VersionMismatch.new(server_version: reply["protocol_version"])
+      else
+        raise ProtocolError, "unexpected #{reply.type.inspect} in response to #{HELLO}"
+      end
+    end
+
+    def server_handshake(io)
+      hello = read_message(io)
+      raise TruncatedMessage, "client closed during handshake" if hello.nil?
+      raise ProtocolError, "expected #{HELLO}, got #{hello.type.inspect}" unless hello.type == HELLO
+
+      if hello["protocol_version"] == VERSION
+        write_message(io, WELCOME, protocol_version: VERSION)
+        true
+      else
+        write_message(io, VERSION_MISMATCH, protocol_version: VERSION)
+        false
+      end
+    end
+  end
+end

data/lib/siding/restarter.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "staleness"
+require_relative "watch"
+
+module Siding
+  class Restarter
+    MIN_INTERVAL = 3.0
+    MAX_INTERVAL = 60.0
+    IDLE_FRACTION = 0.1
+    SETTLE = 1.0
+    HANDOVER_INTERVAL = 0.5
+
+    QUIET = :quiet
+    SETTLING = :settling
+    BOOT = :boot
+    SUPERSEDED = :superseded
+
+    attr_reader :manifest, :project_key, :runtime, :logger
+
+    def initialize(manifest:, project_key:, runtime:, logger:, env: ENV, clock: nil, busy: nil, superseded: nil, on_superseded: nil, spawner: nil)
+      @manifest = manifest
+      @project_key = project_key
+      @runtime = runtime
+      @logger = logger
+      @env = env
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @busy = busy || -> { false }
+      @superseded = superseded || -> { false }
+      @on_superseded = on_superseded
+      @spawner = spawner
+      @gate = Mutex.new
+      @signal = Thread::Queue.new
+      @running = false
+      @last_activity = @clock.call
+    end
+
+    def start
+      return self if @thread
+
+      @watch = start_watch
+
+      @running = true
+      @thread = Thread.new { poll_loop }
+      @thread.name = "siding-restarter" if @thread.respond_to?(:name=)
+      self
+    end
+
+    def stop
+      thread = @thread
+      @running = false
+      @thread = nil
+      @watch&.stop
+      return self if thread.nil?
+
+      @signal << :stop
+      thread.join(1) || thread.kill
+      self
+    end
+
+    def watch_mode
+      @watch ? @watch.mode_label : "poll"
+    end
+
+    def busy!
+      @last_activity = @clock.call
+    end
+    alias idle! busy!
+
+    def idle_seconds(now = @clock.call)
+      now - @last_activity
+    end
+
+    def interval_for(idle)
+      [[idle * IDLE_FRACTION, MIN_INTERVAL].max, MAX_INTERVAL].min
+    end
+
+    def quiesce
+      @gate.synchronize { yield }
+    end
+
+    def around_fork
+      quiesce do
+        @watch&.stop
+        yield
+      ensure
+        @watch = start_watch if @running
+      end
+    end
+
+    def poll(now: @clock.call)
+      decision = tick(now: now)
+      act(decision)
+      decision
+    end
+
+    def tick(now: @clock.call)
+      return SUPERSEDED if @superseded.call
+      return QUIET if @busy.call
+
+      verdict = Staleness.validate(manifest, env: @env)
+      return settled(QUIET) if verdict.fresh?
+
+      settle(verdict.revision_label, now)
+    end
+
+    def replacement_pid
+      pid = @replacement_pid
+      return nil if pid.nil?
+      return pid if alive?(pid)
+
+      @replacement_pid = nil
+    end
+
+    private
+
+    def start_watch
+      Watch.start(manifest:, env: @env, logger:) do
+        @signal << :changed if @signal.empty?
+      end
+    end
+
+    def poll_loop
+      while @running
+        wait(wait_interval)
+        break unless @running
+
+        @last_decision = quiesce { poll }
+      end
+    rescue StandardError => e
+      logger.debug("restarter stopped: #{e.class}: #{e.message}")
+    end
+
+    def wait(seconds)
+      @signal.pop(timeout: seconds)
+    end
+
+    def wait_interval
+      return SETTLE if @last_decision == SETTLING
+      return HANDOVER_INTERVAL if replacement_pid
+      return MAX_INTERVAL if @watch&.watching?
+
+      interval_for(idle_seconds)
+    end
+
+    def act(decision)
+      case decision
+      when BOOT then spawn_replacement
+      when SUPERSEDED then withdraw
+      end
+    end
+
+    def settle(label, now)
+      if label != @pending_label
+        @pending_label = label
+        @pending_since = now
+        return SETTLING
+      end
+
+      return SETTLING if now - @pending_since < SETTLE
+      return QUIET if label == @attempted_label
+
+      @attempted_label = label
+      BOOT
+    end
+
+    def settled(decision)
+      @pending_label = nil
+      @pending_since = nil
+      decision
+    end
+
+    def spawn_replacement
+      require_relative "server"
+
+      @replacement_pid = spawner.call
+      reaper = Process.detach(@replacement_pid) if @replacement_pid
+      # A reaper that finds the pid was never ours has nothing to report to anyone's terminal.
+      reaper&.report_on_exception = false
+      logger.debug("restarter booting #{@pending_label} as #{@replacement_pid}")
+      @replacement_pid
+    rescue StandardError => e
+      logger.debug("restarter could not boot a replacement: #{e.message}")
+      @replacement_pid = nil
+    end
+
+    def spawner
+      @spawner || -> { Server.spawn(project_key:, runtime:, env: @env) }
+    end
+
+    def withdraw
+      @running = false
+      @on_superseded&.call
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue SystemCallError
+      true
+    end
+  end
+end

data/lib/siding/runtime.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+require_relative "platform"
+
+module Siding
+  class Runtime
+    DIRECTORY_MODE = 0o700
+
+    NAMESPACE = "siding"
+
+    # Used when XDG_RUNTIME_DIR is unset -- common on macOS, where there is no such convention.
+    # `~/.local/state` is the XDG base-directory spec's home for state that should persist between
+    # restarts but is not configuration.
+    FALLBACK_ROOT = File.join(".local", "state", NAMESPACE)
+
+    class Unavailable < Error
+      attr_reader :path
+
+      def initialize(message, path: nil)
+        @path = path
+        super(message)
+      end
+    end
+
+    attr_reader :project_key, :root
+
+    def self.for(project_key, env: ENV)
+      new(project_key: project_key, root: root_for(env))
+    end
+
+    def self.root_for(env)
+      xdg = env["XDG_RUNTIME_DIR"]
+      return File.join(xdg, NAMESPACE) if xdg && !xdg.empty?
+
+      File.join(Dir.home, FALLBACK_ROOT)
+    end
+
+    def initialize(project_key:, root:)
+      @project_key = project_key
+      @root = root
+    end
+
+    def dir = File.join(root, project_key.digest)
+    def socket_path = File.join(dir, "sock")
+    def lock_path = File.join(dir, "lock")
+    def server_info_path = File.join(dir, "server.json")
+    def boot_log_path = File.join(dir, "boot.log")
+    def events_path = File.join(dir, "events.jsonl")
+    def log_path = File.join(dir, "siding.log")
+
+    def server_info
+      info = JSON.parse(File.read(server_info_path))
+      info.is_a?(Hash) ? info : nil
+    rescue SystemCallError, JSON::ParserError
+      nil
+    end
+
+    def live_server_info
+      info = server_info
+      return nil if info.nil?
+
+      pid = info["pid"]
+      return nil unless pid.is_a?(Integer) && self.class.process_alive?(pid)
+
+      info
+    end
+
+    def server_pid = live_server_info&.[]("pid")
+
+    def discard_socket
+      File.unlink(socket_path)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def discard_records
+      [socket_path, server_info_path].each do |path|
+        File.unlink(path)
+      rescue SystemCallError
+        nil
+      end
+      true
+    end
+
+    def self.process_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    rescue SystemCallError
+      # Anything else means the question could not be asked, and a live process wrongly called dead
+      # would have us boot a second server over a working one.
+      true
+    end
+
+    def prepare
+      check_socket_path_length
+      ensure_directory(root)
+      ensure_directory(dir)
+      self
+    end
+
+    def prepared?
+      File.directory?(dir) && safe_directory?(dir) && socket_path_within_limit?
+    end
+
+    def unavailable_reason
+      prepare
+      nil
+    rescue Unavailable => e
+      e.message
+    end
+
+    def socket_path_within_limit?
+      socket_path.bytesize <= Platform::UNIX_SOCKET_PATH_LIMIT - 1
+    end
+
+    private
+
+    def ensure_directory(path)
+      FileUtils.mkdir_p(path, mode: DIRECTORY_MODE)
+      File.chmod(DIRECTORY_MODE, path)
+      verify_ownership(path)
+    rescue SystemCallError => e
+      raise Unavailable.new("cannot use runtime directory #{path}: #{e.message}", path: path)
+    end
+
+    def verify_ownership(path)
+      stat = File.stat(path)
+      unless stat.uid == Process.uid
+        raise Unavailable.new(
+          "runtime directory #{path} is owned by uid #{stat.uid}, not #{Process.uid}", path: path
+        )
+      end
+
+      return if (stat.mode & 0o077).zero?
+
+      raise Unavailable.new(
+        "runtime directory #{path} is accessible to other users (mode #{format('%o', stat.mode & 0o777)})",
+        path: path
+      )
+    end
+
+    def safe_directory?(path)
+      stat = File.stat(path)
+      stat.uid == Process.uid && (stat.mode & 0o077).zero?
+    rescue SystemCallError
+      false
+    end
+
+    def check_socket_path_length
+      return if socket_path_within_limit?
+
+      raise Unavailable.new(
+        "socket path #{socket_path} is #{socket_path.bytesize} bytes, over the " \
+        "#{Platform::UNIX_SOCKET_PATH_LIMIT - 1}-byte limit for Unix domain sockets",
+        path: socket_path
+      )
+    end
+  end
+end