herb 0.10.4 → 0.11.0

data/lib/herb/dev/server.rb

@@ -4,43 +4,42 @@ require "fileutils"
 require "socket"
 require "json"
 
-begin
-  require "websocket"
-rescue LoadError
-  require "bundler/inline"
-
-  gemfile do
-    source "https://rubygems.org"
-    gem "websocket"
-  end
+require_relative "../../herb"
 
-  require "websocket"
-end
+Herb.ensure_installed("websocket")
 
+require_relative "protocol"
 require_relative "server_entry"
 
 module Herb
   module Dev
     class Server
-      DEFAULT_PORT = 8592
-      HANDSHAKE_TIMEOUT = 5
+      DEFAULT_PORT = 8592 #: Integer # "HERB".bytes.map { (it - 64).digits.sum }.join
+      HANDSHAKE_TIMEOUT = 5 #: Integer
+      ROLES = [:browser, :app].freeze #: Array[Symbol]
 
-      attr_reader :port, :project_path
+      Client = Struct.new(:socket, :version, :mutex, :role, keyword_init: true)
 
-      Client = Data.define(:socket, :version, :mutex)
+      attr_reader :port #: Integer
+      attr_reader :project_path #: String?
 
-      def initialize(port: DEFAULT_PORT, project_path: nil)
+      #: (?port: Integer, ?project_path: String?, ?kind: String) -> void
+      def initialize(port: DEFAULT_PORT, project_path: nil, kind: "standalone")
         @port = port
         @project_path = project_path
+        @kind = kind
         @clients = [] #: Array[Client]
         @mutex = Mutex.new
         @server = nil
         @accept_thread = nil
         @entry = nil
+        @on_client = nil #: (^(Symbol, Integer) -> void)?
+        @on_welcome = nil #: (^() -> Array[Hash[Symbol, untyped]])?
       end
 
+      #: () -> void
       def start
-        @entry = ServerEntry.new(pid: Process.pid, port: @port, project: @project_path)
+        @entry = ServerEntry.new(pid: Process.pid, port: @port, project: @project_path, kind: @kind)
         @entry.save
         @server = TCPServer.new("0.0.0.0", @port)
 
@@ -54,6 +53,7 @@ module Herb
         end
       end
 
+      #: () -> void
       def stop
         @mutex.synchronize do
           @clients.each { |client| safely_close(client.socket) }
@@ -66,11 +66,13 @@ module Herb
         @entry&.remove
       end
 
-      def broadcast(message)
+      #: (Hash[Symbol, untyped] | String, ?to: Symbol) -> void
+      def broadcast(message, to: :all)
         data = message.is_a?(String) ? message : JSON.generate(message)
 
         failed_clients = []
         clients_snapshot = @mutex.synchronize { @clients.dup }
+        clients_snapshot = clients_snapshot.select { |client| client.role == :browser } if to == :browsers
 
         clients_snapshot.each do |client|
           frame = WebSocket::Frame::Outgoing::Server.new(version: client.version, data: data, type: :text)
@@ -85,17 +87,53 @@ module Herb
           failed_clients << client
         end
 
-        return unless failed_clients.any?
+        failed_clients.each { |client| unregister(client.socket) }
+      end
+
+      #: () { (Symbol, Integer) -> void } -> void
+      def on_client(&block)
+        @on_client = block
+      end
+
+      #: () { () -> Array[Hash[Symbol, untyped]] } -> void
+      def on_welcome(&block)
+        @on_welcome = block
+      end
+
+      #: (Client) -> void
+      def register(client)
+        count = @mutex.synchronize {
+          @clients << client
+
+          @clients.size
+        }
+
+        @on_client&.call(:connected, count)
+      end
+
+      #: (untyped) -> void
+      def unregister(socket)
+        removed = false
+        count = 0
 
         @mutex.synchronize do
-          failed_clients.each { |client| @clients.delete(client) }
+          before = @clients.size
+
+          @clients.delete_if { |client| client.socket == socket }
+
+          removed = @clients.size < before
+          count = @clients.size
         end
+
+        @on_client&.call(:disconnected, count) if removed
       end
 
+      #: () -> Integer
       def client_count
         @mutex.synchronize { @clients.size }
       end
 
+      #: (Integer) -> bool
       def self.port_available?(port)
         server = TCPServer.new("0.0.0.0", port)
         server.close
