openlanes 3.0.0 → 3.1.0

data/lib/openlanes/apps/probe.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "socket"
+
+module OpenLanes
+  module Apps
+    # Whether a process is ready (plan 012, decision 1): something accepts a
+    # TCP connection on its port, and, when its `ready:` names a path, a GET
+    # of that path answers 2xx or 3xx.
+    #
+    # Only ever on the port the process was given. An app that moved to
+    # another port (Vite without `--strictPort` does) therefore never
+    # becomes ready, which is how a moved port fails the start rather than
+    # leaving the Preview tab pointing at nothing.
+    module Probe
+      # Seconds a connect, and a read, may take.
+      TIMEOUT = 1
+
+      module_function
+
+      # @param port [Integer]
+      # @param path [String, nil]
+      # @return [Boolean]
+      def ready?(port, path: nil)
+        return false unless listening?(port)
+        return true if path.nil?
+
+        status(port, path).between?(200, 399)
+      end
+
+      # Something accepted a connection on the port. Asking the socket for
+      # its peer is the part that matters: behind a network filter (Little
+      # Snitch on macOS) `Socket.tcp` with `connect_timeout` returns a socket
+      # for a refused connect, and only `getpeername` then says EINVAL. Without
+      # it every port on the machine reads as taken.
+      #
+      # @param port [Integer]
+      # @param timeout [Numeric] seconds the connect may take
+      # @return [Boolean]
+      def listening?(port, timeout: TIMEOUT)
+        Socket.tcp(Status::HOST, port, connect_timeout: timeout) do |socket|
+          socket.remote_address
+          true
+        end
+      rescue SystemCallError, IOError, SocketError
+        false
+      end
+
+      # @param port [Integer]
+      # @param path [String]
+      # @return [Integer] the status, 0 when nothing answered
+      def status(port, path)
+        http = Net::HTTP.new(Status::HOST, port)
+        http.open_timeout = TIMEOUT
+        http.read_timeout = TIMEOUT
+        http.request_get(path).code.to_i
+      rescue SystemCallError, IOError, Timeout::Error, Net::HTTPBadResponse, SocketError
+        0
+      end
+    end
+  end
+end

data/lib/openlanes/apps/process_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Apps
+    # One process of an app, as `.openlanes.yml` declares it under
+    # `app.processes` (M12).
+    #
+    # @!attribute [r] name
+    #   @return [String] `api`, `web`; unique within the app
+    # @!attribute [r] start
+    #   @return [String] a shell line, run by `sh -c` in the checkout, so
+    #     `$PORT_WEB` expands there
+    # @!attribute [r] ready
+    #   @return [String, nil] an HTTP path that must answer 2xx or 3xx; nil
+    #     means a TCP connect is enough
+    # @!attribute [r] restart_on
+    #   @return [Array<String>] `Dir.glob` patterns, relative to the checkout
+    # @!attribute [r] preview
+    #   @return [Boolean] the one process the Preview tab shows
+    ProcessSpec = Data.define(:name, :start, :ready, :restart_on, :preview) do
+      def initialize(name:, start:, ready: nil, restart_on: [], preview: false) = super
+
+      # `PORT_<NAME>`: upcased, anything not a letter or digit as `_`, so
+      # `api-v2` is `PORT_API_V2` and a shell can expand it.
+      #
+      # @return [String]
+      def port_env = "PORT_#{name.upcase.gsub(/[^A-Z0-9]/, "_")}"
+
+      # @return [Boolean]
+      def preview? = preview == true
+
+      # @return [Hash] as `.openlanes.yml` spells it, defaults left out
+      def to_h
+        { "name" => name, "start" => start, "ready" => ready,
+          "restart_on" => (restart_on unless restart_on.empty?), "preview" => (true if preview?) }.compact
+      end
+    end
+  end
+end

