Group: GNU Social P2P/Design/Agent2LocalCore

Latest revision as of 23:05, 20 November 2010

Agent to Local Core Protocol

Keys

The Agent has a public key which controls the identity of the user. All values are opaque to the Core and are decrypted on the Agent side. The Agent 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

Agent Side

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

on_receive is a result of a push from a friend.

REST HTTP binding

A simple binding of the Local Core to Agent 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}* ]

Callbacks to Agent:

Agent 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: "..." }

NOTES:

@@ Line 1: / Line 1: @@
 < [[Group:GNU Social P2P/Design]]
-== UI to Core Protocol ==
+== Agent to Local 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.
+The Agent has a public key which controls the identity of the user.  All values are opaque to the Core and are decrypted on the Agent side.  The Agent should have a local cache for performance.
 === Core Side ===
@@ Line 17: / Line 17: @@
 * multiget(max, path [, seek_path]) - return sub-tree
-Sharing:
+=== Agent Side ===
-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.
+A simple binding of the Local Core to Agent protocol over HTTP REST.  All {} enclosed structures are JSON encoded.
 Data manipulation:
@@ Line 71: / Line 49: @@
 returns [ {path: $path, value: $value}* ]
-Sharing:
+Callbacks to Agent:
- set_permission_keys(subject_path, [ { friend: $friend_path, dkey: $permission_dkey, push: $push } ]) - allow access to subject_path to a set of friends
+Agent performs:
- -> 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'
@@ Line 98: / Line 60: @@
   -> { 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: <references/>

Navigation menu