Add server mode with live reload (rdoc --server)#1620
Open
Conversation
Collaborator
|
🚀 Preview deployment available at: https://a0f78dbf.rdoc-6cd.pages.dev (commit: 4d2eea3) |
Adds a built-in HTTP server for previewing documentation while editing source files. Parses all sources on startup, watches for file changes, re-parses only changed files, and auto-refreshes the browser. Server implementation (lib/rdoc/server.rb): - Uses Ruby's built-in TCPServer (no WEBrick or external dependencies) - Persistent Aliki generator instance rendering to strings - Thread-per-connection with Connection: close (no keep-alive) - Background watcher thread polls file mtimes every 1 second - Live reload via inline JS polling /__status endpoint - New --server[=PORT] option (default 4000) and rdoc:server Rake task - Moved RDoc::Servlet to RDoc::RI::Servlet (server mode uses new class) Security: - Binds to 127.0.0.1 only (localhost) - Path traversal protection in asset serving via expand_path containment - Proper HTTP error responses (400, 404, 405, 500) - 5-second read timeout on client sockets Concurrency: - Mutex protects all store mutations, generator refresh, and cache invalidation as a single atomic operation - Thread-safe last_change_time reads for the status endpoint Correctness: - Clears file contributions (methods, constants, comments, etc.) before re-parsing to prevent duplication, without removing shared namespaces - Individual parse_file errors caught so one failure doesn't block others - Store#remove_file recursively cleans nested classes/modules and C vars - Watcher thread uses @running flag with clean shutdown via join
st0012
force-pushed
the
server-mode-retry
branch
from
5ab5492 to
a3bd278
Compare
kou
reviewed
Feb 22, 2026
Co-authored-by: Sutou Kouhei <kou@clear-code.com>
tompng
reviewed
Feb 22, 2026
tompng
reviewed
Feb 22, 2026
- Embed last_change_time into the live-reload script at render time so the browser's initial timestamp matches the page content. This fixes a race where a change between page generation and the first poll would be silently skipped. - Call clear_file_contributions for removed files (not just changed files) and remove classes/modules from the store when no files contribute to them anymore. This correctly handles reopened classes across multiple files and improves file deletion behavior.
Move `relative_path_for` from a private method on RDoc::Server to a public method on RDoc::RDoc, eliminating the duplication with the inline logic in `parse_file`. Move `clear_file_contributions` from RDoc::Server to RDoc::Store where it naturally belongs — it operates entirely on store internals (files_hash, classes_hash, modules_hash). Add tests for Store#clear_file_contributions covering single-file removal, multi-file preservation, per-file cleanup of methods/ constants/includes, and no-op for nonexistent files.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A better attempt of #1151
Implement
rdoc --server[=PORT]for previewing documentation with automatic browser refresh on source file changes. The server parses all sources on startup, serves pages from memory via the Aliki generator, and watches for file modifications, additions, and deletions — re-parsing only what changed.rdoc-server-live-reload-demo.mp4
Changes
RDoc::Server(lib/rdoc/server.rb) — minimal HTTP server using Ruby's built-inTCPServer(no WEBrick or external dependencies)Connection: close/__statusendpoint every 1 second--server[=PORT]CLI option (default port 4000) andrdoc:serverRake taskRDoc::Store#remove_file— removes a file's entries from the store hashesRDoc::Store#clear_file_contributions— surgically removes a file's methods, constants, comments, includes, extends, and aliases from its classes/modules, preserving classes that span multiple filesRDoc::RDoc#relative_path_for— extracted path normalization (againstoptions.rootandoptions.page_dir) shared byparse_fileand the serverDarkfish#refresh_store_data— extracted for reuse by the server after re-parsingRDoc::Servlet→RDoc::RI::Servlet— moved to clarify RI-specific usageSecurity & robustness
127.0.0.1only (localhost)File.expand_pathcontainment check)IO.selectread timeout on client socketsparse_fileerrors rescued so one failure doesn't block remaining files@runningflag with clean shutdown viaThread#joinKnown limitations