1 | # ssb-blobs
|
2 |
|
3 | Protocol for gossiping "blobs", in no particular order. This is a plugin for [secret-stack](https://github.com/ssbc/secret-stack) and such general information about these type of plugins is [documented in `plugins.md` in that repository](https://github.com/ssbc/secret-stack/blob/master/PLUGINS.md).
|
4 |
|
5 | ## Protocol
|
6 |
|
7 | When two peers connect, they request the blobs they "want" from each other.
|
8 | They do this by sending a JSON object that is a map of
|
9 | `{<blob_id>: -hop_count}` (note, the hop count is negative) to the peer.
|
10 | If they have a blob wanted by the peer, they respond with the size they have
|
11 | for that blob: `{<blob_id>: size}` (note, size is positive - this is how sizes
|
12 | and blobs are distinguished).
|
13 |
|
14 | Peers can only request blobs they know about. In the legacy
|
15 | [scuttlebot/plugins/blobs](https://github.com/ssbc/scuttlebot/tree/99fad7c5f6e436cbd670346b4da20c57222a1419/plugins/blobs)
|
16 | peers would request blobs that where mentioned in an
|
17 | [ssb-feed](https://github.com/ssbc/ssb-feed) but this approach
|
18 | means they cannot know about (encrypted) blobs shared in private
|
19 | messages, or about blobs recursively linked from other blobs.
|
20 |
|
21 | This protocol addresses that by implementing _sympathetic wants_.
|
22 | If a peer requests a blob that you do not have, you start to want it too.
|
23 | To prevent these requests from flooding the entire network, you signal how much
|
24 | you want a blob with a hop count.
|
25 | If you want it for yourself, you use a `hop_count` of -1.
|
26 | If you want it for a friend, you use a `hop_count` of -2 (and so on..)
|
27 |
|
28 | This allows you to publish a secret blob, without creating
|
29 | a permanent cryptographic record of that blob.
|
30 |
|
31 | However, this alone would mean that to upload a blob,
|
32 | someone else needs to request it from you, which requires
|
33 | both peers to be online at the same time.
|
34 |
|
35 | To address this, we have a `push` method. "pushing" a blob,
|
36 | just makes a peer "pretend" that they want a blob,
|
37 | triggering sympathetic wants from intermediate nodes,
|
38 | ensuring that there are at least some peers that will have the blob.
|
39 | (currently, your peer will continue to pretend they want the
|
40 | blob until at least 3 peers report having it)
|
41 |
|
42 |
|
43 | ## Configuration
|
44 |
|
45 | By changing `.ssb/config`, you can control how generous
|
46 | ssb-blobs will be. These are the default values:
|
47 |
|
48 | ``` js
|
49 | "blobs": {
|
50 | "stingy": false,
|
51 | "sympathy": 3,
|
52 | "pushy": 3,
|
53 | "legacy": true,
|
54 | "max": 5000000,
|
55 | }
|
56 | ```
|
57 |
|
58 | ### `stingy` (default `false`)
|
59 |
|
60 | Enabling `stingy` mode will make your pub pretend it does not have blobs
|
61 | unless it _wants_ to push those blobs to the network. (because you have uploaded that file)
|
62 |
|
63 | ### `sympathy` (default `3`)
|
64 |
|
65 | When a peer asks for a blob, if you do not have it, then out of sympathy you'll
|
66 | ask for it from your other peers.
|
67 | The value for `sympathy` determines how many hops away from you that peer may be.
|
68 | Note that this depends on hops on the current network topology, not the follow
|
69 | graph: `ssb-blobs` is actually completely independent of the ssb logs.
|
70 |
|
71 | Set this to 0 to never request a blob that someone else has asked for, unless _you_ want it too.
|
72 |
|
73 | ### `pushy` (default `3`)
|
74 |
|
75 | When you publish a blob, tell everyone about it, until at least this many peers have taken it.
|
76 | Of course for this they will need a setting for `sympathy` > 0.
|
77 |
|
78 |
|
79 | ### `legacy` (default `true`)
|
80 |
|
81 | Whether you support the legacy style blob replication or not.
|
82 | It's probably safe to disable this now since most pubs will have updated by now.
|
83 |
|
84 | ### `max` (default `5MB`)
|
85 |
|
86 | Maximum size of blobs to replicate.
|
87 | Note that if you set this too low, blobs will simply fail to be retrieved.
|
88 |
|
89 | ## Usage
|
90 | This plugin is required by default by [ssb-server](https://github.com/ssbc/ssb-server) and doesn't need to be added to your system if you're using a standard Secure Scuttlebutt install. If you're rolling your own, please refer to [the documentation in `plugins.md` in the `secret-stack` repository](https://github.com/ssbc/secret-stack/blob/master/plugins.md) for how to create your own peer-to-peer solution that uses this plugin.
|
91 |
|
92 | ## License
|
93 |
|
94 | MIT
|
95 |
|
96 |
|
97 |
|