Implementing event stream handlers

[Arlodotexe]

Background

This background serves as general reference for the two types of data structures in OwlCore.Nomad.Kubo.

Local data

Event streams

• Individual sources published separately by each device
• Read by each individual device
• Contain event stream entries

Event stream entries

• Individual interactions a user has with an application
• Recorded in an event stream
• Unique per device, per published event stream
• From each device, aggregated and time ordered to converge on the same final roaming state as other devices

Roaming data

• Data that is published for consumption by an application or another user
• Represents the sum of interactions from each users' device.
• Eventually convergent

Data handling in an event handler

It's recommended that an application has at minimum 2 sets of models

• Models: Serializable, IPLD compatible models for roaming data
• AppModels: C# "App" models for libray or application-level interaction.
• Event stream entries: Serializable, IPLD compatible models for the individual changes possible in an event stream.

Ideally, these should be:

• All properties deduplicated into interfaces
• 1:1
  • Each interface in Models should exist in AppModels
  • Each member in Models should should exist in AppModels

This smoothes out the process of mapping members in the event stream handler.

Root vs 'Virtual' event handlers

Root

An event stream handler is considered 'root' when the handled roaming data is published to the root of an IPNS dag.

Characteristics:

• Uses full dag
• Is an event handler
• Each instance has isolate scope/keys
• Created via repository
• Usually has unique roaming/local key
• Has roaming id
• Has roaming / local value
• Roaming name required (todo: explain)

Interaction Characteristics:

• Get
  • Must use repo
  • Repo returns a modifiable or read only instance
  • Based on the permissions scoped for that repo.
• Create / Delete
  • Done via Kubo
  • Create: New local/roaming setup
  • Delete: Stop published, delete from Kubo.
• Add / Remove
  • This object can be contained by other event handlers, but is not managed here.
  • This object can contain other event handlers, which is virtual.

Virtual

A 'virtual' event stream handler is not published to the root an IPNS dag, but may be an ancestor of a published IPNS dag.

These event stream handlers still need to handle events, but they have different characteristics than a published 'Root' IEventStreamHandler.

Characteristics:

• Uses a subset of a full 'root' dag
• Runtime dependencies passed down from root handler
• Each instance has separate scope, but a shared key across all virtual handlers from a root
• Created manually, using data from Nomad (not from Repo)
• No local/roaming key, or key is shared across virtual handlers with root.
• No roaming id
• Has roaming/local value
  • Roaming value is subdag
  • Local value is event stream
• Roaming name required (todo: explain)

Interaction Characteristics:

• Get
  • Just instantiating it
  • Using data contained in a higher-level event handler (virtual or root).
  • Done via Nomad
• Create / Delete
  • Same as above
• Add / Remove
  • Same as above

Problem

The event stream handlers are not implemented.

Solution

Using this blueprint, we will implement event stream handlers for the community infrastructure.

1. Create a single "root" and a single "virtual" event stream handler
2. Ensure no further refinements to the blueprint are required, refine as needed.
3. Using the finalized blueprint, map out and identify isolated "Areas" that can be implemented concurrently, creating tickets to delegate work.

Flow diagram

flowchart TB
    subgraph Nomad Data Flow
        A[Nomad] --> B[Event Streams]
        B --> C[Event Stream Entries]
        C --> D[Roaming Data]
    end

    subgraph Data Models
        D --> E(Models - IPLD compatible)
        D --> F(AppModels - C# app models)
        E <--> F
    end

    subgraph Event Stream Handlers
        B --> G[IEventStreamHandler]
        G --> H[Root Handler]
        G --> I[Virtual Handler]
    end

    %% Root Handler
    H -->|Publishes to| IPNS[IPNS DAG]
    H -->|Created/Deleted via| Repo[Kubo / Repo]

    %% Virtual Handler
    I -->|Uses subset of DAG| IPNS
    I -->|Created manually| NomadInst[Nomad Instances]

Loading

### Tasks
- [ ] https://github.com/WindowsAppCommunity/WindowsAppCommunity.Sdk/issues/13
- [x] Use the simple implementations to Discern, Derive and Deduce required refinements to the blueprint, refine simple implementation as needed.
- [x] Use event stream handler blueprint to discern isolated "Areas", deduce execution order, and derive concurrent work
- [x] Create tickets individually detailing concurrent work

[Arlodotexe]

I'm thinking that moving forward with #13 and creating a minimal example will be the best way to simplify this for others.

[Arlodotexe]

Simplified breakdown and additional tracking in #14