Add relay follower query API and refactor types #514

sij411 · 2025-12-31T11:16:51Z

Summary

Adds public API methods to query relay followers and refactors the type system for better type safety and maintainability.

Related to: #512 (comment)

Changes

New Public API Methods

listFollowers(): AsyncIterableIterator<RelayFollower> - Lists all followers of the relay
getFollower(actorId: string): Promise<RelayFollower | null> - Gets a specific follower by actor ID

Type System Refactor

Two-type design for clarity:

RelayFollowerData (internal): Storage format with JSON-LD actor data (actor: unknown)
RelayFollower (public): API format with validated Actor instances (actor: Actor, includes actorId)

Why separate types?

KV stores require JSON-serializable data (can't store class instances)
Deserialization happens at read time
Public API provides typed Actor objects for better DX

Implementation Details

Added parseFollowerData() helper to centralize validation and deserialization
Both API methods use the same validation logic (no duplication)
Enhanced tests to verify typed Actor properties

Benefits

Users can query relay followers without accessing KV store directly
Type-safe Actor instances in public API
Clear separation between storage and API layers
No code duplication in validation logic

Separate internal storage format from public API types and add helper method to eliminate code duplication in follower data handling. - Add RelayFollowerData for internal KV storage (JSON-LD format) - Rename RelayFollowerEntry to RelayFollower as the main public type - Add parseFollowerData() helper to centralize validation and deserialization - Update isRelayFollower to isRelayFollowerData for storage validation - Keep RelayFollowerData internal (not exported from mod.ts) - Update tests to use new type naming This improves type safety by clearly distinguishing between the storage format (actor: unknown) and the public API format (actor: Actor), while reducing duplication across listFollowers() and getFollower() methods. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

gemini-code-assist · 2025-12-31T11:17:14Z

Summary of Changes

Hello @sij411, I'm Gemini Code Assist¹! 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 significantly enhances the relay package by exposing new public API methods that allow users to query relay followers without needing to interact directly with the underlying key-value store. Concurrently, it refactors the internal type system to clearly distinguish between stored data and public-facing, validated objects, leading to a more robust and type-safe codebase. This separation improves developer experience by providing fully typed Actor objects in the public API, while ensuring efficient and reliable data handling internally.

Highlights

New Public API for Relay Followers: Introduced listFollowers() to iterate over all relay followers and getFollower(actorId: string) to retrieve a specific follower by ID, providing direct access to follower information without exposing internal storage.
Refactored Type System for Clarity and Safety: Implemented a two-type design: RelayFollowerData for internal storage (holding raw JSON-LD actor data) and RelayFollower for the public API (providing validated Actor instances), significantly enhancing type safety and maintainability.
Centralized Data Validation and Deserialization: A new private helper method, parseFollowerData(), was added to centralize the logic for deserializing JSON-LD actor data and validating it, ensuring consistent and robust data handling across the new API methods.

🧠 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 Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a valuable public API for querying relay followers and significantly improves the type system for better safety and maintainability. The separation of internal storage types (RelayFollowerData) from public API types (RelayFollower) is a well-executed pattern that enhances the developer experience. The new listFollowers and getFollower methods are cleanly implemented, leveraging a shared helper function to avoid code duplication, and are backed by comprehensive tests. I have one suggestion to make the documentation example more robust. Overall, this is an excellent and well-thought-out contribution.

packages/relay/README.md

packages/relay/src/mod.ts

packages/relay/src/base.ts

Update JSDoc examples in listFollowers() and getFollower() to show complete working examples including relay creation with createRelay(). Previously the examples referenced 'relay' without showing how to create it, making them incomplete and potentially confusing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

codecov · 2025-12-31T11:45:38Z

Codecov Report

❌ Patch coverage is 91.42857% with 3 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/relay/src/base.ts	93.33%	1 Missing and 1 partial ⚠️
packages/relay/src/builder.ts	50.00%	1 Missing ⚠️

Files with missing lines	Coverage Δ
packages/relay/src/factory.ts	`100.00% <ø> (ø)`
packages/relay/src/litepub.ts	`85.24% <100.00%> (ø)`
packages/relay/src/mod.ts	`100.00% <ø> (ø)`
packages/relay/src/types.ts	`100.00% <100.00%> (+10.00%)`	⬆️
packages/relay/src/builder.ts	`81.17% <50.00%> (ø)`
packages/relay/src/base.ts	`96.00% <93.33%> (-4.00%)`	⬇️

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- Add public Relay interface with fetch(), listFollowers(), getFollower() - Update BaseRelay to implement Relay interface (marked @internal) - Change createRelay() return type from BaseRelay to Relay - Remove MastodonRelay and LitePubRelay exports from mod.ts - Update README to document interface-based API 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

dahlia

Is there any more work to add to this pull request? If not, can we take it out of draft?

sij411 and others added 2 commits December 31, 2025 02:55

Add getRelayFollowers and listRelayFollwers api

defc140

issues-auto-labeler bot added breaking change Breaking change component/federation Federation object related component/relay Relay related (@fedify/relay) difficulty/intermediate Intermediate level labels Dec 31, 2025

gemini-code-assist bot reviewed Dec 31, 2025

View reviewed changes

packages/relay/README.md Show resolved Hide resolved

dahlia requested changes Dec 31, 2025

View reviewed changes

packages/relay/src/mod.ts Outdated Show resolved Hide resolved

packages/relay/src/base.ts Outdated Show resolved Hide resolved

packages/relay/src/base.ts Show resolved Hide resolved

sij411 and others added 2 commits December 31, 2025 21:10

Make relaybuilder to be private

a3cbb0e

dahlia approved these changes Dec 31, 2025

View reviewed changes

Merge branch 'next' into feat/addrelayapi

e5b254d

sij411 marked this pull request as ready for review December 31, 2025 16:39

dahlia merged commit 83b8fa2 into fedify-dev:next Dec 31, 2025
18 of 19 checks passed

sij411 mentioned this pull request Dec 31, 2025

Add relay manual #512

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add relay follower query API and refactor types #514

Add relay follower query API and refactor types #514

sij411 commented Dec 31, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Dec 31, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Dec 31, 2025 •

edited

Loading

Uh oh!

dahlia left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Add relay follower query API and refactor types #514

Add relay follower query API and refactor types #514

Conversation

sij411 commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New Public API Methods

Type System Refactor

Implementation Details

Benefits

Uh oh!

gemini-code-assist bot commented Dec 31, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dahlia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sij411 commented Dec 31, 2025 •

edited

Loading

codecov bot commented Dec 31, 2025 •

edited

Loading