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'), usepriorityto ensure the specific one wins. - Custom Filtering: When the standard HubRouting isn't enough,
supply a
matchfunction for complex logic. - Governed Security: Use
contextto 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
keyof 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:
- Cell.hub – the factory that uses these registrations.
- HubRouting – the routing strategies available for hubs.
- HubHandle – the handle returned by Cell.hub.
- DeputyContext – the security context for governed spokes.
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,
});