sbazerque
commented
1 year ago Hello @timsim00 ! That's an amazing summary and list of questions, thank you again for putting it together.
Even though this library is already a few years old, it's only now becoming a viable platform for apps. The truth is that we're still figuring out a set of generic primitives to base p2p, Byzantine fault tolerant apps on. I think we've got all the pieces by now, but as you hinted I feel we need a set of established patterns / recipes to make it easier.
Data model
Yeah, HashedObject is for data that won't change, but it may contain references to mutable stuff. For example, in the chat group example the root object would look something like
class ChatGroup extends HashedObject {
moderators: MutableSet<Identity>;
messages: MutableSet<Message>;
...
}
So the ChatGroup object is immutable, but contains references to the moderators and messages sets that are mutable.
Like you said, internally a MutableObject is represented as a HashedObject (this is the mutable object's initial state, in the case of the set that would be an empty set). Changes are implemented by creating operations, which are instances of MutationOp (another derivative of HashedObject). So say when you add an element to a set and then save it to the store, MutableSet will create an AddOp containing the new element, and referencing the object you're modifying. Hence a graph of derivatives of HashedObject referencing each other is formed, and it grows as you add or modify data (crucially these objects never change, if you remove that element from the set later, a DeleteOp referencing the set and the AddOpwill be appended to the graph).
So the data model can be seen as transforming mutable state into an append-only graph that can be streamed to other peers.
Spaces
In general, a Space defines the sharing boundary an app will use. In the chat example, it makes sense to use the ChatGroup class as our sharing boundary: folks can join a chat group (and hence get access to all its contents). In document-based apps, a document is a natural candidate for a Space. Usually, the methods startSync and stopSync will configure the mesh node they're on by:
- Joining any necessary peer groups (may be just one per space)
- Asking the mesh node to sync some objects with that peer group
As you mention, it is possible to use spaces as an inter-app integration method. For example, if you define types for something like Slack or Discord, you could have a space for your entire workspace, with all the threads, but you could also define a space per-channel, to make this channels available in other apps / contexts besides your workspace (for example, you may want to make a channel public and embed it into your website, or bridge a channel between two different workspaces to help to organizations collaborate). But this is rather advanced and I've never used spaces like that yet!
Access control
This data model makes access control especially challenging, because the graph we're using to represent data may be replicated un-evenly to peers. So folks may use their access rights concurrently with they being granted or revoked, and some peers may see their actions as valid or invalid initially, but may have to change their mind as more data is replicated. That's what the CausalSets are for: they attach additional information to object mutations, in order to allow all the peers to agree on a state once enough data has been replicated.
Here's an example, again from chat groups, about the rule for deleting messages:
protected createDeleteAuthorizer(msg: Message, author: Identity): Authorizer {
// any member may delete their own messages, but only moderators can delete other's
const membershipReq = author.equals(msg.getAuthor()) ?
this.getMembers()
:
this.getAdmins();
const membershipAuth = membershipReq.createMembershipAuthorizer(author);
return Authorization.chain(super.createDeleteAuthorizer(msg, author), membershipAuth);
}That's saying that we will require a membership attestation (that's an object that serves as proof that something belonged to a given set at the time of this change), and if the author of the message is the same as the author doing the change, we will require an attestation of the author belonging to the members set of the chat group - but if the author of the change (the deletion) is not the same as the author of the message, then he needs to attest that they belong to the moderators set.
This API is not intuitive enough yet, we'll try to find better primitives for expressing this. But in this terms, upon adding an Order to the OrderSet in your example, OrderSet should derive from CausalSet, and its createAddAuthorizer method should return something like this.employeeSet.createMembershipAuthorizer(employee), where employee is the author of the order. This kind of relationships could in theory be nested arbitrarily, to represent the authorization patterns in your app. About CapabilitySet: you're right, we're leaning on just using CausalSets as the right primitive (and probably more types of the Causal... flavor).
Peer Discovery
The default behavior when you use the sync(object) method of the MeshNode is to create a peer group of all the nodes that are trying to sync object, using dynamic peer discovery. So following your example, if the members of AcmeCorp and ABCCorp are sync'ing different objects, they will end up in different peer groups by default. However, in this case it'd probably be better to use a peer group that cannot be freely joined by just knowing which objects to sync. The full signature of sync is sync(object, mode, peerGroup), where a peerGroup is:
type PeerGroupInfo = {
id: string, // a string identifying this peer group
localPeer: PeerInfo, // our local identity
peerSource: PeerSource // a method that will give us random peers to connect
};peerSource may pull peers from an external source, like a database, or use the local replica of an HHS object (like the members set in the chat group, for example). There are several PeerSource implementations here.
As things stabilize a bit more, we'll write a reference manual trying to iron out how to go about all this things. I'll go over your list of questions as soon as I got a bit more time, please just add more questions if the above is not clear.
If perchance you'd be interested in working with us to get the library in shape for app creation, or want to suggest features you feel are missing, or how to go about documenting all this stuff, all would be very welcome.
Thank you again for your analysis & questions, I feel this will help us already!
timsim00
I'm really excited to be learning HHS, as I can see a lot of great, very intelligent, work has gone into it already. From reading the documentation it sounds like it will work for the app I'm building. Now I'm trying to understand how I would use HHS to implement the data model for my app. I've used many different databases but nothing like p2p. I'm very new to this space (no depth of knowledge of Merkle-DAG's, spanning trees, WebRTC etc...but I get graphs). I'm trying to bridge the gap between what I want to do and how HHC works. Here's what I've been able to piece together after a few days with a fresh set of eyes. My apologies in advance if I missed anything obvious in the docs. If anyone is able to confirm or correct my understanding and point me in the right direction I would really appreciate it! Open source examples are always welcome.
High Level
I can put my static SPA app on a CDN and peers will sync app data among themselves. A signaling server is needed to aid in this process, but load on the server is not high. HHS is like a toolbox with tools to enable this.
A Store is an abstract for actual data persistence to a peer, for instance IndexedDB in the browser. An app's data model is made up of many interlinked spaces. Sync logic takes data in a 'Space' and updates the store on a peer using the verify function of each class. The full graph of spaces is represented across the network of peers. Individual peers only have the spaces they edited or requested. Access is granted or revoked using the CausalSet. The whitepaper says CapabilitySet but I think the API has changed since it was written.
Spaces
Spaces can be nested within other spaces by referencing those spaces. Spaces can be discovered independently (of any particular app) via a 3-word code. A space is an abstract for exactly one grouping of data, "a chat room, an article, a blog, an ecommerce store, etc." A class (written by a dev) defines that grouping of data, a potential combination of literals and references to other spaces/class instances, based on business logic. A space is implemented when a class inherits from either an immutable HashedObject or a mutable abstract, ie MutableSet which is a MutableObject.
When to use one or the other, I'm not sure. Seems like a good use-case for HashedObject would be an error log. Or would an error log be represented as a HashedObject nested inside a MutableSet? What are some good use-cases for an immutable space? Will most app data be mutable?
"They can be universally looked up using 3-word codes, like suburb-suburb-awake." If a space really is a class instance, does that mean every single class instance needs a 3-word code? Is this what the Shuffle class is for? If I code a BlogSet class and an Article class, and there are 3 articles in the blog, does that mean there must be 4 spaces total for the blog? Is there ever a situation where the blog would be just one space?
Data Model
(my main question...how to model my app data?)
It seems like an application data model would represent a graph, with the application (for a particular user) pointing to some logical root. Various spaces/classes would then be organized under the root in a way that makes sense according to the business logic. Each user would have various access to all or parts of this node. ie.
App Data (for Acme Employee: Bob) =>
Acme Corp {
Meta: {orgSpace: "acme-corp-best"}
EmployeeSet -> Employee: {name, startDate, title, boss...}
CustomerSet -> Customer: {name, address...}
OrderSet -> Order: {date, total, Lines -> LineItem: {product, qty, price, amount, total}, customer...}
ProductSet -> Product: {name, priceSet...}
OutsideMeetingSet -> Meeting: {mtgDateTime, discussion, Invites -> Invite:{orgSpace: "abc-corp-great"}}
}
Bob may be granted access to all or parts of this graph depending on his role at Acme. This is not the app I want to build, just an example.
Peer Discovery
"Peers in the network form application-defined groups over which mutable objects are synchronized. The method for obtaining peers is also application defined..." I'm not sure what this means. Let's say both Acme Corp ("acme-corp-best") and ABC Corp ("abc-corp-great") are pointing to their respective Org graphs. Does HHS have logic, or does the app need custom logic, to make sure Acme employees are primarily trying to sync with other Acme employees and not ABC employees, other than for shared data like an OutsideMeeting discussion Forum which both companies can access? How does an app define peer groups? Implicitly? Or is there example code for this?
Other questions:
Again, great work on HHC and thank you to anyone who can help confirm/deny assumptions and answer questions. It looks very promising!