Skip to content

codedb_remote: add local fallback when api.wiki.codes is unreachable #534

@idea404

Description

@idea404

Problem

codedb_remote depends on api.wiki.codes, which is frequently unreachable (Cloudflare 530 errors, rate limiting, timeouts). This makes the remote tool unreliable in practice, while the local tools (tree, outline, search, symbol, etc.) work great.

Suggested approach

Add a fallback chain when api.wiki.codes fails:

  1. Try remote first (current behavior)
  2. Check local cache: ~/.codedb/remote-cache/<repo-hash>/
    • If exists and fresh (TTL), use the cached local index
    • If missing or stale, git clone --depth=1 + codedb index
  3. Query local index with the same action/params

Cache management

  • TTL: auto-delete repos not accessed in ~7-30 days
  • LRU: cap at N repos or max disk size (e.g. 2GB)
  • Cleanup: run lazily on query or as a background task
  • Manual: codedb remote --clean-cache

Benefits

  • Self-healing when the upstream is down
  • Fast after first clone (cached locally)
  • Shallow clones keep disk usage reasonable
  • Works offline after initial clone

Trade-offs

  • First query is slow (clone + index, 10-60s for large repos)
  • Auth needed for private repos (GitHub token)

This would make codedb_remote genuinely robust instead of a single point of failure.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions