feat(cli): Real-time ActivityPub debug dashboard #319
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @notJoon, 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 significant new debugging capability to the CLI, enabling developers to gain real-time insights into ActivityPub federation traffic. It provides a flexible and powerful toolset for monitoring inbound and outbound activities, offering both a web-based dashboard for visual analysis and a terminal interface for command-line driven debugging. This feature will greatly assist in understanding and troubleshooting ActivityPub interactions within the application.
Highlights
- New
debugCLI Command: Introduces a powerful newdebugcommand to the CLI for real-time monitoring and analysis of ActivityPub federation activities. - Dual Debugging Interfaces: Provides two distinct ways to debug: a web-based dashboard for a rich, interactive experience and a terminal-based interface for quick, command-line inspection.
- Real-time Activity Monitoring: The core functionality allows users to intercept and view inbound and outbound ActivityPub activities as they happen.
- Comprehensive Activity Data: Captured activities include direction (inbound/outbound), type, timestamp, and the full raw ActivityPub JSON, aiding in detailed debugging.
- Activity Storage and Search: Activities are stored in a circular buffer (
ActivityStore) with configurable capacity, enabling retrieval, filtering by type, direction, and time range, and statistical analysis. - Flexible Terminal Output: The terminal debugger offers options for following real-time streams, showing the last N activities, filtering, displaying statistics, and viewing raw activity JSON, with customizable colorization.
- Web Dashboard API & WebSockets: The web dashboard exposes REST API endpoints for activities and statistics, and a WebSocket endpoint for real-time updates, facilitating external tool integration or custom UI development.
- Modular Design: The debugging functionality is built with modular components (
ActivityInterceptor,ActivityStore,DebugServer,TerminalFormatter,TerminalDebugger), promoting maintainability and extensibility.
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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| 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 issue 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 is currently in preview and 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 to provide feedback.
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
-
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. ↩
github-actions
bot
added
activitypub/interop
There was a problem hiding this comment.
Code Review
This pull request introduces a real-time ActivityPub debug dashboard, a significant new feature for the CLI. The code is well-structured with a clear separation of concerns and includes an impressive suite of tests. My review focuses on improving correctness, robustness, and clarity. I've identified a critical bug in the terminal filtering logic and made several medium-severity suggestions to enhance input validation, unique ID generation, and code readability.
cli/debug.tsx
Outdated
| "--direction=<direction:string>", | ||
| "Filter by direction: inbound or outbound (terminal mode only).", | ||
| ) |
There was a problem hiding this comment.
To improve correctness and provide better command-line validation, consider using EnumType from cliffy to restrict the allowed values for the --direction option. This enhances the user experience by showing allowed values in the help text and validating input.
"--direction=<direction:direction>",
"Filter by direction: inbound or outbound (terminal mode only).",
{ type: new EnumType(["inbound", "outbound"]) },
cli/debug/formatter.ts
Outdated
| private colorStrategy: ColorStrategy; | ||
| constructor(private options: FormatterOptions = {}) { | ||
| this.options = { | ||
| showRawActivity: false, | ||
| showTimestamp: true, | ||
| colorize: true, | ||
| ...options, | ||
| }; | ||
| this.colorStrategy = options.colorize === false | ||
| ? new ColorizeOff() | ||
| : new ColorizeOn(); | ||
| } |
There was a problem hiding this comment.
To improve code clarity, refactor the constructor logic to explicitly define the options property and streamline the colorStrategy assignment.
private readonly colorStrategy: ColorStrategy;
private readonly options: Required<FormatterOptions>;
constructor(options: FormatterOptions = {}) {
this.options = {
showRawActivity: false,
showTimestamp: true,
colorize: true,
...options,
};
this.colorStrategy = this.options.colorize
? new ColorizeOn()
: new ColorizeOff();
}
cli/debug/interceptor.ts
Outdated
| } | ||
|
|
||
| return { | ||
| id: `debug-${++this.activityCounter}-${Date.now()}`, |
There was a problem hiding this comment.
For more robust unique ID generation, consider using crypto.randomUUID() instead of Date.now(), which is available as a global in Deno.
| id: `debug-${++this.activityCounter}-${Date.now()}`, | |
| id: crypto.randomUUID(), |
cli/debug/server.ts
Outdated
| const clientId = `client-${Date.now()}-${ | ||
| Math.random().toString(36).substring(7) | ||
| }`; |
There was a problem hiding this comment.
For more robust client ID generation, consider using crypto.randomUUID() instead of Date.now() and Math.random().
const clientId = crypto.randomUUID();
cli/debug/server.ts
Outdated
| socket.onerror = (evt) => { | ||
| logger.error("WebSocket error for {clientId}: {error}", { | ||
| clientId, | ||
| error: evt, | ||
| }); | ||
| }; |
There was a problem hiding this comment.
To improve error logging, check if the event in socket.onerror is an ErrorEvent and log its message property for better diagnostics.
socket.onerror = (evt) => {
const errorMessage = evt instanceof ErrorEvent ? evt.message : "WebSocket error";
logger.error("WebSocket error for {clientId}: {error}", {
clientId,
error: errorMessage,
});
};
cli/debug/terminal.test.ts
Outdated
| function assert(condition: boolean, message?: string): void { | ||
| if (!condition) { | ||
| throw new Error(message || "Assertion failed"); | ||
| } | ||
| } |
There was a problem hiding this comment.
To maintain consistency, use the standard library's assert function instead of defining a custom helper function. Update the import on line 1 to include assert.
|
Would you rebase? .vocab.ts file is now in gitignore |
@malkoG Done 👍 |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
|
Thank you so much for all the hard work you've put into implementing this real-time ActivityPub debug dashboard! 🙏 The architecture you've built with the I feel a bit bad suggesting a different direction after you've already done so much work, but I had some thoughts about the integration approach that might make this feature even more useful for developers. Please know that I really appreciate the effort you've already invested—the core concepts and implementation details you've built are excellent and could largely be reused. Your current approach with the standalone CLI debug command is well-architected with clean separation between What if we integrated the debugger directly into the The proposed API would add a const federation = createFederation({
kv: new MemoryKvStore(),
debugger: true, // Enables /__debugger__ endpoint
});Since the federation router already handles various endpoints like Most of your excellent implementation could be reused—your I'm really sorry to suggest this direction change after you've built so much! Your implementation is genuinely impressive and the core architecture is sound. Would you be interested in exploring this federation-integrated approach, or do you prefer to continue with the CLI-based direction? Either way, I think this debug dashboard will be incredibly valuable for Fedify developers. Thank you again for taking this on! 🚀 |
|
I've created a related issue #323 that proposes a more general interface approach, which would enable your debug dashboard implementation while keeping the core package lean and extensible for other use cases. Would love to hear your thoughts on this direction! |
Summary
WIP
Related Issue
Reference the related issue(s) by number, e.g.:
Changes
List the specific modifications made in this PR.
Focus on what was changed without going into detail about impact.
Benefits
Describe the advantages or improvements brought by these changes.
Explain how these changes affect the project, users, or performance.
Checklist
deno task test-allon your machine?Additional Notes
Include any other information, context, or considerations.