docyard 0.8.0 → 1.0.0

data/lib/docyard/server/dev_server.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
-require "webrick"
-require "stringio"
-require_relative "file_watcher"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require "puma/log_writer"
 require_relative "rack_application"
+require_relative "sse_server"
+require_relative "file_watcher"
 require_relative "../config"
+require_relative "../navigation/sidebar/cache"
 
 module Docyard
-  class Server
+  class DevServer
     DEFAULT_PORT = 4200
     DEFAULT_HOST = "localhost"
 
@@ -19,27 +23,34 @@ module Docyard
       @docs_path = docs_path
       @search_enabled = search
       @config = Config.load
-      @file_watcher = FileWatcher.new(File.expand_path(docs_path))
       @search_indexer = nil
-      @app = nil
+      @sse_server = nil
+      @file_watcher = nil
+      @launcher = nil
+      @sidebar_cache = nil
     end
 
     def start
       validate_docs_directory!
+      build_sidebar_cache
       generate_search_index if @search_enabled
-      initialize_app
+      setup_hot_reload
       print_server_info
-      @file_watcher.start
-
-      http_server.mount_proc("/") { |req, res| handle_request(req, res) }
-      trap("INT") { shutdown_server }
-
-      http_server.start
+      run_server
+    ensure
       cleanup
     end
 
     private
 
