fix(runtime): polish relaunch smoke behavior and health checks

Intent: end the relaunch history with the small but important fixes that make operations and regression diagnosis trustworthy.

Goals: keep container health checks configurable, make smoke cleanup failure-safe, and lock the final feed and health behavior into request specs.

Changes: tighten the Docker healthcheck setup, harden the smoke task cleanup path, and add regression coverage for the late feed and health fixes.

Author: gildesmarais

Dockerfile

@@ -1,5 +1,16 @@
-# Stage 1: Build
-FROM ruby:4.0.1-alpine3.23 AS builder
+ARG RUBY_BASE_IMAGE=ruby:4.0.1-alpine3.23
+
+# Stage 1: Frontend Build
+FROM node:22-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+# Stage 2: Ruby Build
+FROM ${RUBY_BASE_IMAGE} AS builder
 
 LABEL maintainer="Gil Desmarais <html2rss-web-docker@desmarais.de>"
 
@@ -22,21 +33,22 @@ RUN apk add --no-cache \
   && bundle install --retry=5 --jobs=$(nproc) \
   && bundle binstubs bundler html2rss
 
-# Stage 2: Runtime
-FROM ruby:4.0.1-alpine3.23
+# Stage 3: Runtime
+FROM ${RUBY_BASE_IMAGE}
 
 LABEL maintainer="Gil Desmarais <html2rss-web-docker@desmarais.de>"
 
 SHELL ["/bin/ash", "-o", "pipefail", "-c"]
 
-ENV PORT=3000 \
-    RACK_ENV=production \
-    RUBY_YJIT_ENABLE=1
+ENV PORT=4000 \
+  RACK_ENV=production \
+  RUBY_YJIT_ENABLE=1
 
 EXPOSE $PORT
 
 HEALTHCHECK --interval=30m --timeout=60s --start-period=5s \
-  CMD curl -f http://${HEALTH_CHECK_USERNAME}:${HEALTH_CHECK_PASSWORD}@localhost:${PORT}/health_check.txt || exit 1
+  CMD TOKEN="${HEALTH_CHECK_TOKEN:-CHANGE_ME_HEALTH_CHECK_TOKEN}" && \
+    curl -f -H "Authorization: Bearer ${TOKEN}" http://localhost:${PORT}/api/v1/health || exit 1
 
 ARG USER=html2rss
 ARG UID=991
@@ -67,5 +79,6 @@ USER html2rss
 
 COPY --from=builder /usr/local/bundle /usr/local/bundle
 COPY --chown=$USER:$USER . /app
+COPY --from=frontend-builder --chown=$USER:$USER /app/public/frontend ./public/frontend
 
 CMD ["bundle", "exec", "puma", "-C", "./config/puma.rb"]

Rakefile

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'fileutils'
+require 'open3'
 
 ##
 # Helper methods used during :test run
@@ -27,21 +29,32 @@ module Output
   end
 end
 
+def test_container_exists?(container_name)
+  inspection, status = Open3.capture2e('docker', 'inspect', container_name)
+  return false unless status.success?
+  return false if inspection.strip.empty?
+
+  JSON.parse(inspection).any?
+rescue JSON::ParserError
+  false
+end
+
 task default: %w[test]
 
 desc 'Build and run docker image/container, and send requests to it'
 
 task :test do
   current_dir = ENV.fetch('GITHUB_WORKSPACE', __dir__)
+  smoke_auto_source_enabled = ENV.fetch('SMOKE_AUTO_SOURCE_ENABLED', 'false')
 
   Output.describe 'Building and running'
   sh 'docker build -t gilcreator/html2rss-web -f Dockerfile .'
   sh ['docker run',
       '-d',
-      '-p 3000:3000',
+      '-p 4000:4000',
       '--env PUMA_LOG_CONFIG=1',
-      '--env HEALTH_CHECK_USERNAME=username',
-      '--env HEALTH_CHECK_PASSWORD=password',
+      '--env HEALTH_CHECK_TOKEN=CHANGE_ME_HEALTH_CHECK_TOKEN',
+      "--env AUTO_SOURCE_ENABLED=#{smoke_auto_source_enabled}",
       "--mount type=bind,source=#{current_dir}/config,target=/app/config",
       '--name html2rss-web-test',
       'gilcreator/html2rss-web'].join(' ')
@@ -51,22 +64,17 @@ task :test do
   Output.describe 'Listing docker containers matching html2rss-web-test filter'
   sh 'docker ps -a --filter name=html2rss-web-test'
 
