Behaviors and Commands

Documentation

Architecture

The Matrix Framework uses behaviors to define how services react to messages and commands to encapsulate service operations.

Service Behaviors

Message Handlers

Define how services respond to messages:

<ServiceNode Name="OrderProcessor">
    <ServiceNode.Behaviors>
        <!-- Handle order creation -->
        <MessageBehavior Path="/orders/create">
            <OnMessage>
                <ValidateMessage />
                <ProcessOrder />
                <NotifySuccess Path="/orders/created" />
            </OnMessage>
        </MessageBehavior>
        
        <!-- Handle order updates -->
        <MessageBehavior Path="/orders/update">
            <OnMessage>
                <ValidateUpdate />
                <UpdateOrder />
                <NotifyUpdate Path="/orders/updated" />
            </OnMessage>
        </MessageBehavior>
    </ServiceNode.Behaviors>
</ServiceNode>

State Behaviors

React to state changes:

<ServiceNode Name="InventoryManager">
    <ServiceNode.Behaviors>
        <!-- Monitor stock levels -->
        <StateBehavior Property="StockLevels">
            <OnChanged>
                <CheckThresholds />
                <TriggerReplenishment When="@level < @threshold" />
                <NotifyLowStock When="@level < @minimum" />
            </OnChanged>
        </StateBehavior>
        
        <!-- Track order status -->
        <StateBehavior Property="OrderStatus">
            <OnChanged>
                <ValidateTransition />
                <UpdateMetrics />
                <NotifyStatusChange Path="/orders/status" />
            </OnChanged>
        </StateBehavior>
    </ServiceNode.Behaviors>
</ServiceNode>

Service Commands

Command Definition

Define operations that can be invoked:

<ServiceNode Name="OrderManager">
    <ServiceNode.Commands>
        <!-- Create order command -->
        <Command Name="CreateOrder">
            <Parameters>
                <Parameter Name="CustomerId" Type="string" />
                <Parameter Name="Items" Type="List<OrderItem>" />
            </Parameters>
            
            <Validation>
                <Required Path="CustomerId" />
                <NotEmpty Path="Items" />
                <Custom Path="Items" 
                        Rule="@item.Quantity > 0" />
            </Validation>
            
            <Execution>
                <CreateOrderEntity />
                <ValidateInventory />
                <ReserveStock />
                <NotifyCreated />
            </Execution>
        </Command>
        
        <!-- Cancel order command -->
        <Command Name="CancelOrder">
            <Parameters>
                <Parameter Name="OrderId" Type="string" />
                <Parameter Name="Reason" Type="string" />
            </Parameters>
            
            <Authorization>
                <RequireRole Role="OrderManager" />
                <RequireOwnership Resource="@OrderId" />
            </Authorization>
            
            <Execution>
                <ValidateOrderState />
                <ReleaseStock />
                <UpdateOrderStatus Status="Cancelled" />
                <NotifyCancelled />
            </Execution>
        </Command>
    </ServiceNode.Commands>
</ServiceNode>

Command Binding

Bind commands to messages:

<ServiceNode Name="OrderAPI">
    <ServiceNode.Bindings>
        <!-- Bind HTTP endpoints to commands -->
        <CommandBinding Path="/api/orders/create" 
                       Command="CreateOrder">
            <ParameterMapping>
                <Map Source="body.customer_id" 
                     Target="CustomerId" />
                <Map Source="body.items" 
                     Target="Items" />
            </ParameterMapping>
        </CommandBinding>
        
        <!-- Bind message to command -->
        <CommandBinding Path="/orders/cancel" 
                       Command="CancelOrder">
            <ParameterMapping>
                <Map Source="message.order_id" 
                     Target="OrderId" />
                <Map Source="message.reason" 
                     Target="Reason" />
            </ParameterMapping>
        </CommandBinding>
    </ServiceNode.Bindings>
</ServiceNode>

Behavior Composition

Behavior Chains

Combine behaviors for complex scenarios:

<ServiceNode Name="OrderProcessor">
    <ServiceNode.Behaviors>
        <!-- Order processing chain -->
        <BehaviorChain>
            <MessageBehavior Path="/orders/submit" />
            <ValidationBehavior />
            <AuthorizationBehavior />
            <TransactionBehavior />
            <MetricsBehavior />
            <LoggingBehavior />
        </BehaviorChain>
    </ServiceNode.Behaviors>
</ServiceNode>

Behavior Templates

Create reusable behavior patterns:

<Template Name="AuditedBehavior">
    <BehaviorChain>
        <LoggingBehavior Level="Info" />
        <MetricsBehavior />
        <AuditBehavior>
            <Track Property="Actor" />
            <Track Property="Action" />
            <Track Property="Resource" />
        </AuditBehavior>
    </BehaviorChain>
</Template>

<ServiceNode Name="OrderManager">
    <ServiceNode.Behaviors>
        <!-- Apply behavior template -->
        <ApplyTemplate Name="AuditedBehavior">
            <Track Property="OrderId" />
            <Track Property="Status" />
        </ApplyTemplate>
    </ServiceNode.Behaviors>
</ServiceNode>

Best Practices

Behavior Design
- Keep behaviors focused
- Compose for complexity
- Handle errors gracefully
- Log behavior decisions
Command Design
- Validate inputs thoroughly
- Enforce authorization
- Maintain idempotency
- Document parameters
Composition
- Use templates for reuse
- Chain behaviors logically
- Monitor performance
- Test combinations

Message Routing State Management