+    def build_sidebar_cache
+      @sidebar_cache = Sidebar::Cache.new(
+        docs_path: File.expand_path(docs_path),
+        config: @config
+      )
+      @sidebar_cache.build
+    end
+
     def generate_search_index
       @search_indexer = Search::DevIndexer.new(
         docs_path: File.expand_path(docs_path),
@@ -48,17 +59,45 @@ module Docyard
       @search_indexer.generate
     end
 
-    def initialize_app
-      @app = RackApplication.new(
-        docs_path: File.expand_path(docs_path),
-        file_watcher: @file_watcher,
-        config: @config,
-        pagefind_path: @search_indexer&.pagefind_path
+    def setup_hot_reload
+      @sse_server = SSEServer.new(port: sse_port)
+      @sse_server.start
+
+      @file_watcher = FileWatcher.new(
+        docs_path: docs_path,
+        on_change: ->(change_type) { handle_file_change(change_type) }
       )
+      @file_watcher.start
+    end
+
+    def sse_port
+      port + 1
+    end
+
+    def handle_file_change(change_type)
+      invalidate_sidebar_cache if change_type == :full
+      log_file_change(change_type)
+      @sse_server.broadcast("reload", { type: change_type.to_s })
+    end
+
+    def invalidate_sidebar_cache
+      @sidebar_cache&.invalidate
+      @sidebar_cache&.build
+    end
+
+    def log_file_change(change_type)
+      message = case change_type
+                when :content then "Content changed, reloading..."
+                when :config then "Config changed, full reload..."
+                when :asset then "Asset changed, reloading..."
+                else "File changed, reloading..."
+                end
+      Docyard.logger.info("* #{message}")
     end
 
     def cleanup
-      @file_watcher.stop
+      @file_watcher&.stop
+      @sse_server&.stop
       @search_indexer&.cleanup
     end
 
@@ -70,48 +109,44 @@ module Docyard
     end
 
     def print_server_info
-      puts "Starting Docyard server..."
-      puts "=> Serving docs from: #{docs_path}/"
-      puts "=> Running at: http://#{host}:#{port}"
-      puts "=> Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}"
-      puts "=> Press Ctrl+C to stop\n"
+      Docyard.logger.info("Starting Docyard server...")
+      Docyard.logger.info("* Version: #{Docyard::VERSION}")
+      Docyard.logger.info("* Running at: http://#{host}:#{port}")
+      Docyard.logger.info("* Hot reload: ws://127.0.0.1:#{sse_port}")
+      Docyard.logger.info("* Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}")
+      Docyard.logger.info("Use Ctrl+C to stop\n")
     end
 
-    def shutdown_server
-      puts "\nShutting down server..."
-      http_server.shutdown
-    end
+    def run_server
+      app = build_rack_app
+      puma_config = build_puma_config(app)
+      log_writer = Puma::LogWriter.strings
 
-    def http_server
-      @http_server ||= WEBrick::HTTPServer.new(
-        Port: port,
-        BindAddress: host,
-        AccessLog: [],
-        Logger: WEBrick::Log.new(File::NULL)
-      )
+      @launcher = Puma::Launcher.new(puma_config, log_writer: log_writer)
+      @launcher.run
     end
 
-    def handle_request(req, res)
-      env = build_rack_env(req)
-      status, headers, body = @app.call(env)
-
-      res.status = status
-      headers.each { |key, value| res[key] = value }
-      body.each { |chunk| res.body << chunk }
+    def build_rack_app
+      RackApplication.new(
+        docs_path: File.expand_path(docs_path),
+        config: @config,
+        pagefind_path: @search_indexer&.pagefind_path,
+        sse_port: sse_port,
+        sidebar_cache: @sidebar_cache
+      )
     end
 
-    def build_rack_env(req)
-      {
-        "REQUEST_METHOD" => req.request_method,
-        "PATH_INFO" => req.path,
-        "QUERY_STRING" => req.query_string || "",
-        "SERVER_NAME" => req.host,
-        "SERVER_PORT" => req.port.to_s,
-        "rack.version" => Rack::VERSION,
-        "rack.url_scheme" => "http",
-        "rack.input" => StringIO.new,
-        "rack.errors" => $stderr
-      }
+    def build_puma_config(app)
+      server_host = host
+      server_port = port
+
+      Puma::Configuration.new do |config|
+        config.bind "tcp://#{server_host}:#{server_port}"
+        config.app app
+        config.workers 0
+        config.threads 4, 8
+        config.quiet
+      end
     end
   end
 end

data/lib/docyard/server/file_watcher.rb

@@ -4,39 +4,89 @@ require "listen"
 
 module Docyard
   class FileWatcher
-    attr_reader :last_modified_time
+    DEBOUNCE_DELAY = 0.1
+    ROOT_CONFIG_FILE = "docyard.yml"
+    CONFIG_FILES = %w[docyard.yml _sidebar.yml].freeze
+    CONTENT_EXTENSIONS = %w[.md .markdown].freeze
+    ASSET_EXTENSIONS = %w[.css .js .html .erb].freeze
 
-    def initialize(docs_path)
-      @docs_path = docs_path
-      @last_modified_time = Time.now
-      @listener = nil
+    def initialize(docs_path:, on_change:)
+      @docs_path = File.expand_path(docs_path)
+      @project_root = File.dirname(@docs_path)
+      @on_change = on_change
+      @docs_listener = nil
+      @config_listener = nil
+      @pending_changes = { content: false, config: false, asset: false }
+      @debounce_timer = nil
+      @mutex = Mutex.new
     end
 
     def start
-      @listener = Listen.to(@docs_path, only: /\.md$/) do |modified, added, removed|
-        handle_changes(modified, added, removed)
+      @docs_listener = Listen.to(@docs_path, latency: DEBOUNCE_DELAY) do |modified, added, removed|
+        handle_changes(modified + added + removed)
       end
+      @docs_listener.start
 
-      @listener.start
+      @config_listener = Listen.to(@project_root, only: /\Adocyard\.yml\z/) do |modified, added, removed|
+        handle_changes(modified + added + removed)
+      end
+      @config_listener.start
     end
 
     def stop
-      @listener&.stop
-    rescue StandardError => e
-      Docyard.logger.error "Error stopping file watcher: #{e.class} - #{e.message}"
+      @docs_listener&.stop
+      @config_listener&.stop
+      @debounce_timer&.kill
     end
 
-    def changed_since?(timestamp)
-      @last_modified_time > timestamp
+    private
+
+    def handle_changes(paths)
+      return if paths.empty?
+
+      @mutex.synchronize do
+        paths.each { |path| categorize_change(path) }
+        schedule_notification
+      end
     end
 
-    private
+    def categorize_change(path)
+      filename = File.basename(path)
+
+      if CONFIG_FILES.include?(filename)
+        @pending_changes[:config] = true
+      elsif CONTENT_EXTENSIONS.include?(File.extname(path))
+        @pending_changes[:content] = true
+      elsif ASSET_EXTENSIONS.include?(File.extname(path))
+        @pending_changes[:asset] = true
+      end
+    end
+
+    def schedule_notification
+      @debounce_timer&.kill
+      @debounce_timer = Thread.new do
+        sleep DEBOUNCE_DELAY
+        send_notification
+      end
+    end
+
+    def send_notification
+      changes = nil
+      @mutex.synchronize do
+        changes = @pending_changes.dup
+        @pending_changes = { content: false, config: false, asset: false }
+      end
+
+      change_type = determine_change_type(changes)
+      @on_change.call(change_type) if change_type
+    end
 
-    def handle_changes(modified, added, removed)
-      return if modified.empty? && added.empty? && removed.empty?
+    def determine_change_type(changes)
+      return :full if changes[:config]
+      return :content if changes[:content]
+      return :asset if changes[:asset]
 
-      @last_modified_time = Time.now
-      Docyard.logger.info "Files changed, triggering reload..."
+      nil
     end
   end
 end

data/lib/docyard/server/pagefind_handler.rb

@@ -31,7 +31,7 @@ module Docyard
       return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
 
       output_dir = config&.build&.output_dir || "dist"
-      File.join(output_dir, "pagefind", relative_path)
+      File.join(output_dir, "_docyard", "pagefind", relative_path)
     end
 
     def serve_file(file_path)

data/lib/docyard/server/preview_server.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
-require "webrick"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require "puma/log_writer"
 require_relative "../config"
+require_relative "static_file_app"
 
 module Docyard
   class PreviewServer
@@ -13,16 +17,13 @@ module Docyard
       @port = port
       @config = Config.load
       @output_dir = File.expand_path(@config.build.output)
+      @launcher = nil
     end
 
     def start
       validate_output_directory!
       print_server_info
-
-      server = create_server
-      trap("INT") { shutdown_server(server) }
-
-      server.start
+      run_server
     end
 
     private
@@ -35,38 +36,33 @@ module Docyard
     end
 
     def print_server_info
-      puts "Preview server starting..."
-      puts "=> Serving from: #{output_dir}/"
-      puts "=> Running at: http://localhost:#{port}"
-      puts "=> Press Ctrl+C to stop\n"
+      Docyard.logger.info("Starting preview server...")
+      Docyard.logger.info("* Version: #{Docyard::VERSION}")
+      Docyard.logger.info("* Running at: http://localhost:#{port}")
+      Docyard.logger.info("Use Ctrl+C to stop\n")
     end
 
-    def create_server
-      WEBrick::HTTPServer.new(
-        Port: port,
-        DocumentRoot: output_dir,
-        AccessLog: [],
-        Logger: WEBrick::Log.new(File::NULL),
-        MimeTypes: mime_types
-      )
-    end
+    def run_server
+      app = StaticFileApp.new(output_dir)
+      puma_config = build_puma_config(app)
+      log_writer = Puma::LogWriter.strings
 
-    def mime_types
-      WEBrick::HTTPUtils::DefaultMimeTypes.merge(
-        {
-          "css" => "text/css",
-          "js" => "application/javascript",
-          "json" => "application/json",
-          "svg" => "image/svg+xml",
-          "woff" => "font/woff",
-          "woff2" => "font/woff2"
-        }
-      )
+      @launcher = Puma::Launcher.new(puma_config, log_writer: log_writer)
+      @launcher.run
+    rescue Interrupt
+      Docyard.logger.info("\nShutting down preview server...")
     end
 
-    def shutdown_server(server)
-      puts "\nShutting down preview server..."
-      server.shutdown
+    def build_puma_config(app)
+      server_port = port
+
+      Puma::Configuration.new do |config|
+        config.bind "tcp://localhost:#{server_port}"
+        config.app app
+        config.workers 0
+        config.threads 1, 4
+        config.quiet
+      end
     end
   end
 end

data/lib/docyard/server/rack_application.rb

@@ -2,24 +2,26 @@
 
 require "json"
 require "rack"
+require_relative "../navigation/page_navigation_builder"
 require_relative "../navigation/sidebar_builder"
-require_relative "../navigation/prev_next_builder"
-require_relative "../navigation/breadcrumb_builder"
 require_relative "../config/branding_resolver"
-require_relative "../config/constants"
+require_relative "../constants"
 require_relative "../rendering/template_resolver"
 require_relative "../routing/fallback_resolver"
 require_relative "pagefind_handler"
 
 module Docyard
   class RackApplication
-    def initialize(docs_path:, file_watcher:, config: nil, pagefind_path: nil)
+    def initialize(docs_path:, config: nil, pagefind_path: nil, sse_port: nil, sidebar_cache: nil)
       @docs_path = docs_path
-      @file_watcher = file_watcher
       @config = config
+      @sse_port = sse_port
+      @dev_mode = !sse_port.nil?
+      @sidebar_cache = sidebar_cache
       @router = Router.new(docs_path: docs_path)
-      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config)
-      @asset_handler = AssetHandler.new
+      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config, dev_mode: @dev_mode,
+                               sse_port: sse_port)
+      @asset_handler = AssetHandler.new(public_dir: config&.public_dir || "docs/public")
       @pagefind_handler = PagefindHandler.new(pagefind_path: pagefind_path, config: config)
     end
 
