API Review and Refactor Nov 30, 2024

[Arlodotexe]

Background

With the recent batch of updates to the various OwlCore libraries I've been incubating to support our new community infrastructure, we're ready to move forward with our implementation.

Just to recap from this thread on Discord:

Here be owls! Updates have arrived, full release notes linked

• IpfsShipyard.Ipfs.Core was updated to 0.7.0 with major fixes and API alignment with Kubo.
• IpfsShipyard.Ipfs.Http.Client was updated to 0.6.0 with similar implementation-side improvements.
• OwlCore.Storage was updated to 0.12.1 with improvements to SystemFile and SystemFolder.
• OwlCore.Kubo was updated to 0.20.0 with support for Filestore and the API improvements in the shipyard.
• OwlCore.Nomad was updated to 0.9.0 with cleanup of extraneous lifecycle-managed properties and support for multi-domain event streams.
• OwlCore.Nomad.Storage was updated to 0.9.0 with no notable changes, mostly cleanup.
• OwlCore.Nomad.Kubo was updated to 0.14.0 with new tooling for root-level event stream handler lifecycle management.
• OwlCore.Nomad.Kubo.Storage was updated to 0.14.0 to implement the underlying updates and add a StorageRepoFactory for easy lifecycle management (unit tested).

This concludes ~2 months of research and planning largely centered around container ownership and operations. With the changes fully validated on a working implementation, now we know exactly what to do and how to do it in the new community infra.

Problem

Our API is outdated and full of leaks and holes. Using insights learned from the various libraries we've built we can identify several potential pitfalls and shortcomings in our current setup.

Before we can move forward with the implementation, we must review and refactor our API surface for both Models (serialized objects) and AppModels (interfaces).
 

Solution

We've performed a full analysis of the API and have identified additions/removals/changes that need to happen to both models and AppModels simultaneously.

We've split this analysis into two sections: Lists and properties. Each section lists what's extra and what's missing for each of the three types.

---

Lists:

Current setup

Publisher

• Projects
• Users
• ParentPublishers
• ChildPublishers

Project

• Collaborators
• Dependencies
• Connections
• Features
• Links
• Images

User

• Connections
• Projects
• Publishers
• Links

---

Changes to make:

[What's extra]:

Publisher doesn't need:

• Users
• Projects

Project doesn't need:

• [n/a]

User doesn't need:

• Projects

[What's missing]:

Publisher is missing:

• Users + Roles
• Connections
• Links

Project is missing:

• [n/a]

User is missing:

• Projects + Roles
• Publisher + Roles

---

Properties:

Current setup

Publisher

• Owner
• Name
• Description
• Icon
• AccentColor
• ContactEmail
• IsUnlisted

Project

• Publisher
• Name
• Description
• Icon
• HeroImage
• AccentColor
• Category
• CreatedAt
• ForgetMe
• IsUnlisted

User

• Name
• MarkdownAboutMe
• Icon
• ForgetMe

---

Changes to make:

[What's extra]:

Publisher doesn't need:

• Owner
• ContactEmail
• Icon

Project doesn't need:

• HeroImage
• CreatedAt
• Icon

User doesn't need:

• MarkdownAboutMe
• Icon

[What's missing]:

Publisher is missing:

• ExtendedDescription
• ForgetMe

Project is missing:

• ExtendedDescription

User is missing:

• ExtendedDescription

---

These changes need to be applied to:

1. Both models and AppModels
2. For both properties and lists
3. For all three types (User, Publisher, Project)

Ignore any build errors for now, we have no implementations but changing things might affect our event entry records. The work within each task can be split up at each order, descending. We'll PR any concurrent work into the PR for order n+1. e.g., Two PRs A and B merge 1) into main, four PRs A1-A2 and B1-B2 merge into A and B (respectively), and so on as needed.

Once all the above is completed, we can adjust our event stream entry records and serializer and begin the implementation of the AppModels using the models we've just refined.

I'll create sub-issues to elaborate on the exact requirements for these tasks a bit more.

### Tasks
- [ ] https://github.com/WindowsAppCommunity/WinAppCommunity.Sdk/issues/3
- [ ] https://github.com/WindowsAppCommunity/WinAppCommunity.Sdk/issues/4
- [ ] https://github.com/WindowsAppCommunity/WinAppCommunity.Sdk/issues/7