Add relay manual #512
Add relay manual #512
Conversation
Summary of ChangesHello @sij411, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a comprehensive manual for Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive and well-structured manual for @fedify/relay. The documentation is excellent, covering everything from initial setup to advanced topics like security and monitoring. I've provided a couple of suggestions to improve formatting consistency and to make a code example safer and more robust. Overall, this is a great addition to the project's documentation.
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
dahlia
left a comment
dahlia
left a comment
There was a problem hiding this comment.
Thank you for writing this comprehensive documentation for @fedify/relay! The overall structure is well-organized and covers the essential topics.
However, I have a concern about the Managing followers section that I'd like to discuss.
Replace direct KvStore access with the new Relay interface methods: - Use relay.listFollowers() instead of kv.list() - Add documentation for relay.getFollower() - Update RelayFollower type to show actorId and validated Actor object - Remove isRelayFollower reference (now internal as isRelayFollowerData) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
dahlia
left a comment
dahlia
left a comment
There was a problem hiding this comment.
Thank you for this comprehensive documentation for @fedify/relay! The overall structure is excellent and covers the essential topics well.
However, I found a few issues that need to be addressed before merging:
Documentation build fails due to Twoslash errors
Running pnpm build in the docs/ directory fails with the following errors:
[2307] Cannot find module '@fedify/relay' or its corresponding type declarations.
[7006] Parameter 'ctx' implicitly has an 'any' type.
[7006] Parameter 'actor' implicitly has an 'any' type.
The @fedify/relay package isn't available in the docs build environment. You'll need to add the package to the docs dependencies. For the implicit any errors, you may need to add explicit type annotations in the code examples.
Markdown style guide issues
There are some places that don't follow the Markdown style guide described in AGENTS.md. Please review the guide and update the formatting accordingly.
Once these issues are resolved, the documentation looks great!
dahlia
left a comment
dahlia
left a comment
There was a problem hiding this comment.
There are some places that don't follow the Markdown style guide described in AGENTS.md. Please review the guide and update the formatting accordingly.
Tip
If you're using Claude Code, you can ask it to reformat docs/manual/relay.md according to the Markdown style guide in AGENTS.md—it should handle this well!
docs/manual/relay.md
Outdated
| Follower data is stored in the [`KvStore`](./kv.md) with keys following the | ||
| pattern `["follower", actorId]`. Each entry contains: | ||
|
|
||
| - `actor`: The actor's JSON-LD data | ||
| - `state`: Either `"pending"` or `"accepted"` | ||
|
|
||
| ### Querying followers | ||
|
|
||
| ~~~~ typescript twoslash | ||
| import type { KvStore } from "@fedify/fedify"; | ||
| const kv = null as unknown as KvStore; | ||
| // ---cut-before--- | ||
| import type { RelayFollower } from "@fedify/relay"; | ||
|
|
||
| for await (const entry of kv.list<RelayFollower>(["follower"])) { | ||
| console.log(`Follower: ${entry.value.actor["@id"]}`); | ||
| console.log(`State: ${entry.value.state}`); | ||
| } | ||
| ~~~~ | ||
|
|
||
| > [!NOTE] | ||
| > The `~KvStore.list()` method requires a `KvStore` implementation that | ||
| > supports listing by prefix (Redis, PostgreSQL, SQLite, Deno KV all support | ||
| > this). | ||
| ### Validating follower objects | ||
|
|
||
| ~~~~ typescript twoslash | ||
| import type { KvStore } from "@fedify/fedify"; | ||
| const kv = null as unknown as KvStore; | ||
| // ---cut-before--- | ||
| import { isRelayFollower } from "@fedify/relay"; | ||
|
|
||
| for await (const entry of kv.list(["follower"])) { | ||
| if (isRelayFollower(entry.value)) { | ||
| console.log(`Valid follower in state: ${entry.value.state}`); | ||
| } | ||
| } | ||
| ~~~~ | ||
|
|
There was a problem hiding this comment.
The Querying followers and Validating follower objects subsections were removed in this commit, but I believe these examples are valuable for users who need to work with follower data directly through KvStore.
Could you please restore these examples? They demonstrate important use cases:
- How to iterate over followers using
kv.list<RelayFollower>(["follower"]) - How to validate follower objects using
isRelayFollower()type guard
If there were Twoslash type errors with these examples, we can work together to fix them rather than removing the examples entirely.
There was a problem hiding this comment.
Unfortunately, that was the result of asking CC to use AGENTS.md to follow markdown styles. Welp, it seems that didn't work very well though.
The problem could be solved with adding isRelayFollower. However, whendo people use directly querying follower over public APIs?
There was a problem hiding this comment.
Actually, I take that back. Since there's already a Listing all followers subsection using relay.listFollowers(), the Querying followers subsection would be redundant. And isRelayFollower() isn't exported anyway, so removing both subsections was the right call. Sorry for the confusion!
- Fix markdown style to follow the style guide: - Fix title underline length to match "Relay" - Align all tables properly - Remove trailing spaces - Wrap long lines at 80 characters - Use italics for package names instead of backticks - Use en dash for "Key–value" - Add Bun and Node.js server examples alongside Deno - Add pnpm and Yarn installation commands - Add "Subscribing to a relay" section explaining: - Different subscription URLs for Mastodon-style vs LitePub-style relays - How to subscribe from Mastodon - How to subscribe from Pleroma/Akkoma - Add FEP-ae0c reference for protocol specifications
2 participants
Summary
Added a manual for
@fedify/relay. Related to #359Notes
Could you check if this documentation contains all information for building relay servers? I'm open to take opinions or recommendations.