fedify lookup currently supports --traverse, which is designed for iterating collection items. That works well for collection-shaped resources, but it does not help when a user wants to walk object relationships, such as following a reply chain through replyTarget.
This issue proposes a new --recurse option for fedify lookup. The intent is to let users start from one object and recursively follow a selected property to fetch related objects step by step. In other words, --traverse remains collection-oriented, while --recurse is relationship-oriented.
Because these two modes represent different lookup semantics, --traverse and --recurse should be mutually exclusive, with a clear parse-time error when both are provided.
For option values, short names should follow Fedify property naming only. So replyTarget is accepted, while inReplyTo is not accepted as a short form. To preserve standards-level precision, fully qualified IRIs should also be accepted, e.g. https://www.w3.org/ns/activitystreams#inReplyTo.
Error handling should match existing CLI expectations. By default, a fetch error in the chain should fail the command. When --suppress-errors is set, lookup should continue in best-effort mode and return whatever could be resolved. The implementation also needs loop protection (visited tracking) and a depth cap (e.g. --recurse-depth) to prevent infinite or unbounded recursion.
Example invocations:
fedify lookup <url> --recurse=replyTargetfedify lookup <url> --recurse=https://www.w3.org/ns/activitystreams#inReplyTofedify lookup <url> --recurse=replyTarget --recurse-depth=10fedify lookup <url> --recurse=replyTarget --suppress-errors
Acceptance criteria
--recurse=replyTarget recursively follows the reply chain.--recurse=<IRI> for inReplyTo behaves equivalently.--recurse=inReplyTo (short form) is rejected with a helpful error.--traverse and --recurse cannot be used together.--suppress-errors works in recurse mode as best-effort behavior.- Cycles do not cause infinite loops.
- CLI/tests are added for parsing, recursion behavior, error behavior, and cycle/depth limits.
fedify lookupcurrently supports--traverse, which is designed for iterating collection items. That works well for collection-shaped resources, but it does not help when a user wants to walk object relationships, such as following a reply chain throughreplyTarget.This issue proposes a new
--recurseoption forfedify lookup. The intent is to let users start from one object and recursively follow a selected property to fetch related objects step by step. In other words,--traverseremains collection-oriented, while--recurseis relationship-oriented.Because these two modes represent different lookup semantics,
--traverseand--recurseshould be mutually exclusive, with a clear parse-time error when both are provided.For option values, short names should follow Fedify property naming only. So
replyTargetis accepted, whileinReplyTois not accepted as a short form. To preserve standards-level precision, fully qualified IRIs should also be accepted, e.g.https://www.w3.org/ns/activitystreams#inReplyTo.Error handling should match existing CLI expectations. By default, a fetch error in the chain should fail the command. When
--suppress-errorsis set, lookup should continue in best-effort mode and return whatever could be resolved. The implementation also needs loop protection (visitedtracking) and a depth cap (e.g.--recurse-depth) to prevent infinite or unbounded recursion.Example invocations:
fedify lookup <url> --recurse=replyTargetfedify lookup <url> --recurse=https://www.w3.org/ns/activitystreams#inReplyTofedify lookup <url> --recurse=replyTarget --recurse-depth=10fedify lookup <url> --recurse=replyTarget --suppress-errorsAcceptance criteria
--recurse=replyTargetrecursively follows the reply chain.--recurse=<IRI>forinReplyTobehaves equivalently.--recurse=inReplyTo(short form) is rejected with a helpful error.--traverseand--recursecannot be used together.--suppress-errorsworks in recurse mode as best-effort behavior.