SpokeRegistration typedef

SpokeRegistration = ({DeputyContext? context, Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler, String key, bool Function(String? type)? match, int priority, Receptor<Cell>? receptor})

A configuration record for an individual Spoke (Destination) within a Cell.hub.

A SpokeRegistration acts like a registered address in a post office. It defines the "Who" (key), the "How important" (priority), and the "What to do" (handler or receptor) when a signal arrives.

When to use

  • Use this when building complex hubs that require fine-grained control over routing, such as when multiple handlers might match the same signal or when you need specialized security per spoke.
  • Priority Routing: When two spokes match (e.g., 'user.*' and 'user.login'), use priority to ensure the specific one wins.
  • Custom Filtering: When the standard HubRouting isn't enough, supply a match function for complex logic.
  • Governed Security: Use context to assign a DeputyContext to a specific spoke, enforcing Capability-Based Access Control.
  • Mixed Routing: When you need some spokes to use exact matching and others to use pattern matching within the same hub.
  • Fallback Routes: The key of a registration can be used as a Cell.hub fallback when no other spokes match.

How it works

When a hub receives a pulse, it iterates through its list of SpokeRegistrations. It compares the Pulse.type against the key (or runs the match predicate). If a match is found, the signal is routed to that spoke's internal cell.

Example: Basic Spoke Registration

final registration = (
  key: 'auth.success',
  priority: 10,
  handler: (cell, pulse, {user}) {
    print('Login successful!');
    return pulse;
  },
);

Example: Governed Spoke with Custom Context

final secureSpoke = (
  key: 'admin.audit',
  priority: 20,
  match: (type) => type?.startsWith('admin.') ?? false,
  receptor: Receptor((cell, pulse, {user}) {
    // Process admin audit signals
    return pulse;
  }),
  context: DeputyContext(
    baseContext: Context.system,
    authority: 'AUDIT',
    role: 'Auditor',
    clearance: Clearance.administrative,
  ),
);

Example: Pattern Matching Spoke

final patternSpoke = (
  key: 'user.*.profile',  // Matches 'user.123.profile', 'user.456.profile'
  priority: 5,
  match: (type) => type != null && RegExp(r'^user\..+\.profile$').hasMatch(type),
  handler: (cell, pulse, {user}) {
    // Handle user profile updates
    return pulse;
  },
);

See also:

Implementation

typedef SpokeRegistration = ({
  /// The routing address or label used to identify this destination.
  ///
  /// Depending on the [HubRouting] mode, this key is matched against
  /// the incoming [Pulse.type].
  String key,

  /// The precedence of this spoke relative to others.
  ///
  /// When multiple spokes match a single [Pulse.type], the hub uses this
  /// value to decide which one to prefer (unless in `multicast` mode).
  /// Higher values are evaluated and triggered first.
  int priority,

  /// A specialized filter that determines if a signal belongs to this spoke.
  ///
  /// When provided, this logic overrides the global [HubRouting] strategy
  /// for this specific registration. Return `true` to accept the pulse.
  bool Function(String? type)? match,

  /// The functional logic to execute when a pulse is routed to this spoke.
  ///
  /// Use this for "Simple Mode" where you just want to run a function.
  /// Exactly one of [handler] or [receptor] must be non-null.
  Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler,

  /// A pre-built reactive object that manages its own state and logic.
  ///
  /// Use this for "Governed Mode" where the spoke is a complex cell with
  /// its own security and lifecycle rules.
  Receptor? receptor,

  /// The specialized permission and identity record for this spoke.
  ///
  /// If provided, this [DeputyContext] enforces specific **Authority**
  /// and **Role** restrictions for all signals arriving at this destination.
  DeputyContext? context,
});