@@ -105,6 +143,7 @@ module Herb
         false
       end
 
+      #: (?Integer) -> Integer?
       def self.find_available_port(starting_port = DEFAULT_PORT)
         port = starting_port
 
@@ -118,14 +157,37 @@ module Herb
         nil
       end
 
+      #: (Client, String) -> void
+      def handle_text_frame(client, data)
+        message = JSON.parse(data)
+
+        return unless message.is_a?(Hash)
+        return unless message["type"] == "hello"
+
+        role = message["role"].to_s.to_sym
+
+        client.role = role if ROLES.include?(role)
+      rescue JSON::ParserError
+        nil
+      end
+
       private
 
+      #: () -> Array[Hash[Symbol, untyped]]
+      def broken_entries
+        @on_welcome&.call || []
+      rescue StandardError
+        []
+      end
+
+      #: (untyped) -> void
       def safely_close(resource)
         resource&.close
       rescue StandardError
         nil
       end
 
+      #: (untyped) -> void
       def handle_connection(socket)
         socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
 
@@ -155,15 +217,16 @@ module Herb
 
         welcome = WebSocket::Frame::Outgoing::Server.new(
           version: handshake.version,
-          data: JSON.generate({ type: "welcome", project: @project_path }),
+          data: JSON.generate(Protocol.welcome(project: @project_path, broken_files: broken_entries)),
           type: :text
         )
 
         socket.write(welcome.to_s)
         socket.flush
 
-        client = Client.new(socket: socket, version: handshake.version, mutex: Mutex.new)
-        @mutex.synchronize { @clients << client }
+        client = Client.new(socket: socket, version: handshake.version, mutex: Mutex.new, role: :browser)
+
+        register(client)
 
         frame_parser = WebSocket::Frame::Incoming::Server.new(version: handshake.version)
 
@@ -189,16 +252,16 @@ module Herb
 
               client.mutex.synchronize { socket.write(pong.to_s) }
             when :text
-              nil
+              handle_text_frame(client, frame.data)
             end
           end
         end
       rescue IOError, Errno::ECONNRESET, Errno::EPIPE
         # client disconnected
       rescue StandardError => e
-        warn "[herb-dev-server] connection error: #{e.class}: #{e.message}"
+        warn "[Herb Dev Server] connection error: #{e.class}: #{e.message}"
       ensure
-        @mutex.synchronize { @clients.delete_if { |client| client.socket == socket } }
+        unregister(socket)
 
         safely_close(socket)
       end

data/lib/herb/dev/server_entry.rb

@@ -6,45 +6,65 @@ require "fileutils"
 module Herb
   module Dev
     class ServerEntry
-      SERVERS_DIR = File.expand_path("~/.herb/dev-servers").freeze
-      REQUIRED_KEYS = ["pid", "port", "project", "started_at"].freeze
+      SERVERS_DIR = File.expand_path("~/.herb/dev-servers").freeze #: String
+      REQUIRED_KEYS = ["pid", "port", "project", "started_at"].freeze #: Array[String]
 
-      attr_reader :pid, :port, :project, :started_at
+      KINDS = ["standalone", "embedded"].freeze #: Array[String]
 
-      def initialize(pid:, port:, project:, started_at: Time.now.utc.iso8601)
+      attr_reader :pid #: Integer
+      attr_reader :port #: Integer
+      attr_reader :project #: String?
+      attr_reader :started_at #: String
+      attr_reader :kind #: String
+
+      #: (pid: Integer, port: Integer, project: String?, ?started_at: String, ?kind: String) -> void
+      def initialize(pid:, port:, project:, started_at: Time.now.utc.iso8601, kind: "standalone")
         @pid = pid
         @port = port
         @project = project
         @started_at = started_at
+        @kind = KINDS.include?(kind.to_s) ? kind.to_s : "standalone"
+      end
+
+      #: () -> bool
+      def embedded?
+        @kind == "embedded"
       end
 
+      #: () -> void
       def save
         FileUtils.mkdir_p(SERVERS_DIR)
         File.write(file_path, to_json)
       end
 
+      #: () -> void
       def remove
         File.delete(file_path)
       rescue StandardError
         nil
       end
 
+      #: () -> bool
       def alive?
         self.class.process_alive?(pid)
       end
 
