Event Log Branch design

[einari]

Tasks:

• [ ] State for branches: StartedAt, SequenceNumber From, BranchTypeId, Tags
• [ ] Checkout will need to get event log and get the tail sequence number if sequence number from is not specified
• [ ] Introduce branch identifier into EventContext
• [ ] When merging back we want the ability to filter events - cherry pick what we want

Design notes:

• Branch from sequence number (default head if not specified)
• You can't have branches on top of branches
• A branch creates a new temporary event sequence
• Projections working in a branch will project from event log till the event sequence of the branch and then go onto the branch events
• Branches can be used for simulation
• Cherry picking events from the event log after the event sequence should be possible, one can then do changes (compensations) to these events. When merging down, the original events gets the compensations done.
• Merging down from a branch will append the events appended in the branch event sequence
• "Master protection" - rules before we merge down that. Concurrency rules (Optimistic = no rules, pessimistic = specific rules)
• EventContext on the client needs to know which branch we're on
• Inbox projections could project into a branch
• Branches needs metadata that tells type
• Branches could have metadata in the form of tags/labels - key value
• With branch type classification we should be able to ask the system for all active branches of a type

[einari]

Technical notes

Getting events from a start sequence to an end sequence

EventSequenceQueueCacheCursor could be extended with start and end as optional parts. In addition it could have a "follow up" event sequence id. This could then be used to continue delivering events from the branch sequence after the cursor is exhausted.

The cursor for the branch scenario would start at the beginning of the event log and stop at the beginning of the branch and then continue within the branch. Once within a branch, we won't get any changes in the main event log.

Observers

[Observer("07d1ced0-b6a3-432d-883d-12d5ab840828", forBranchType: BranchTypes.BulkPayment]
public class SomeObserver
{
}

EventLog

public class BulkPayments
{
    readonly IEventLog _eventLog;

    public BulkPayments(IEventLog eventLog) => _eventLog = eventLog;

    public async Task<Branch> InitiateFor(AccountId accountId)
    {
         return await _eventLog.Branch(BranchTypes.BulkPayment, new { key = "value" });
    }
}

Immediate Projections

public record AccountBalance(double Balance);

public class BalanceProjection : IImmediateProjectionFor<AccountBalance>
{
    public ProjectionId Identifier => "14e8d5b0-9476-4059-a5e2-09439a98a890";

    public void Define(IProjectionBuilderFor<AccountsCounter> builder) => builder
            .From<DepositToDebitAccountPerformed>(_ => _
                .Add(model => model.Balance).With(@event => @event.Amount))
            .From<WithdrawalFromDebitAccountPerformed>(_ => _
                .Subtract(model => model.Balance).With(@event => @event.Amount))
}

Using it:

immediateProjections.GetInstanceById(accountId, branchId: branchId);

[einari]

Projections

For materialized projections, we could have a dependency tracking mechanism that would sense when there are changes that affects something that a query for a projection is depending on. This would take a copy of an existing projected document before it is modified as the consequence of a new event in the event log into a branch specific collection for all branches affected when a new event occurs on the event log that would affect any result.

For knowing which dependencies one has:

[Route("/api/some/route/{branchId}"]
public class QueryController : Controller
{
     readonly IMongoCollection<ReadModel> _collection;

     public QueryController(IBranchedMongoCollections collections)
     {
          var branchId = (BranchId)RouteData.Values("branchId").ToString();
          _collection = collections.GetFor<ReadModel>(BranchType, branchId);         
     }
}

This could also be added as metadata:

[Route("/api/some/route/{branchId}"]
[Branch(branchType: MyBranchTypeIdentifier, routeValue:"BranchId")]
public class QueryController : Controller
{
     readonly IMongoCollection<ReadModel> _collection;

     public QueryController(IMongoCollection<ReadModel> collection) => _collection = collection;
}

The purpose of this type of mechanism is to provide the correct collection. This collection will need to have a read through mechanism. Basically it will have to run whatever query it has twice; once for the original collection it projects to and then once for the branch and then combine the results.

To avoid getting items that are created after the sequence number the branch starts from, we should keep track on the document of which sequence number created it and the last sequence number that updated it.

When an event is appended to event log any projections affected will be executed. These will then look at what queries exist that is linked to the branch type and know the dependency. If there are no branches for the branch type, it won't do anything. For all branches it will look if there is an initial document for the branch for the instance it is about to project to, copy it to a branch collection.

The projections will need to subscribe to events appended to all branches as it does for the event log.

When a branch is concluded, we will have to clean up all read models collections that are specific for the branch.