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.
| ### 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 Managing followers section exposes internal implementation details (key patterns like ["follower", actorId] and the raw RelayFollower data structure). This approach has a few concerns:
- Encapsulation: Exposing the internal key schema makes it part of the public API contract
- Maintenance burden: Changing the storage structure later would become a breaking change
- Incomplete API: Direct
KvStoreaccess isn't a proper API—it lacks type safety and discoverability
I think we have two options:
-
Option A: Remove this section from the documentation for now, and add it back once we have proper APIs like
relay.listFollowers(),relay.getFollower(actorId), etc. -
Option B: Add these methods to
BaseRelayfirst, then document the proper API instead of rawKvStoreaccess.
What do you think?
There was a problem hiding this comment.
Option B sounds good, I will be working on that with another PR. (relay.listFollowers() and relay.getFollower(actorId)) How's that sound?
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.