+      #: () -> Hash[Symbol, untyped]
       def to_hash
-        { pid: pid, port: port, project: project, started_at: started_at }
+        { pid: pid, port: port, project: project, started_at: started_at, kind: kind }
       end
 
+      #: (*untyped) -> String
       def to_json(*)
         JSON.generate(to_hash)
       end
 
+      #: () -> String
       def project_name
         project&.split("/")&.last || "unknown"
       end
 
+      #: () -> bool
       def stop!
         Process.kill("INT", pid)
         remove
@@ -55,6 +75,7 @@ module Herb
       end
 
       class << self
+        #: () -> Array[ServerEntry]
         def all
           FileUtils.mkdir_p(SERVERS_DIR)
 
@@ -74,18 +95,29 @@ module Herb
           end
         end
 
+        #: (Integer) -> ServerEntry?
         def find_by_port(port)
           all.find { |entry| entry.port == port }
         end
 
+        #: (String) -> ServerEntry?
         def find_by_project(project_path)
           all.find { |entry| entry.project == project_path }
         end
 
+        #: (?String?) -> Integer?
+        def port_for(project_path = nil)
+          find_by_project(project_path || Dir.pwd)&.port
+        rescue StandardError
+          nil
+        end
+
+        #: () -> void
         def stop_all
           all.each(&:stop!)
         end
 
+        #: (Integer?) -> bool
         def process_alive?(pid)
           return false unless pid
 
@@ -97,6 +129,7 @@ module Herb
 
         private
 
+        #: (String) -> ServerEntry?
         def load_file(path)
           data = JSON.parse(File.read(path))
 
@@ -106,7 +139,8 @@ module Herb
             pid: data["pid"],
             port: data["port"],
             project: data["project"],
-            started_at: data["started_at"]
+            started_at: data["started_at"],
+            kind: data["kind"] || "standalone"
           )
         rescue JSON::ParserError, Errno::ENOENT, Errno::EACCES
           begin
@@ -120,6 +154,7 @@ module Herb
 
       private
 
+      #: () -> String
       def file_path
         File.join(SERVERS_DIR, "#{pid}.json")
       end