-  Output.describe 'Generating feed from a html2rss-configs config'
-  sh 'curl -f "http://127.0.0.1:3000/github.com/releases.rss?username=html2rss&repository=html2rss-web" || exit 1'
-
-  Output.describe 'Generating example feed from feeds.yml'
-  sh 'curl -f http://127.0.0.1:3000/example.rss || exit 1'
-
-  Output.describe 'Authenticated request to GET /health_check.txt'
-  sh 'docker exec html2rss-web-test curl -f http://username:password@127.0.0.1:3000/health_check.txt || exit 1'
-
-  # skipped as html2rss is used in development version
-  # Output.describe 'Print output of `html2rss help`'
-  # sh 'docker exec html2rss-web-test html2rss help'
+  Output.describe 'Running RSpec smoke suite against container'
+  smoke_env = {
+    'SMOKE_BASE_URL' => 'http://127.0.0.1:4000',
+    'SMOKE_HEALTH_TOKEN' => 'CHANGE_ME_HEALTH_CHECK_TOKEN',
+    'SMOKE_API_TOKEN' => 'CHANGE_ME_ADMIN_TOKEN',
+    'SMOKE_AUTO_SOURCE_ENABLED' => smoke_auto_source_enabled,
+    'RUN_DOCKER_SPECS' => 'true'
+  }
+  sh smoke_env, 'bundle exec rspec --tag docker'
 ensure
-  test_container_exists = JSON.parse(`docker inspect html2rss-web-test`).any?
-
-  if test_container_exists
+  if test_container_exists?('html2rss-web-test')
     Output.describe 'Cleaning up test container'
 
     sh 'docker logs --tail all html2rss-web-test'
@@ -76,3 +84,78 @@ ensure
 
   exit 1 if $ERROR_INFO
 end
+
+namespace :openapi do
+  desc 'Generate OpenAPI YAML from request specs'
+  task :generate do
+    FileUtils.mkdir_p('docs/api/v1')
+    FileUtils.rm_f('docs/api/v1/openapi.yaml')
+    sh({ 'OPENAPI' => '1' }, 'bundle exec rspec spec/html2rss/web/api/v1_spec.rb --order defined')
+  end
+
+  desc 'Verify generated OpenAPI YAML is up to date'
+  task verify: :generate do
+    sh 'git diff --exit-code -- docs/api/v1/openapi.yaml'
+  end
+end
+
+namespace :yard do
+  desc 'Fail when public methods in app/ are missing essential YARD docs'
+  task :verify_public_docs do
+    require 'yard'
+
+    files = Dir.glob(File.join(__dir__, 'app/**/*.rb'))
+    YARD::Registry.clear
+    YARD::Registry.load(files, true)
+
+    violations = []
+
+    YARD::Registry.all(:method).each do |method_object|
+      next unless method_object.visibility == :public
+      next unless method_object.file&.include?('/app/')
+
+      location = "#{method_object.path} (#{method_object.file}:#{method_object.line})"
+      normalize_param_name = lambda do |name|
+        name.to_s.sub(/\A[*&]/, '').sub(/:$/, '')
+      end
+
+      param_tags = method_object.tags(:param)
+      params = method_object.parameters.map(&:first).map { |name| normalize_param_name.call(name) }
+      params.reject! { |name| name == 'block' }
+
+      param_tag_names = param_tags.map { |tag| normalize_param_name.call(tag.name) }
+      missing_params = params - param_tag_names
+      violations << "#{location} missing @param for: #{missing_params.join(', ')}" unless missing_params.empty?
+
+      param_tags.each do |tag|
+        violations << "#{location} @param #{tag.name} missing type" if tag.types.nil? || tag.types.empty?
+      end
+
+      return_tag = method_object.tag(:return)
+      if return_tag.nil?
+        violations << "#{location} missing @return"
+      elsif return_tag.types.nil? || return_tag.types.empty?
+        violations << "#{location} @return missing type"
+      end
+    end
+
+    if violations.any?
+      puts 'YARD public method documentation check failed:'
+      violations.sort.each { |violation| puts "  - #{violation}" }
+      abort "\nFound #{violations.count} YARD documentation violation(s)."
+    end
+
+    puts 'YARD public method documentation check passed.'
+  end
+end
+
+namespace :zeitwerk do
+  desc 'Fail when Zeitwerk cannot eager load the app tree cleanly'
+  task :verify do
+    ENV['RACK_ENV'] ||= 'test'
+    require_relative 'app'
+
+    Html2rss::Web::Boot.eager_load!
+    puts 'Zeitwerk eager load check passed.'
+  end
+end