fix: fall back to DB-cached CID when IPNS delegated routing fails

[FSM1]

Summary

• When delegated-ipfs.dev returns 502 or is unreachable, resolveRecord now falls back to the latest_cid stored in the folder_ipns table instead of surfacing the error to the user
• Extracted delegated routing logic into private resolveFromDelegatedRouting() method, with the public resolveRecord() wrapping it with DB fallback on BAD_GATEWAY
• No schema migration needed — latest_cid column already exists and is updated on every publish

Test plan

• 5 new unit tests covering: DB fallback on HTTP error, fallback after network retries, re-throw when no cache, re-throw when cache has null CID, non-BAD_GATEWAY passthrough
• All 44 IPNS service tests pass
• All 251 API unit tests pass
• Full E2E suite (23 tests) passes in headless and headed mode

🤖 Generated with Claude Code

Summary by CodeRabbit

• Tests

  • Added comprehensive test coverage for IPNS resolution fallback behavior, error handling scenarios, and retry logic.

• Bug Fixes

  • Improved IPNS resolution reliability with automatic fallback to cached data when primary resolution fails.
  • Enhanced error handling for network errors and rate-limiting with exponential backoff retry behavior.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (3)

• .learnings/2026-02-07-ipns-resolve-db-fallback.md is excluded by !.learnings/**
• .learnings/2026-02-07-parallel-bugfix-agents.md is excluded by !.learnings/**
• tools/mock-ipns-routing/package-lock.json is excluded by !**/package-lock.json

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

Walkthrough

Introduces a fallback mechanism to IpnsService.resolveRecord that attempts delegated routing first, then falls back to database-cached values when delegated routing returns a BAD_GATEWAY error. Adds comprehensive test coverage for fallback behavior, error handling, retry logic, and sequence number extraction.

Changes

Cohort / File(s)	Summary
IPNS Resolution Implementation apps/api/src/ipns/ipns.service.ts	Added private helper method resolveFromDelegatedRouting() to handle delegated routing lookups with retry and error handling. Updated resolveRecord() to attempt delegated routing first, then fall back to DB cache on BAD_GATEWAY errors. Includes logging for fallback usage and cache operations.
IPNS Service Tests apps/api/src/ipns/ipns.service.spec.ts	Added comprehensive test suite covering: fallback behavior on delegated routing failures, DB cache retrieval with/without cached data, 429 rate-limiting with Retry-After header handling, exponential backoff behavior, CID parsing (Qm-prefixed and bafk-prefixed formats), sequence number extraction, error re-throwing for non-BAD_GATEWAY errors, and timestamp updates during record publishing.

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant IpnsService
    participant DelegatedRouting as Delegated Routing API
    participant IpnsParser
    participant Database

    Client->>IpnsService: resolveRecord(ipnsName)
    
    IpnsService->>DelegatedRouting: resolveFromDelegatedRouting(ipnsName)
    
    alt Delegated Routing Success
        DelegatedRouting-->>IpnsService: IPNS Record
        IpnsService->>IpnsParser: parseIpnsRecord()
        IpnsParser-->>IpnsService: {CID, sequence}
        IpnsService-->>Client: {CID, sequence}
    else BAD_GATEWAY Error
        DelegatedRouting-->>IpnsService: BAD_GATEWAY (502)
        IpnsService->>Database: Lookup cached CID & sequence
        
        alt Cache Hit
            Database-->>IpnsService: {cachedCID, cachedSequence}
            IpnsService-->>Client: {cachedCID, cachedSequence}
        else Cache Miss
            Database-->>IpnsService: null
            IpnsService-->>Client: Error (re-throw BAD_GATEWAY)
        end
    else Other HTTP/Network Error
        DelegatedRouting-->>IpnsService: Error
        IpnsService-->>Client: Error (re-throw)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.99%. Comparing base (5842b83) to head (a6564d3).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #60      +/-   ##
==========================================
+ Coverage   88.88%   88.99%   +0.10%     
==========================================
  Files          34       34              
  Lines        1071     1081      +10     
  Branches      203      205       +2     
==========================================
+ Hits          952      962      +10     
  Misses         72       72              
  Partials       47       47              

Flag	Coverage Δ
api	88.99% <100.00%> (+0.10%)	⬆️
crypto	88.99% <100.00%> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
apps/api/src/ipns/ipns.service.ts	99.19% <100.00%> (+0.07%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.