Skip to content

Add advanced Context helpers guide#673

Merged
dahlia merged 1 commit intofedify-dev:mainfrom
dahlia:docs/context-advanced
Apr 10, 2026
Merged

Add advanced Context helpers guide#673
dahlia merged 1 commit intofedify-dev:mainfrom
dahlia:docs/context-advanced

Conversation

@dahlia
Copy link
Copy Markdown
Member

@dahlia dahlia commented Apr 10, 2026

Background

The manual already covers several advanced Context and RequestContext methods, but the material is spread across multiple pages: routeActivity() in the inbox guide, getSignedKeyOwner() in the access control guide, and remote-lookup helpers split across the WebFinger and NodeInfo pages. This makes the higher-level Context API harder to discover than it should be.

Changes

  • Add docs/manual/context-advanced.md, a dedicated guide that gathers all the advanced Context helpers in one place, with usage examples and a quick-reference table:
    • parseUri()
    • routeActivity() (including its security/trust semantics)
    • getSignedKey() and getSignedKeyOwner() (including the instance actor / mutual authorized fetch pattern)
    • getDocumentLoader() and authenticated document loading
    • getActorKeyPairs()
    • lookupObject(), lookupWebFinger(), lookupNodeInfo(), and traverseCollection()
    • RequestContext.request and RequestContext.url
  • Add a cross-link from docs/manual/context.md to the new guide.
  • Add the new page to the manual navigation in docs/.vitepress/config.mts.

Protocol-specific caveats (authorized fetch, WebFinger resolution, NodeInfo discovery, etc.) are kept in their existing pages; the new guide provides concise summaries and links back to those pages for deeper coverage.

Closes #670

The manual had no single place where readers could find all the
advanced Context methods.  parseUri(), routeActivity(),
getSignedKey()/getSignedKeyOwner(), getDocumentLoader(),
getActorKeyPairs(), lookupObject()/lookupWebFinger()/lookupNodeInfo(),
traverseCollection(), and RequestContext.request/url were scattered
across the inbox, access-control, webfinger, and nodeinfo pages.

This commit adds docs/manual/context-advanced.md, a dedicated guide
that gathers every advanced helper in one place with usage examples,
a quick-reference table, and links back to the protocol-specific pages
for deeper coverage.  The existing Context page now carries a pointer
to the new guide.

Closes fedify-dev#670

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Apr 10, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 468e02b3-94a5-48b3-a44b-d43b4eb07993

📥 Commits

Reviewing files that changed from the base of the PR and between 12c6288 and f48ba8f.

⛔ Files ignored due to path filters (1)
  • deno.lock is excluded by !**/*.lock
📒 Files selected for processing (4)
  • .zed/settings.json
  • docs/.vitepress/config.mts
  • docs/manual/context-advanced.md
  • docs/manual/context.md

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for advanced Context and RequestContext helpers through a new dedicated guide page. It updates the existing Context documentation to cross-link to the new guide, adds a navigation entry to the documentation site, and updates IDE configuration settings.

Changes

Cohort / File(s) Summary
Documentation
docs/manual/context-advanced.md, docs/manual/context.md, docs/.vitepress/config.mts
New advanced Context guide page documenting URI parsing, activity routing, signature verification, authenticated fetching, actor key introspection, remote object/WebFinger/NodeInfo lookups, and collection traversal. Updated main context page with cross-link. Added navigation entry.
Repository Configuration
.zed/settings.json
Added Markdown language configuration with external formatter (hongdown) and language server allow/deny list.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding a dedicated advanced Context helpers guide to consolidate scattered documentation.
Description check ✅ Passed The description is directly related to the changeset, providing background on the documentation gap and detailing all changes made: the new guide, cross-links, and navigation updates.
Linked Issues check ✅ Passed All coding requirements from issue #670 are met: the new context-advanced.md guide covers all specified helpers with examples and links, cross-links are added to context.md, navigation is updated in config.mts, and protocol-specific caveats remain on their original pages.
Out of Scope Changes check ✅ Passed All changes are directly aligned with issue #670 objectives. The new Markdown language configuration in .zed/settings.json appears unrelated to the documentation objectives but is a minor configuration addition that does not compromise the PR's primary scope.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new documentation page, "Advanced context helpers," which provides detailed guidance on URI parsing, manual activity routing, signature introspection, and authenticated fetching. It also updates the project's Markdown formatting configuration and refreshes numerous dependencies in the lockfile. Feedback was provided to improve a code example in the new documentation by using optional chaining to safely handle cases where an actor might not have any registered key pairs.

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 10, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dahlia dahlia merged commit 568b08c into fedify-dev:main Apr 10, 2026
16 of 17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/documentation Improvements or additions to documentation

Development

Successfully merging this pull request may close these issues.

Document advanced Context methods in one place

1 participant