@@ -29,21 +31,20 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler, :pagefind_handler
+    attr_reader :docs_path, :config, :router, :renderer, :asset_handler, :pagefind_handler, :dev_mode
 
     def handle_request(env)
       path = env["PATH_INFO"]
 
-      return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
-      return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
       return pagefind_handler.serve(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
+      return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
 
       public_response = asset_handler.serve_public_file(path)
       return public_response if public_response
 
       handle_documentation_request(path)
     rescue StandardError => e
-      handle_error(e)
+      handle_error(e, env)
     end
 
     def handle_documentation_request(path)
@@ -106,14 +107,20 @@ module Docyard
     end
 
     def build_navigation_html(template_resolver, current_path, markdown, header_ctas)
-      return { sidebar_html: "", prev_next_html: "", breadcrumbs: nil } unless template_resolver.show_sidebar?
+      navigation_builder.build(
+        current_path: current_path,
+        markdown: markdown,
+        header_ctas: header_ctas,
+        show_sidebar: template_resolver.show_sidebar?
+      )
+    end
 
-      sidebar_builder = build_sidebar_instance(current_path, header_ctas)
-      {
-        sidebar_html: sidebar_builder.to_html,
-        prev_next_html: build_prev_next(sidebar_builder, current_path, markdown),
-        breadcrumbs: build_breadcrumbs(sidebar_builder.tree, current_path)
-      }
+    def navigation_builder
+      @navigation_builder ||= Navigation::PageNavigationBuilder.new(
+        docs_path: docs_path,
+        config: config,
+        sidebar_cache: @sidebar_cache
+      )
     end
 
     def render_not_found_page
@@ -126,67 +133,28 @@ module Docyard
         docs_path: docs_path,
         current_path: current_path,
         config: config,
-        header_ctas: header_ctas
+        header_ctas: header_ctas,
+        sidebar_cache: @sidebar_cache
       )
     end
 