data/lib/openlanes/apps/runner.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_boolean"
+require "json"
+
+module OpenLanes
+  module Apps
+    # `openlanes app start` in the foreground (plan 012, B6): one plan's app
+    # started, kept, and stopped.
+    #
+    # Each tick it heartbeats the app's statuses into Redis for the Preview
+    # tab ({Listing}), restarts the processes whose `restart_on` files
+    # changed ({Watcher}), and applies what the tab's toolbar asked for
+    # (`Live::Keys#app_commands`). It ends on INT or TERM, which is what
+    # `openlanes app stop` sends, or on the toolbar's Stop, and either way
+    # stops every process and takes the app off the board.
+    #
+    # Redis is optional. Without a store the app runs just the same and the
+    # page simply never hears of it.
+    class Runner
+      # Seconds between ticks: the watcher's poll and the heartbeat.
+      INTERVAL = 1
+
+      # Commands kept on the stream; the runner reads only what arrives
+      # after it started, so this is only a bound on Redis.
+      COMMANDS_LENGTH = 100
+
+      # What the toolbar may ask for.
+      ACTIONS = %w[restart stop].freeze
+
+      # @param definition [OpenLanes::Apps::Definition]
+      # @param root [String] the checkout
+      # @param plan [String]
+      # @param branch [String]
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore, nil]
+      # @param keys [OpenLanes::Live::Keys, nil]
+      # @param interval [Numeric]
+      # @param sleeper [#call] waits the given seconds
+      # @param stopping [Concurrent::AtomicBoolean] set to end the loop
+      # @param say [#call] given a line for the terminal
+      # @param supervisor [Hash] more arguments for {Supervisor.new}
+      def initialize(definition:, root:, plan:, branch:, store: nil, keys: nil, interval: INTERVAL,
+        sleeper: ->(seconds) { sleep seconds }, stopping: Concurrent::AtomicBoolean.new, say: ->(_) {}, supervisor: {})
+        @definition = definition
+        @plan = plan
+        @store = store
+        @keys = keys
+        @interval = interval
+        @sleeper = sleeper
+        @stopping = stopping
+        @say = say
+        @supervisor = Supervisor.new(definition:, root:, plan:, branch:, publisher: method(:publish), **supervisor)
+        @watcher = Watcher.new(root:, definition:)
+      end
+
+      # @return [OpenLanes::Apps::Supervisor]
+      attr_reader :supervisor
+
+      # @return [Concurrent::AtomicBoolean]
+      attr_reader :stopping
+
+      # Start the app and keep it until told to stop.
+      #
+      # @return [void]
+      # @raise [OpenLanes::Apps::Supervisor::StartFailed] after the failed
+      #   statuses were published, so the tab can show why
+      def call
+        cursor = newest_command
+        @supervisor.start
+        until @stopping.true?
+          @watcher.changed.each { restart(it, why: "its files changed") }
+          cursor = commands(cursor)
+          heartbeat
+          @sleeper.call(@interval) unless @stopping.true?
+        end
+      rescue Supervisor::StartFailed
+        # The failed statuses stay on the board until their heartbeat runs
+        # out, so the tab can say why before it goes.
+        failed = true
+        raise
+      ensure
+        @supervisor.stop
+        live { Listing.remove(store: @store, keys: @keys, plan: @plan) } unless failed
+        nudge
+      end
+
+      # The supervisor's publisher: every transition goes out at once, with
+      # the whole app, since the page reads a plan's processes together.
+      #
+      # @param status [OpenLanes::Apps::Status]
+      # @return [void]
+      def publish(status)
+        @say.call("#{status.process} #{status.state} on port #{status.port}#{": #{status.reason}" if status.reason}")
+        heartbeat
+        nudge
+      end
+
+      private
+
+      # @return [void]
+      def heartbeat = live { Listing.write(store: @store, keys: @keys, plan: @plan, statuses: @supervisor.statuses) }
+
+      # Tells open pages the app changed. Only on a transition or a stop,
+      # never on the once-a-second {#heartbeat}, which changes nothing a
+      # page shows: an app that is merely up keeps every stream asleep.
+      #
+      # @return [void]
+      def nudge = live { Live::News.publish(store: @store, keys: @keys, kind: "app") }
+
+      # @return [Boolean]
+      def restart(name, why:)
+        @say.call("restarting #{name}: #{why}")
+        @supervisor.restart(name)
+      end
+
+      # Apply the toolbar's requests for this plan that arrived after +cursor+.
+      #
+      # @param cursor [String] a stream id
+      # @return [String] the last id read
+      def commands(cursor)
+        entries = live { @store.xread(@keys.app_commands, id: cursor) } || []
+        entries.each do |entry|
+          cursor = entry.id
+          command = Listing.parse(entry.fields["json"])
+          apply(command) if command && command["plan"] == @plan
+        end
+        cursor
+      end
+
+      # @param command [Hash] `plan`, `action`, `target`
+      # @return [void]
+      def apply(command)
+        case command["action"]
+        when "stop"
+          @say.call("stopping: asked from the page")
+          @stopping.make_true
+        when "restart"
+          targets(command["target"]).each { restart(it.name, why: "asked from the page") }
+        end
+      end
+
+      # `backend` is every process but the previewed one, in declared order
+      # (spec open question 9); a name is that process; nothing is all of them.
+      #
+      # @return [Array<OpenLanes::Apps::ProcessSpec>]
+      def targets(target)
+        case target
+        when nil, "" then @definition.processes
+        when "backend" then @definition.backend
+        else Array(@definition.process(target))
+        end
+      end
+
+      # Commands written before this runner started are not for it.
+      #
+      # @return [String]
+      def newest_command = live { @store.xrevrange(@keys.app_commands, count: 1).first&.id } || "0-0"
+
+      # Run a Redis call when there is a store, and survive one that went
+      # away: the app matters more than the board.
+      #
+      # @return [Object, nil]
+      def live
+        return nil unless @store
+
+        yield
+      rescue Live::Unavailable => e
+        @say.call("Redis: #{e.message}") unless @said_unavailable
+        @said_unavailable = true
+        nil
+      end
+    end
+  end
+end

data/lib/openlanes/apps/status.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "time"
+
+module OpenLanes
+  module Apps
+    # Where one process of a running app stands, and the `<app>` object of
+    # the `apps` and `app` events the control room reads (plan 012, B1).
+    # The Preview tab draws only what arrives in this shape, so every field
+    # is said here once and {#to_h} is the wire.
+    #
+    # @!attribute [r] plan
+    #   @return [String] the ordinal, `012.00`
+    # @!attribute [r] branch
+    #   @return [String] the checkout's branch
+    # @!attribute [r] process
+    #   @return [String] the process's name
+    # @!attribute [r] state
+    #   @return [String] one of {STATES}
+    # @!attribute [r] port
+    #   @return [Integer] the port it was given
+    # @!attribute [r] preview
+    #   @return [Boolean] the process the tab shows
+    # @!attribute [r] url
+    #   @return [String] `http://127.0.0.1:<port><ready path or />`
+    # @!attribute [r] framing
+    #   @return [String, nil] `frame` or `window` once the preview process is
+    #     ready; nil before that and on every other process
+    # @!attribute [r] reason
+    #   @return [String, nil] why it failed, for a person
+    # @!attribute [r] at
+    #   @return [Time] when it entered this state
+    Status = Data.define(:plan, :branch, :process, :state, :port, :preview, :url, :framing, :reason, :at) do
+      def initialize(plan:, branch:, process:, state:, port:, preview: false, url: nil, framing: nil, reason: nil, at: Time.now)
+        raise ArgumentError, "state #{state.inspect} is not one of #{Status::STATES.join(", ")}" unless Status::STATES.include?(state.to_s)
+
+        super(plan:, branch:, process:, state: state.to_s, port:, preview:, url: url || "http://#{Status::HOST}:#{port}/",
+          framing: framing&.to_s, reason:, at:)
+      end
+
+      # @return [Boolean]
+      def ready? = state == "ready"
+
+      # @return [Boolean]
+      def failed? = state == "failed"
+
+      # @return [Hash] the wire's `<app>`, string keys
+      def to_h
+        { "plan" => plan, "branch" => branch, "process" => process, "state" => state, "port" => port,
+          "preview" => preview, "url" => url, "framing" => framing, "reason" => reason, "at" => at.utc.iso8601 }
+      end
+    end
+
+    class Status
+      # Every state a process passes through.
+      STATES = %w[starting ready restarting stopped failed].freeze
+
+      # Where every app listens: nothing here is reachable from another machine.
+      HOST = "127.0.0.1"
+    end
+  end
+end

data/lib/openlanes/apps/supervisor.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Apps
+    # Runs one plan's app (plan 012, B4): every process in `app:` started in
+    # declared order, each on a port from {Ports}, the next only once the
+    # previous is ready, and all of them stopped together.
+    #
+    # Every process is told every port (`PORT_API`, `PORT_WEB`) before the
+    # first one starts, so a web process can find its API. Ports are
+    # reserved up front for the same reason.
+    #
+    # A process runs as `sh -c <start>` through {Execution::Child}, which
+    # leads a process group of its own: a dev server's watcher and workers
+    # are grandchildren, and only a group stop reaches them. `Child` also
+    # kills every group still running when this Ruby exits, which is what
+    # stops the app when its runner does.
+    #
+    # Each transition is handed to +publisher+ as a {Status}; the runner
+    # writes it to Redis for the Preview tab, and plan 014 reads the same
+    # {#statuses} for its report.
+    class Supervisor
+      # The app did not come up. The message is the reason, for a person;
+      # everything that had started has been stopped by the time it is raised.
+      # {#process} names the one that failed, so its {#log_tail} can be read
+      # after the stop: verification quotes it when it rejects (M1).
+      class StartFailed < Error
+        # @return [String, nil] the process that did not become ready
+        attr_reader :process
+
+        # @param message [String]
+        # @param process [String, nil]
+        def initialize(message = nil, process: nil)
+          super(message)
+          @process = process
+        end
+      end
+
+      # Seconds a process has to become ready (spec open question 10).
+      READY_TIMEOUT = 30
+
+      # Seconds between readiness probes.
+      POLL = 0.1
+
+      # Lines of a process's output kept, for the reason when it fails.
+      TAIL = 20
+
+      # What a process says when another took its port between the probe
+      # and the bind: the one failure worth a second attempt.
+      RACE = /EADDRINUSE|address already in use/i
+
+      # One process the supervisor started.
+      Running = Struct.new(:spec, :child, :waiter, :reader, :tail)
+
+      # @param definition [OpenLanes::Apps::Definition]
+      # @param root [String] the checkout every process runs in
+      # @param plan [String] the ordinal
+      # @param branch [String]
+      # @param registry [OpenLanes::Apps::Ports]
+      # @param publisher [#call, nil] given each {Status} as it happens
+      # @param probe [#ready?]
+      # @param framing [#check]
+      # @param origin [String] the control room's origin, for {Framing}
+      # @param ready_timeout [Numeric] seconds
+      # @param poll [Numeric] seconds between probes
+      # @param output [#call, nil] given a process's name and each line it prints
+      def initialize(definition:, root:, plan:, branch:, registry: Ports.new, publisher: nil, probe: Probe, framing: Framing,
+        origin: Framing::ORIGIN, ready_timeout: READY_TIMEOUT, poll: POLL, output: nil)
+        @definition = definition
+        @root = root
+        @plan = plan
+        @branch = branch
+        @registry = registry
+        @publisher = publisher
+        @probe = probe
+        @framing = framing
+        @origin = origin
+        @ready_timeout = ready_timeout
+        @poll = poll
+        @output = output
+        @running = {}
+        @ports = {}
+        @statuses = {}
+        @tails = {}
+        @mutex = Mutex.new
+      end
+
+      # @return [OpenLanes::Apps::Definition]
+      attr_reader :definition
+
+      # @return [String]
+      attr_reader :plan
+
+      # Start every process in order and wait for each to be ready.
+      #
+      # A start whose process lost its port to somebody else between the
+      # reservation and the bind is tried once more, from fresh ports.
+      #
+      # @return [self]
+      # @raise [OpenLanes::Apps::Supervisor::StartFailed]
+      def start
+        launch
+        self
+      rescue StartFailed => e
+        raise unless e.message.match?(RACE)
+
+        launch
+        self
+      end
+
+      # Stop every process, last started first, and give its port back.
+      #
+      # @return [void]
+      def stop
+        @running.keys.reverse_each { halt(it) }
+        @ports.each_value { @registry.release(it) }
+        @ports.clear
+      end
+
+      # Stop one process and start it again on the same port (B5): what a
+      # change to its `restart_on` files, or Restart backend, asks for.
+      # Its siblings are not touched.
+      #
+      # @param name [String]
+      # @return [Boolean] whether it came back ready
+      def restart(name)
+        spec = definition.process(name) or raise ArgumentError, "no process #{name.inspect} in this app"
+        return false unless @ports.key?(spec.name)
+
+        publish(spec, "restarting")
+        halt(spec.name, quietly: true)
+        bring_up(spec, nil)
+      end
+
+      # @return [Array<OpenLanes::Apps::Status>] the latest of each process, in start order
+      def statuses = @mutex.synchronize { definition.processes.filter_map { @statuses[it.name] } }
+
+      # @return [OpenLanes::Apps::Status, nil] the process the Preview tab shows
+      def preview = statuses.find(&:preview)
+
+      # @param name [String]
+      # @return [Integer, nil] the pid of the process's group leader
+      def pid(name) = @running[name.to_s]&.child&.pid
+
+      # @param name [String]
+      # @return [Integer, nil]
+      def port(name) = @ports[name.to_s]
+
+      # The last lines a process printed, kept after it is stopped. A failed
+      # start stops everything before it raises, and M1 wants the failing
+      # process's last 20 lines in the rejection, which {Status#reason}
+      # (five lines, for the Preview tab) is too short to carry.
+      #
+      # @param name [String]
+      # @param lines [Integer] at most {TAIL}
+      # @return [Array<String>] oldest first; empty for a process never started
+      def log_tail(name, lines = TAIL) = @mutex.synchronize { Array(@tails[name.to_s]).last(lines) }
+
+      private
+
+      # @return [void]
+      # @raise [StartFailed]
+      def launch
+        @ports = definition.processes.to_h { [it.name, @registry.reserve(root: @root, plan:, process: it.name)] }
+        @env = definition.processes.to_h { [it.port_env, @ports.fetch(it.name).to_s] }
+        definition.processes.each do |spec|
+          next if bring_up(spec, "starting")
+
+          reason = @statuses.fetch(spec.name).reason
+          stop
+          raise StartFailed.new(reason, process: spec.name)
+        end
+      end
+
+      # Spawn, then wait until it is ready, it exits, or time runs out.
+      #
+      # @param spec [OpenLanes::Apps::ProcessSpec]
+      # @param state [String, nil] what to say while it comes up; nil when
+      #   that was said already, as a restart does before it stops the old one
+      # @return [Boolean] ready
+      def bring_up(spec, state)
+        publish(spec, state) if state
+        running = spawn(spec)
+        outcome = await(spec, running)
+        return publish(spec, "failed", reason: reason(spec, running, outcome)).then { false } unless outcome == :ready
+
+        publish(spec, "ready", framing: (@framing.check(url(spec), origin: @origin) if spec.preview?))
+        true
+      end
+
+      # @return [Running]
+      def spawn(spec)
+        child = Execution::Child.spawn(["sh", "-c", spec.start], chdir: @root, env: @env)
+        tail = []
+        @mutex.synchronize { @tails[spec.name] = tail }
+        reader = Thread.new { read(spec.name, child, tail) }
+        waiter = Thread.new { child.wait }
+        @running[spec.name] = Running.new(spec, child, waiter, reader, tail)
+      end
+
+      # @return [void]
+      def read(name, child, tail)
+        pending = +""
+        child.each_chunk do |text|
+          pending << text
+          while (line = pending.slice!(/\A[^\n]*\n/))
+            line = line.chomp
+            @mutex.synchronize do
+              tail.push(line)
+              tail.shift while tail.size > TAIL
+            end
+            @output&.call(name, line)
+          end
+        end
+      end
+
+      # @return [Symbol] :ready, :exited or :timeout
+      def await(spec, running)
+        deadline = UI.monotonic + @ready_timeout
+        loop do
+          return :exited unless running.waiter.alive?
+          return :ready if @probe.ready?(@ports.fetch(spec.name), path: spec.ready)
+          return :timeout if UI.monotonic >= deadline
+
+          sleep @poll
+        end
+      end
+
+      # @return [String]
+      def reason(spec, running, outcome)
+        port = @ports.fetch(spec.name)
+        said = if outcome == :exited
+                 running.reader.join(1)
+                 "#{spec.name} exited with status #{running.waiter.value&.exitstatus.inspect} before it was ready"
+               else
+                 halt(spec.name, quietly: true)
+                 what = spec.ready ? "2xx or 3xx on #{spec.ready}" : "there"
+                 "#{spec.name} was given port #{port} and nothing answered #{what} within #{@ready_timeout} s"
+               end
+        lines = @mutex.synchronize { running.tail.last(5) }
+        lines.empty? ? said : "#{said}; it said:\n#{lines.join("\n")}"
+      end
+
+      # TERM the process's group, KILL what is left after the grace, and
+      # wait for the leader.
+      #
+      # @return [void]
+      def halt(name, quietly: false)
+        running = @running.delete(name) or return
+        running.child.terminate
+        running.waiter.join
+        running.reader.join(Execution::Child::DRAIN_GRACE)
+        # A process that failed stays failed: its reason is what a person needs.
+        publish(running.spec, "stopped") unless quietly || @statuses[name]&.failed?
+      end
+
+      # @return [String] what the tab opens: the app's root, not its health check
+      def url(spec) = "http://#{Status::HOST}:#{@ports.fetch(spec.name)}/"
+
+      # @return [OpenLanes::Apps::Status]
+      def publish(spec, state, framing: nil, reason: nil)
+        status = Status.new(plan:,
+          branch: @branch,
+          process: spec.name,
+          state:,
+          port: @ports.fetch(spec.name),
+          preview: spec.preview?,
+          url: url(spec),
+          framing:,
+          reason:)
+        @mutex.synchronize { @statuses[spec.name] = status }
+        @publisher&.call(status)
+        status
+      end
+    end
+  end
+end

data/lib/openlanes/apps/watcher.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Apps
+    # Which processes' `restart_on` files changed since it last looked
+    # (plan 012, decision 5).
+    #
+    # Polling, not a file-event gem: one more dependency for a check that
+    # runs once a second over a handful of globs is not worth its native
+    # extension, and a poll is something a spec can drive tick by tick.
+    #
+    # A file counts as changed when it appears, disappears, or its `mtime`
+    # or size moves. Globs are Ruby's `Dir.glob`, relative to the checkout,
+    # with `**/` recursive and `{a,b}` alternatives; a dotfile matches only
+    # a pattern that names the dot.
+    class Watcher
+      # @param root [String] the checkout the globs are relative to
+      # @param definition [OpenLanes::Apps::Definition]
+      def initialize(root:, definition:)
+        @root = root
+        @watched = definition.processes.reject { it.restart_on.empty? }
+        @seen = snapshot
+      end
+
+      # @return [Array<String>] names of processes with a changed file, in
+      #   declared order; empty on a quiet tick
+      def changed
+        now = snapshot
+        names = @watched.map(&:name).reject { now[it] == @seen[it] }
+        @seen = now
+        names
+      end
+
+      private
+
+      # @return [Hash{String => Hash{String => Array}}] process name to path to mtime and size
+      def snapshot
+        @watched.to_h do |spec|
+          files = Dir.glob(spec.restart_on, File::FNM_EXTGLOB, base: @root).sort.to_h do |path|
+            stat = File.stat(File.join(@root, path))
+            [path, [stat.mtime.to_r, stat.size]]
+          rescue SystemCallError
+            [path, nil]
+          end
+          [spec.name, files]
+        end
+      end
+    end
+  end
+end