search

ssbc / ssb-meta-feeds

10 stars 0 forks source link

readme

ssb-meta-feeds

An implementation of the ssb metafeed spec in JS as a secret stack plugin. The core idea is being able to split out content you publish into subfeeds. This allows for quicker replication by peers, such that you only get the subfeeds, thus content types, you are interested in.

Metafeeds are special types of feeds which own or "contain" other feeds (called "subfeeds"), by publishing messages which describe the creation of the subfeeds.

graph TB

main

classDef default fill:#3f506c,stroke:#3f506c,color:#fff;

How "classic" scuttlebutt worked - each device has one main feed with all messages

graph TB

root:::root

root-->aboutMe
root-->contacts
root-->posts
root-->main:::legacy

classDef root fill:#8338ec,stroke:#8338ec,color:#fff;
classDef default fill:#3a86ff,stroke:#3a86ff,color:#fff;
classDef legacy fill:#3f506c,stroke:#3f506c,color:#fff;

How scuttlebutt works with metafeeds - each device now has a root metafeed, whose sole responsibility is to announce (point to) subfeeds that you publish content to. A subfeed can also be a metafeed, which then allows the existence of "sub-subfeeds".

This means that when you first meet a peer you can replicate their root metafeed and, having discovered their subfeeds, replicate just their aboutMe and contacts feeds to get enough info to place them socially. Once you decide you want to follow them you may replicate their other subfeeds.

NOTE: The ideal state is that all content is split out into subfeeds. To add backwards compatability for devices that have already posted a lot of posts to their classic main feed, this library will auto-link that main feed in as a "subfeed" of our root.

Installation

Prerequisites:

npm install --save ssb-meta-feeds

Add this plugin like this:

 const sbot = SecretStack({ appKey: caps.shs })
     .use(require('ssb-db2'))
+    .use(require('ssb-bendy-butt'))
+    .use(require('ssb-meta-feeds'))
     // ...

Example usage

We create a subfeed for about messages under our root feed using findOrCreate. This will only create the subfeed if there is no existing subfeed that matches the criteria.

const details = { purpose: 'aboutMe' }
sbot.metafeeds.findOrCreate(details, (err, aboutMeFeed) => {
  console.log(aboutMeFeed)

  //
})

The details argument is an object used to find (or create) a subfeed under your "root feed". (It actually nests it under a couple of subfeeds, to handle versioning, and sparse replication, but you generally don't need to know the details).

Once you have a FeedDetails object, like aboutMeFeed, you can publish on the new subfeed:

const details = { purpose: 'aboutMe' }
sbot.metafeeds.findOrCreate(details, (err, aboutMeFeed) => {
  console.log(aboutMeFeed)

  const content = {
    type: 'about',
    name: 'baba yaga'
    description: 'lives in a hutt in the forest, swing by sometime!'
  }
  sbot.db.create({ keys: aboutMeFeed.keys, content }, (err, msg) => {
    console.log(msg)
  })
})

API

sbot.metafeeds.findOrCreate(details, cb)

Looks for the first subfeed of metafeed that matches details, or creates one which matches these. This creates feeds following the v1 tree structure.

Arguments:

Meaning:

NOTES:

sbot.metafeeds.findOrCreate(cb)

Fetches the root metafeed details of your own meta feed tree. There can only be one root metafeed in a tree, so even if you call findOrCreate(cb) many times, it will not create duplicates, it will just load the root metafeed.

Callsback with your root FeedDetails object (see findOrCreate(details, cb))

NOTES:

sbot.metafeeds.findRootFeedId(subFeedId, cb)

Finds the id of the root feed in a meta feed tree, given an id of any feed in that tree, including the root feed id itself.

sbot.metafeeds.branchStream(opts)

Returns a pull-stream source of all "branches" in the meta feed trees.

A "branch" is an array where the first item is the root meta feed and the subsequent items are the children and grandchildren (and etc) of the root. A branch looks like this:

[
  rootDetails,
  childDetails,
  grandchildDetails,
]

Or in general, an Array<Details>. The Details object has the shape { id, purpose, feedFormat, keys, parent, metadata } like what findOrCreate returns. If the details is for a feed that doesn't belong to you, the keys field will not be present.

branchStream will emit all possible branches, which means sub-branches are included. For instance, in the example above, branchStream would emit:

[ rootDetails ]

and

[ rootDetails, childDetails ]

and

[
  rootDetails, childDetails, grandchildDetails,
]

The opts argument can have the following properties:

sbot.metafeeds.findAndTombstone(details, reason, cb)

Looks for the first subfeed that matches details and, if found, tombstones it with the string reason.

This is strictly concerned with metafeeds and sub feeds that you own, not with those that belong to other peers.

Arguments:

The callback is called with true on the 2nd argument if tombstoning suceeded, or called with an error object on the 1st argument if it failed.

sbot.metafeeds.getTree(root, cb)

Get an object that represents the full metafeed tree under a given root metafeed.

Arguments:

The tree object has the shape

{
  id,
  purpose,
  feedFormat,
  metadata,
  children: [
    {
      id,
      purpose,
      feedFormat,
      metadata,
      children
    },
  ]
}

The callback is called with the tree object on the 2nd argument if suceeded, or called with an error object on the 1st argument if it failed.

sbot.metafeeds.printTree(root, opts, cb)

Prints (directly to console!) a diagram representation in ASCII for the full metafeed tree under a given root metafeed. Example:

root
└─┬ v1
  ├─┬ 2
  │ └── main
  └─┬ f
    └── chess

Arguments:

The callback is called with undefined on the 1st argument if printing suceeded, or called with an error object if it failed. There is no 2nd argument.

Advanced API

For lower level API docs, see here.

License

LGPL-3.0