Group:GNU Social P2P/Design/Agent2LocalCore

< Group:GNU Social P2P/Design

UI to Core Protocol

Keys

The UI has a public key which controls the identity of the user. All values are opaque to the Core and are decrypted on the UI side. The UI should have a local cache for performance.

Core Side

Data manipulation:

• put(path, value, push) - performs store[path] = value, and notifies any friends if push = true
• get(path) - returns store[path]
• delete(path) - performs delete store[path]
• scan(max, path[, seek_path]) - returns paths in sub-tree
• multiget(max, path [, seek_path]) - return sub-tree

Sharing:

Mounting allows accessing a friend's store as if it was local. Mounts are read-only and are cached on the Core. The UI notifies others of changes to their store with send - see below.

• mount(friend_path, remote_path, local_path) - attach friend store
• unmount(local_path) - detach friend store
• set_permission_keys(subject_path, [ { friend: $friend_path, dkey: $permission_dkey, push: $push } ]) - allow access to subject_path to a set of friends

friend_path includes: friend_id, information required to route to the friend, such as domain or IP

permission_dkey is the key used to encrypt the data at the path, encrypted with a friend's public key

All nodes will be encrypted with a permission_dkey corresponding to the owner, so that the UI can read its own store.

Notification:

• request(max, path, order, [, seek_path]) - request a sub-tree under a mount point to be retrieved from the remote

UI Side

• on_receive(route, local_prefix) - notification that a send was received

on_receive is a result of a push from a friend.

• on_mount_done(local_prefix, result)
• on_send_done(local_prefix, result) - notification of a send completed or failed

REST HTTP binding

A simple binding of the Core to UI protocol over HTTP REST. All {} enclosed structures are JSON encoded.

Data manipulation:

put(path, value, push) 
-> PUT '/store/$path?push=$push', { value: $value }

get(path) 
-> GET '/store/$path'

returns { value: $value }

delete(path) 
-> DELETE '/store/$path'

returns number deleted (0 or 1)

scan(max, path, seek_path) 
-> GET '/store/$path/\$scan?seek=$seek_path&max=$max'

\$ designates a literal dollar sign. If $seek_path is specified, jump after that point (useful for paging). Results are in lexicographical order.

returns [ $path* ]

multiget(max, path [, seek_path]) 
-> GET '/store/$path/\$multi?seek=$seek_path&max=$max'

returns [ {path: $path, value: $value}* ]

Sharing:

set_permission_keys(subject_path, [ { friend: $friend_path, dkey: $permission_dkey, push: $push } ]) - allow access to subject_path to a set of friends
-> PUT '/store/$subject_path/\$permit', [ { ... } ]

mount(route, remote_path, local_path)
-> POST '/store/$local_path/\$mount', { route: $route, remote: $remote_path }

unmount(local_path)
-> DELETE '/store/$local_path/\$mount'

Communication:

request(max, path, order, seek_path)
-> POST '/store/$path/\$request', { max: $max, seek_path: $seek_path, order: $order }

Callbacks to UI:

UI performs:

GET '/event'

This is a blocking call. Possible results:

on_receive(route, path)
-> { type: 'receive', path: $path, success: true, $route }
-> { type: 'receive', path: $path, success: false, $route, message: "..." }

on_send_done(route, path, result)
-> { type: 'send_done', path: $path, success: true }
-> { type: 'send_done', path: $path, success: false, message: "..." }

on_mount_done(route, path, result)
-> { type: 'mount_done', path: $path, success: true }
-> { type: 'mount_done', path: $path, success: false, message: "..." }

NOTES: