Add server mode with live reload (rdoc --server)

[st0012]

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

• New RDoc::Server (lib/rdoc/server.rb) — minimal HTTP server using Ruby's built-in TCPServer (no WEBrick or external dependencies)
  • Thread-per-connection with Connection: close
  • Persistent Aliki generator instance rendering pages to strings
  • In-memory page cache and search index cache with full invalidation on changes
  • Live reload via inline JS polling /__status endpoint every 1 second
  • Background file watcher polling source file mtimes every 1 second
  • Incremental re-parse: only changed files are re-parsed, old data removed first
  • Detection of new and deleted source files
• --server[=PORT] CLI option (default port 4000) and rdoc:server Rake task
• RDoc::Store#remove_file — recursively removes a file's classes, modules, and C variable maps from the store
• Darkfish#refresh_store_data — extracted for reuse by the server after re-parsing
• RDoc::Servlet → RDoc::RI::Servlet — moved to clarify RI-specific usage

Security & robustness

• Binds to 127.0.0.1 only (localhost)
• Path traversal protection in asset serving (File.expand_path containment check)
• Proper HTTP error responses: 400, 404, 405, 500
• 5-second IO.select read timeout on client sockets
• Mutex protects all store mutations, generator refresh, and cache invalidation atomically
• Individual parse_file errors rescued so one failure doesn't block remaining files
• Watcher thread uses @running flag with clean shutdown via Thread#join

Known limitations

• Reopened classes and file deletion: if a class is defined across multiple files, deleting one file removes the entire class from the store. Saving the remaining file triggers a re-parse that restores it.
• Full cache invalidation: any file change clears all cached pages. Rendering is fast (~ms per page); parsing is the expensive part and is done incrementally.
• Template/CSS changes: require server restart (only source files are watched).

[matzbot]

🚀 Preview deployment available at: https://0b3fee17.rdoc-6cd.pages.dev (commit: d11c91c)

[tompng]

Just an idea, how about inserting last_change_time to this script?

There's a possibility to skip some change:

1. last_change_time updated to time1
2. Reload the page generated with time1
3. last_change_time updated again, value becomes time2
4. LIVE_RELOAD_SCRIPT loads initial lastChange value, get time2 but the content is generated in time1

[tompng]

I think what we need to do for removed files and changed files has overlap. File changed to empty file and file deletion seems essentially the same.

• Remove: Remove contributions and remove file from store
• Update: Remove contributions and re-parse the file

How about calling clear_file_contributions here without removing all classes and modules?
In clear_file_contributions, we can remove class or module if it is only defined in this file.

cm.in_files.delete(top_level)
if cm.in_files.empty?
  # Remove from store
  @store.send(:remove_classes_and_modules, [cm])
  # Remove from parent's classes_hash
  cm.parent.classes_hash.delete(cm.name) # or modules_hash.delete(cm.name)
 end

This way, the limitation for reopened classes and file deletion will be gone/improve.
File change that renames a class defined in it might also work as expected.