-    def build_prev_next(sidebar_builder, current_path, markdown)
-      PrevNextBuilder.new(
-        sidebar_tree: sidebar_builder.tree,
-        current_path: current_path,
-        frontmatter: markdown.frontmatter,
-        config: navigation_config
-      ).to_html
-    end
-
-    def build_breadcrumbs(sidebar_tree, current_path)
-      return nil unless breadcrumbs_enabled?
-
-      BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
-    end
-
-    def breadcrumbs_enabled?
-      config&.navigation&.breadcrumbs != false
-    end
-
-    def navigation_config
-      {}
-    end
-
     def branding_options
       BrandingResolver.new(config).resolve
     end
 
-    def handle_reload_check(env)
-      since = parse_since_timestamp(env)
-      reload_needed = file_watcher.changed_since?(since)
-
-      build_reload_response(reload_needed)
-    rescue StandardError => e
-      log_reload_error(e)
-      build_reload_response(false)
-    end
-
-    def parse_since_timestamp(env)
-      query = Rack::Utils.parse_query(env["QUERY_STRING"])
-      query["since"] ? Time.at(query["since"].to_f) : Time.now
-    end
-
-    def log_reload_error(error)
-      Docyard.logger.error "Reload check error: #{error.message}"
-      Docyard.logger.debug error.backtrace.join("\n")
-    end
-
-    def build_reload_response(reload_needed)
-      response_body = { reload: reload_needed, timestamp: Time.now.to_f }.to_json
-      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_JSON }, [response_body]]
-    end
-
-    def handle_error(error)
-      Docyard.logger.error "Request error: #{error.message}"
-      Docyard.logger.debug error.backtrace.join("\n")
+    def handle_error(error, env)
+      request_context = build_request_context(env)
+      Docyard.logger.error("Request error: #{error.message} [#{request_context}]")
+      Docyard.logger.debug(error.backtrace.join("\n"))
       [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
        [renderer.render_server_error(error)]]
     end
+
+    def build_request_context(env)
+      method = env["REQUEST_METHOD"]
+      path = env["PATH_INFO"]
+      user_agent = env["HTTP_USER_AGENT"]&.slice(0, 50)
+      user_agent ? "#{method} #{path} - #{user_agent}" : "#{method} #{path}"
+    end
   end
 end

data/lib/docyard/server/router.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils/path_utils"
+
 module Docyard
   class Router
     attr_reader :docs_path
@@ -11,11 +13,11 @@ module Docyard
     def resolve(request_path)
       clean_path = sanitize_path(request_path)
 
-      file_path = File.join(docs_path, "#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
-      return ResolutionResult.found(file_path) if File.file?(file_path)
+      file_path = safe_file_path("#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
+      return ResolutionResult.found(file_path) if file_path && File.file?(file_path)
 
-      index_path = File.join(docs_path, clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}")
-      return ResolutionResult.found(index_path) if File.file?(index_path)
+      index_path = safe_file_path(File.join(clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}"))
+      return ResolutionResult.found(index_path) if index_path && File.file?(index_path)
 
       ResolutionResult.not_found
     end
@@ -23,9 +25,11 @@ module Docyard
     private
 
     def sanitize_path(request_path)
-      clean = request_path.delete_prefix("/").delete_suffix("/")
-      clean = Constants::INDEX_FILE if clean.empty?
-      clean.delete_suffix(Constants::MARKDOWN_EXTENSION)
+      Utils::PathUtils.sanitize_url_path(request_path)
+    end
+
+    def safe_file_path(relative_path)
+      Utils::PathUtils.resolve_safe_path(relative_path, docs_path)
     end
   end
 end