Skip to content

Create a structured recursive lookup failure model #901

Description

@dahlia

Why

Recursive fedify lookup is useful for debugging replies and quotes, but the current error handling in packages/cli/src/lookup.ts is spread across TimeoutError, RecursiveLookupError, private-address hints, authorized-fetch hints, and --suppress-errors branches. The behavior works, but each new edge case adds another message branch.

A structured internal failure model would make the command easier to test and easier to extend without changing user-facing behavior by accident.

Current code

The recursive path uses collectRecursiveObjects() and then prints errors in runLookup(). There are already tests in packages/cli/src/lookup.test.ts for recursion depth, private-address handling, reverse output, and partial failures.

Scope

Introduce a small internal representation for recursive lookup failures. It should capture at least:

  • the target URL that failed, when known;
  • whether the failure came from timeout, private-address blocking, not found, JSON-LD context loading, or another fetch/parse error;
  • whether --suppress-errors can safely turn the failure into a partial result;
  • the hint that should be printed, if any.

Use that model to simplify the recursive error branch in runLookup() while keeping the CLI output stable unless a message is clearly wrong today.

Non-goals

Do not change the lookupObject() API. Do not change the meaning of --allow-private-address, --authorized-fetch, --suppress-errors, or --reverse.

Suggested checks

Add unit tests for the new classifier and keep the existing end-to-end runLookup tests passing. Include at least one test where a private context URL fails during recursion, because that path currently has special messaging.

Metadata

Metadata

Assignees

No one assigned

    Fields

    Priority

    Low

    Effort

    High

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions