Skip to content

v2.md

Latest commit

 

History

History
242 lines (156 loc) · 6.58 KB

v2.md

File metadata and controls

242 lines (156 loc) · 6.58 KB

html2rss-web v2 Migration Guide (master -> feat/revamp-frontend)

This is a full migration guide for the v2 rewrite compared to master. The branch is a large architecture change, not an incremental patch.

Scope and Impact

Compared to master, v2 includes:

  • Full backend API restructuring under app/api/v1/* and app/routes/*
  • New Astro frontend app under frontend/ (components, hooks, tests, docs)
  • Security/auth/token/error handling rework
  • Dev container standardization and expanded Make workflows
  • CI/CD workflow overhaul and smoke-test improvements

Change size from master:

  • ~134 files changed
  • ~16k+ lines added, ~3.6k lines removed

Treat this migration as a major version upgrade.

Audience-Specific Summary

Operators / Deployment

You must review:

  • Port and probe behavior
  • Required environment variables and feature flags
  • Docker/CI smoke behavior
  • Security defaults and startup validation

API Integrators

You must review:

  • Health route and auth expectations
  • Feed endpoint auth/forbidden semantics
  • Error payload behavior for unexpected failures

Contributors

You must review:

  • New devcontainer-first workflow
  • New backend/frontend test split
  • New repository layout and module boundaries

Breaking / Behavior Changes

1) Runtime Port and Container Defaults

  • v2 standardizes app runtime on 4000 by default.
  • If your infra assumed 3000, update ingress/proxy or set PORT explicitly.

Affected surfaces:

  • config/puma.rb
  • Dockerfile
  • local smoke defaults in Rakefile and spec/smoke/docker_spec.rb
  • docs/OpenAPI examples

2) Health Endpoint Model Changed

v2 health routes:

  • GET /api/v1/health (authenticated)
  • GET /api/v1/health/ready (unauthenticated readiness)
  • GET /api/v1/health/live (unauthenticated liveness)

If your orchestrator cannot set auth headers, use ready/live probes.

3) Error Payload Hardening

  • Unexpected internal failures now return a generic client message.
  • Internal details are not exposed in API responses.

Client impact:

  • Depend on error.code, not raw exception text.

4) Feed Endpoint Auth and Policy Semantics

Semantics are now explicit and consistent:

  • 401 UNAUTHORIZED for missing/invalid credentials
  • 403 FORBIDDEN only for authenticated policy violations
    • example: auto source disabled
    • example: URL not allowed for account

5) Auto Source Feature Flag Semantics

Policy is environment-sensitive:

  • Development: enabled unless AUTO_SOURCE_ENABLED=false
  • Non-development: enabled only when AUTO_SOURCE_ENABLED=true

CI/smoke behavior:

  • SMOKE_AUTO_SOURCE_ENABLED must be set to match intended runtime mode.

6) Legacy Server-Rendered UI/Helpers Removed

Removed legacy ERB/helpers/routes stack in favor of API + Astro frontend:

  • removed views/* legacy pages
  • removed old helpers/* and legacy routes/auto_source.rb
  • frontend assets now built from frontend/

If you customized old server-rendered pages, port those customizations into Astro.

Architecture Changes

Backend

New module boundaries:

  • API contract and handlers: app/api/v1/*
  • Route composition: app/routes/api_v1.rb, app/routes/static.rb
  • Error policy: app/error_responder.rb
  • Env/feature policy: app/environment_validator.rb
  • TTL policy: app/cache_ttl.rb
  • Feed command split: app/api/v1/feeds/create_feed.rb, show_feed.rb

Security/auth stack:

  • token/account management via app/auth.rb, app/feed_token.rb, app/account_manager.rb
  • URL allow-list validation in app/url_validator.rb
  • structured security logging in app/security_logger.rb

Frontend

New Astro app and docs site under frontend/:

  • UI: frontend/src/components/*
  • hooks: frontend/src/hooks/*
  • docs content: frontend/src/content/docs/*
  • tests: Vitest unit + contract suites

Tooling and Workflow Changes

Development Workflow

Dev container is now first-class:

  • .devcontainer/* added/updated
  • Make targets expanded (make setup, make dev, make test, make ready, etc.)

CI/CD

  • Legacy workflow replaced by .github/workflows/ci.yml
  • Distinct Ruby and frontend jobs
  • Docker smoke coverage now runs in matrix mode for auto-source enabled/disabled

Configuration and Environment

Required/Important Variables

  • HTML2RSS_SECRET_KEY (required in production)
  • PORT (defaults to 4000 in v2)
  • AUTO_SOURCE_ENABLED (intentional per-environment behavior)
  • HEALTH_CHECK_TOKEN for authenticated health checks

Production Validation

v2 startup performs stronger production checks:

  • secret key presence/strength checks
  • account token strength validation

Invalid production config now fails fast at boot.

API Contract and Docs

Primary API doc:

  • docs/api/v1/openapi.yaml

v2 adds contract-focused specs and smoke tests, but because this rewrite is broad, re-check any custom client assumptions against actual runtime behavior before rollout.

Testing Model Changes

v2 test layers:

  • Ruby API request/integration specs
  • Frontend unit/contract tests
  • Docker smoke tests (now mode-aware with SMOKE_AUTO_SOURCE_ENABLED)

Pre-commit gate:

  • make ready (RuboCop + Ruby RSpec)

Migration Plan (Recommended)

  1. Inventory integrations

    • health probes
    • API clients
    • proxy/routing assumptions

  2. Prepare environment

    • set HTML2RSS_SECRET_KEY
    • set AUTO_SOURCE_ENABLED intentionally
    • verify PORT assumptions

  3. Update probe config

    • move readiness/liveness to /api/v1/health/ready and /api/v1/health/live
    • keep /api/v1/health for authenticated deep checks

  4. Update client error handling

    • key off error.code
    • avoid depending on internal exception strings

  5. Run smoke in both feature modes

    • SMOKE_AUTO_SOURCE_ENABLED=false
    • SMOKE_AUTO_SOURCE_ENABLED=true

  6. Canary rollout

    • monitor auth failures, forbidden rates, feed creation success
    • verify probe behavior and cache headers

Rollback Boundary

Because v2 is a broad rewrite, rollback should be version-level (image/tag rollback), not partial cherry-picks.

Keep previous deployment artifacts available until:

  • probes are stable
  • feed creation/retrieval metrics are healthy
  • no client-contract regressions are observed

Post-Migration Verification Checklist

  • App reachable on expected port (4000 unless overridden)
  • Readiness/liveness probes green
  • Authenticated health endpoint works with token
  • Feed creation success path works when auto source enabled
  • Correct forbidden behavior when auto source disabled
  • API clients handle error.code contract correctly
  • Frontend build and API integration flows verified