-
-
Notifications
You must be signed in to change notification settings - Fork 85
Description
Summary
This proposal suggests adding a FederationObserver interface to provide extensible hooks into the federation lifecycle, with the primary use case being a debug dashboard (as discussed in #319) but designed to support other observability and extensibility needs.
Motivation
While reviewing PR #319 (Real-time ActivityPub debug dashboard), we identified that the current approach requires integration hooks in the core federation system to capture real ActivityPub traffic. Rather than adding debugger-specific code to the core @fedify/fedify package, we can introduce a general observer pattern that:
- Enables the debug dashboard without coupling debugger code to the core package
- Provides extensibility for other use cases like logging, metrics, analytics, security auditing
- Maintains separation of concerns keeping the core package focused on federation functionality
- Optimizes bundle size by allowing optional feature packages
Proposed API
Core Interface (in @fedify/fedify)
interface FederationObserver<TContextData> {
onInboundActivity?(context: Context<TContextData>, activity: Activity): void | Promise<void>;
onOutboundActivity?(context: Context<TContextData>, activity: Activity): void | Promise<void>;
}
interface FederationOptions<TContextData> {
// ... existing options
observers?: FederationObserver<TContextData>[];
}Debug Implementation (in separate @fedify/debugger package)
export class DebugObserver<TContextData> implements FederationObserver<TContextData> {
constructor(private options: { path?: string } = {}) {}
onInboundActivity(context: Context<TContextData>, activity: Activity) {
this.store.addActivity({
direction: 'inbound',
activity,
timestamp: new Date()
});
}
onOutboundActivity(context: Context<TContextData>, activity: Activity) {
this.store.addActivity({
direction: 'outbound',
activity,
timestamp: new Date()
});
}
// Additional methods for serving debug dashboard UI
}Usage
import { DebugObserver } from '@fedify/debugger';
const debugObserver = new DebugObserver({ path: '/__debugger__' });
const federation = createFederation({
kv: new MemoryKvStore(),
observers: [debugObserver],
});Integration Points
The observers would be called at strategic points in the federation middleware:
- Inbound activities: In
handleInboxafter activity parsing but before listener execution - Outbound activities: In
sendActivitybefore activity transformation and delivery
Benefits
- Decoupled design: Debug functionality lives in separate package
- Extensible: Can support logging, metrics, filtering, security scanning, etc.
- Async support: Unlike current
ActivityTransformer, observers can perform async operations - Bundle optimization: Production builds don't include debug code unless imported
- Multiple observers: Can register multiple observers for different purposes
Future Extensions
While starting minimal for the debug use case, the interface could be extended with additional hooks:
interface FederationObserver<TContextData> {
// Current proposal
onInboundActivity?(context: Context<TContextData>, activity: Activity): void | Promise<void>;
onOutboundActivity?(context: Context<TContextData>, activity: Activity): void | Promise<void>;
// Potential future additions
onActorRequest?(context: Context<TContextData>, actor: Actor): void | Promise<void>;
onCollectionRequest?(context: Context<TContextData>, collection: Collection): void | Promise<void>;
onWebFingerRequest?(context: Context<TContextData>, resource: string): void | Promise<void>;
}Relationship to PR #319
This proposal would enable the debug dashboard from #319 to be implemented as:
- A
@fedify/debuggerpackage that implementsFederationObserver - Integration with the federation router to serve debug UI at configurable paths
- Real-time activity capture without modifying core federation logic
The excellent work in #319 (ActivityStore, WebSocket updates, terminal interface, etc.) would be reused in this new architecture.
Implementation Plan
- Add
FederationObserverinterface to core package - Add
observersoption toFederationOptions - Integrate observer calls in federation middleware
- Create
@fedify/debuggerpackage using work from feat(cli): Real-time ActivityPub debug dashboard #319 - Update documentation and examples
Metadata
Metadata
Assignees
Labels
Type
Projects
Status