Storage
PeerPigeon's storage is a set of records, each under a key in one of five spaces. Every change is signed by the key that made it, synced to the room, and kept on the room's storage servers when there are any.
Spaces
| Space | Who may write | Kept where |
|---|---|---|
public | Anyone in the room | Synced to the room and its servers |
user | Its first writer only: the record's owner is the key that signed it | Synced to the room and its servers |
frozen | Written once, never changed (for content named by its own hash) | Synced to the room and its servers |
private | This node only | This device only, never synced |
epublic | PeerPigeon itself (putSystem) | Synced; for internal records |
A record carries its ownerId, the signer that wrote it, when it was made and changed, and a version. A change from another peer is taken only if it is signed, so nobody can write as someone else, and a user record can be changed only by its owner.
Reading and writing
const s = node.storage
await s.put('user', `profiles/${s.signer()}`, { name: 'Maya' })
await s.get('user', `profiles/${s.signer()}`) // what this node holds
await s.retrieve('public', 'scores/today', { timeoutMs: 3000 }) // ask the room and its servers
await s.list('public') // everything this node holds in a space
await s.delete('public', 'scores/today')get answers from what this node holds; retrieve also asks the room and the servers when it holds nothing.
Following changes
const stop = s.subscribe(({ origin, op, space, key, record }) => {
// origin: 'local' or 'remote'; op: 'upsert' or 'delete'
})
s.subscribeKey('public', 'scores/today') // follow one key you do not replicateReplicating a namespace
storage: { replicate: ['notes/'] } makes a node keep every record under notes/ without subscribing to each key, and a neighbour that links up sends it every such record at once. An app that shows a whole collection (a feed, a list of games) replicates its prefix.
Deletes stay deleted
A delete is kept as a tombstone for 180 days. A peer that was away and still holds the old record does not bring it back: when it syncs, the delete wins.
Storage servers
With storage servers in the room (the default is to use them when there are any):
- records go to the room's three closest servers as they are written, and come back from them;
- once the servers hold a record, a node drops its own copy unless it uses it (subscribed, replicated or private) and reads it back when asked;
- a page that opens before the servers are linked gets the records as changes once they are.
storage: { servers: false } keeps storage on the mesh alone. Files and pictures use the same servers through their blob store, cut into 128 KB pieces kept by their SHA-256.
A room of one's own
node.openStorage(sessionId, { owner }) opens a room that takes only records signed by one key, on the servers as well. Apps use it for a person's own data, such as an encrypted vault that should sync between that person's devices and nobody else's.