data/lib/herb/dev/watcher.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "../../herb"
+require_relative "../configuration"
+require_relative "assets"
+
+module Herb
+  module Dev
+    # Watches a project's templates and says which one changed.
+    #
+    # Cruise reports raw filesystem events, and most of them are noise. This keeps the last
+    # content it saw for every template, filters events through the project's include and
+    # exclude patterns, and emits one normalized event per change that actually changed
+    # something, carrying both the previous and the current source so nothing downstream has
+    # to read the file again.
+    #
+    #     watcher = Herb::Dev::Watcher.new(config: config, root: root) do |event|
+    #       pipeline.handle_event(event)
+    #     end
+    #
+    #     watcher.run    # blocks, for the CLI
+    #     watcher.spawn  # returns a Thread, for an embedded host
+    #
+    class Watcher
+      KINDS = ["created", "modified", "removed"].freeze #: Array[String]
+
+      Event = Data.define(
+        :kind,          #: Symbol
+        :path,          #: String
+        :relative_path, #: String
+        :previous,      #: String?
+        :current        #: String?
+      )
+
+      attr_reader :file_states #: Hash[String, String]
+      attr_reader :watch_paths #: Array[String]
+
+      #: (config: Herb::Configuration, root: String, ?watch_paths: Array[String]?) { (Event) -> void } -> void
+      def initialize(config:, root:, watch_paths: nil, &on_event)
+        @config = config
+        @root = root
+        @on_event = on_event
+        @watch_paths = resolve_watch_paths(watch_paths) #: Array[String]
+        @file_states = {} #: Hash[String, String]
+        @assets = Assets.new
+        @include_patterns = config.file_include_patterns
+        @exclude_patterns = config.file_exclude_patterns
+        @thread = nil #: Thread?
+        @stopped = false
+      end
+
+      #: (?String) -> Integer
+      def index(path = @root)
+        @config.find_files(path).each do |file_path|
+          @file_states[file_path] = File.read(file_path)
+        rescue StandardError
+          nil
+        end
+
+        @assets.index(path)
+
+        @file_states.size
+      end
+
+      #: () -> Hash[String, String]
+      def sources
+        @file_states.transform_keys { |path| relative_for(path) }
+      end
+
+      #: () -> void
+      def run
+        Herb.ensure_installed("cruise")
+
+        Cruise.watch(*@watch_paths, only: KINDS) do |raw|
+          break if @stopped
+
+          handle(raw)
+        end
+      end
+
+      #: () -> Thread
+      def spawn
+        @thread = Thread.new { run }
+        @thread.name = "herb-dev-watcher"
+
+        @thread
+      end
+
+      #: () -> void
+      def stop
+        @stopped = true
+        @thread&.kill
+        @thread = nil
+      end
+
+      private
+
+      #: (Array[String]?) -> Array[String]
+      def resolve_watch_paths(paths)
+        return [@root] if paths.nil?
+
+        candidates = Array(paths).filter_map do |path|
+          expanded = File.expand_path(path.to_s, @root)
+
+          next unless File.directory?(expanded)
+          next unless expanded == @root || expanded.start_with?("#{@root}/")
+
+          expanded
+        end.uniq.sort
+
+        return [@root] if candidates.empty?
+        return [@root] if candidates.include?(@root)
+
+        narrowed = candidates.reject do |path|
+          candidates.any? { |other| other != path && path.start_with?("#{other}/") }
+        end
+
+        (narrowed + asset_watch_paths(narrowed)).sort
+      end
+
+      #: (Array[String]) -> Array[String]
+      def asset_watch_paths(narrowed)
+        builds = File.join(@root, Assets::ROOT)
+
+        return [] unless File.directory?(builds)
+        return [] if narrowed.any? { |path| builds == path || builds.start_with?("#{path}/") }
+
+        [builds]
+      end
+
+      #: (String) -> String
+      def relative_for(path)
+        path.delete_prefix("#{@root}/")
+      end
+
+      #: (Cruise::Event) -> void
+      def handle(raw)
+        path = raw.path
+        relative_path = relative_for(path)
+
+        return handle_asset(path, relative_path) if @config.path_included?(relative_path, Assets::PATTERNS)
+        return if @config.path_excluded?(relative_path, @exclude_patterns, @include_patterns)
+        return unless @config.path_included?(relative_path, @include_patterns)
+
+        event = normalize(raw.kind, path, relative_path)
+
+        @on_event.call(event) if event
+      end
+
+      #: (String, String) -> void
+      def handle_asset(path, relative_path)
+        return unless @assets.changed?(path)
+
+        @on_event.call(Event.new(kind: Assets.kind_for(path), path: path, relative_path: relative_path, previous: nil, current: nil))
+      end
+
+      #: (String, String, String) -> Event?
+      def normalize(kind, path, relative_path)
+        if kind == "removed"
+          previous = @file_states.delete(path)
+
+          return Event.new(kind: :removed, path: path, relative_path: relative_path, previous: previous, current: nil)
+        end
+
+        return nil unless File.exist?(path)
+
+        current = File.read(path)
+        previous = @file_states[path]
+        @file_states[path] = current
+
+        return Event.new(kind: :added, path: path, relative_path: relative_path, previous: nil, current: current) if previous.nil?
+        return nil if previous == current
+
+        Event.new(kind: :changed, path: path, relative_path: relative_path, previous: previous, current: current)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/herb/dev.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "dev/watcher"
+require_relative "dev/classifier"
+require_relative "dev/protocol"
+require_relative "dev/pipeline"
+require_relative "dev/embedded"
+
+module Herb
+  # The development server: a file watcher, a websocket, and the pipeline between them.
+  #
+  # The dev server never compiles a template itself, because slot identity depends on the
+  # visitor stack the application compiles with, and only the application knows that stack.
+  # A host that does know it registers a compiler here:
+  #
+  #     Herb::Dev.compiler = ->(source, relative_path) { ... }
+  #
+  # The compiler returns nil for a file it cannot compile at all, and otherwise an object
+  # answering `mode`, `manifest`, `version`, `slot_entries`, `statics`, `static_markup` and
+  # `diagnostics`. Without one, the pipeline still classifies changes and tells browsers to
+  # fetch, so everything degrades instead of breaking.
+  #
+  module Dev
+    # @rbs!
+    #   interface _Compiler
+    #     def call: (String source, String relative_path) -> _CompiledSchema?
+    #   end
+    #
+    #   interface _CompiledSchema
+    #     def mode: () -> Symbol?
+    #     def manifest: () -> Hash[String, untyped]?
+    #     def version: () -> String?
+    #     def slot_entries: () -> Array[Hash[Symbol, untyped]]?
+    #     def statics: () -> Hash[String, String]?
+    #     def static_markup: () -> String?
+    #     def diagnostics: () -> Array[untyped]?
+    #   end
+
+    class << self
+      # @rbs skip
+      attr_accessor :compiler
+    end
+
+    # @rbs!
+    #   attr_accessor self.compiler: _Compiler?
+
+    # Starts the watcher and the websocket server inside the current process, for a host
+    # that already runs the application, like a Rails server in development. Everything a
+    # start would collide with makes it a no-op instead of an error, so a host can call it
+    # unconditionally:
+    #
+    #     Rails.application.server { Herb::Dev.boot(Rails.root.to_s) }
+    #
+    #: (String, ?watch_paths: Array[String]?, ?environment: String?, ?logger: ^(String) -> void) -> Embedded?
+    def self.boot(root, watch_paths: nil, environment: nil, logger: ->(message) { warn(message) })
+      environment ||= ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+
+      return nil unless environment == "development"
+
+      current = booted
+
+      return current if current && current.pid == Process.pid
+
+      require_relative "dev/server"
+
+      begin
+        Herb.ensure_installed("cruise")
+      rescue StandardError
+        logger.call("Herb dev server not started. The 'cruise' gem is required, add it to the Gemfile.")
+
+        return nil
+      end
+
+      expanded = File.realpath(File.expand_path(root))
+      existing = ServerEntry.find_by_project(expanded)
+
+      if existing
+        holder = existing.embedded? ? "inside another server for this app" : "as a standalone `herb dev`"
+
+        logger.call("Herb dev server already running for this project #{holder} (PID: #{existing.pid}, port: #{existing.port}). Stop that process, then restart this server.")
+
+        return nil
+      end
+
+      port = Server.find_available_port
+
+      unless port
+        logger.call("Herb dev server not started. No available ports found.")
+
+        return nil
+      end
+
+      configuration = Herb::Configuration.load(expanded)
+      server = Server.new(port: port, project_path: expanded, kind: "embedded")
+      pipeline = Pipeline.new(server: server, configuration: configuration)
+
+      server.on_welcome { pipeline.broken_entries }
+
+      server.on_client do |event, count|
+        logger.call("Herb dev server client #{event} (#{count} #{count == 1 ? "connection" : "connections"} open)")
+      end
+
+      pipeline.on_classified do |event, classification|
+        line = activity_line(event, classification)
+
+        logger.call(line) if line
+      end
+
+      watcher = Watcher.new(config: configuration, root: expanded, watch_paths: watch_paths) do |event|
+        pipeline.handle_event(event)
+      end
+
+      watcher.index
+      pipeline.remember_broken(watcher.sources)
+      server.start
+      watcher.spawn
+
+      @booted = Embedded.new(server, watcher, pipeline, Process.pid)
+
+      at_exit { shutdown }
+
+      watching = watcher.watch_paths.map { |path| path == expanded ? path : path.delete_prefix("#{expanded}/") }.join(", ")
+
+      logger.call("Herb dev server watching #{watching} on ws://localhost:#{port}")
+
+      @booted
+    end
+
+    #: (Watcher::Event, Classifier::Classification?) -> String?
+    def self.activity_line(event, classification)
+      file = event.relative_path
+
+      case event.kind
+      when :removed then "#{file} removed"
+      when :added then "#{file} added"
+      else
+        return nil unless classification
+
+        case classification.kind
+        when :parse_error
+          "#{file} has #{classification.errors.length} parse error#{"s" unless classification.errors.length == 1}"
+        when :static, :dynamic
+          "#{file} changed (#{classification.kind}, #{classification.operations.length} operation#{"s" unless classification.operations.length == 1})"
+        end
+      end
+    end
+
+    #: () -> Embedded?
+    def self.booted
+      @booted = nil if @booted && @booted.pid != Process.pid
+
+      @booted
+    end
+
+    #: () -> void
+    def self.shutdown
+      booted&.stop
+
+      @booted = nil
+    end
+  end
+end