Skip to content

Document advanced Context methods in one place #670

@dahlia

Description

@dahlia

The manual already covers several advanced Context and RequestContext methods, but the material is spread across multiple pages. docs/manual/context.md introduces the type and some core helpers, while routeActivity() is documented in docs/manual/inbox.md, signed-request helpers such as getSignedKeyOwner() appear in docs/manual/access-control.md, and remote lookup methods are split across docs/manual/webfinger.md and docs/manual/nodeinfo.md.

That makes the higher-level Context API harder to discover than it should be. If a reader wants to understand what Context can do beyond URI building and basic dispatch, they currently need to jump across several sections of the manual.

I think we should add a dedicated guide for advanced Context usage, tentatively in docs/manual/context-advanced.md, and link to it prominently from docs/manual/context.md. The goal would not be to duplicate every existing section, but to gather the advanced methods in one place, explain when to use them, and link back to the more detailed protocol-specific pages where needed.

Proposed scope:

  • parseUri()
  • routeActivity()
  • getSignedKey() and getSignedKeyOwner()
  • getDocumentLoader() and authenticated document loading patterns
  • getActorKeyPairs()
  • remote lookup helpers such as lookupObject(), lookupWebFinger(), lookupNodeInfo(), and traverseCollection()
  • RequestContext.request and RequestContext.url, if we want the page to serve as a complete guide to request-aware context helpers

Expected outcome:

  • add a dedicated advanced Context guide in docs/manual/
  • add clear cross-links from docs/manual/context.md
  • reduce the need to discover these methods indirectly through unrelated pages
  • keep protocol-specific caveats in their existing pages, but add concise summaries and links from the new guide
  • include examples that explain when to use each helper, not just what it returns

A few topics need especially careful treatment:

  • security and trust semantics of routeActivity()
  • authorized fetch and instance-actor patterns around getSignedKey() and getSignedKeyOwner()
  • when to use lookupObject() directly versus lookupWebFinger()
  • when getDocumentLoader() is necessary instead of the default loader

Metadata

Metadata

Assignees

Type

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions