lib-hooks: address mark review

pkg/arvo/lib/pull-hook.hoon

@@ -1,11 +1,10 @@
-::  lib/pull-hook/hoon: helper for creating a push hook
+::  lib/pull-hook: helper for creating a push hook
 ::  
 ::   lib/pull-hook is a helper for automatically pulling data from a
 ::   corresponding push-hook to a store. 
 ::   
 ::   ## Interfacing notes:
 ::
-::   lib/push-hook provides the inner door with its own separate state.
 ::   The inner door may interact with the library by producing cards or
 ::   scrying. Do not pass any cards on a wire beginning with /helper as
 ::   these wires are reserved by this library. Any watches/pokes/peeks
@@ -28,10 +27,10 @@
 ::
 ::  $config: configuration for the pull hook
 ::
-::    .store-name: name of the store to proxy subscriptions to.
+::    .store-name: name of the store to send subscription updates to.
 ::    .update-mark: mark that updates will be tagged with
 ::    .push-hook-name: name of the corresponding push-hook
-
+::
 +$  config
   $:  store-name=term
       update=mold
@@ -44,6 +43,7 @@
 ::    .tracking: a map of resources we are pulling, and the ships that
 ::    we are pulling them from.
 ::    .inner-state: state given to internal door
+::
 +$  state-0
   $:  %0
     tracking=(map resource ship)
@@ -69,6 +69,28 @@
   |*  config
   $_  ^|
   |_  bowl:gall
+  ::  +on-pull-nack: handle failed pull subscription
+  ::
+  ::    This arm is called when a pull subscription fails. lib/pull-hook
+  ::    will automatically delete the resource from .tracking by the
+  ::    time this arm is called.
+  ::
+  ++  on-pull-nack
+    |~  [resource tang]
+    *[(list card) _^|(..on-init)]
+  ::  +on-pull-kick: produce any additional resubscribe path
+  ::
+  ::    If non-null, the produced path is appended to the original
+  ::    subscription path. This should be used to encode extra
+  ::    information onto the path in order to reduce the payload of a
+  ::    kick and resubscribe.
+  ::
+  ::    If null, a resubscribe is not attempted
+  ::
+  ++  on-pull-kick
+    |~  resource
+    *(unit path)
+  ::
   ::  from agent:gall
   ++  on-init
     *[(list card) _^|(..on-init)]
@@ -107,28 +129,6 @@
   ++  on-fail
     |~  [term tang]
     *[(list card) _^|(..on-init)]
-  ::  +on-pull-nack: handle failed pull subscription
-  ::
-  ::    This arm is called when a pull subscription fails. lib/pull-hook
-  ::    will automatically delete the resource from .tracking by the
-  ::    time this arm is called.
-  ::
-  ++  on-pull-nack
-    |~  [resource tang]
-    *[(list card) _^|(..on-init)]
-  ::  +on-pull-kick: produce any additional resubscribe path
-  ::
-  ::    If non-null, the produced path is appended to the original
-  ::    subscription path. This should be used to encode extra
-  ::    information onto the path in order to reduce the payload of a
-  ::    kick and resubscribe.
-  ::
-  ::    If null, a resubscribe is not attempted
-  ::
-  ++  on-pull-kick
-    |~  resource
-    *(unit path)
-  ::  ::
   --
 ++  agent
   |*  =config
@@ -243,7 +243,10 @@
         =^  cards  pull-hook
           (on-fail:og term tang)
         [cards this]
-      ++  on-peek   on-peek:def
+      ++  on-peek   
+        |=  =path
+        ^-  (unit (unit cage))
+        (on-peek:og path)
     --
   |_  =bowl:gall
   +*  og   ~(. pull-hook bowl)

pkg/arvo/lib/push-hook.hoon

@@ -1,4 +1,4 @@
-::  lib/push-hook/hoon: helper for creating a push hook
+::  lib/push-hook: helper for creating a push hook
 ::  
 ::   lib/push-hook is a helper for automatically pushing data from a
 ::   local store to the corresponding pull-hook on remote ships. It also
@@ -6,7 +6,6 @@
 ::
 ::   ## Interfacing notes:
 ::
-::   lib/push-hook provides the inner door with its own separate state.
 ::   The inner door may interact with the library by producing cards or
 ::   scrying. Do not pass any cards on a wire beginning with /helper as
 ::   these wires are reserved by this library. Any watches/pokes/peeks
@@ -15,7 +14,7 @@
 ::   ##  Subscription paths
 ::
 ::   /resource/[resource]: Receive initial state and updates to
-::   .resource. .resource should be encoded with de-path:resource from
+::   .resource. .resource should be encoded with en-path:resource from
 ::   /lib/resource. Facts on this path will be of mark
 ::   update-mark.config
 ::
@@ -60,6 +59,47 @@
   |*  =config
   $_  ^|
   |_  bowl:gall
+  ::
+  ::  +resource-for-update: get affected resource from an update
+  ::  
+  ::    Given a vase of the update, the mark of which is
+  ::    update-mark.config, produce the affected resource, if any.
+  ::
+  ++  resource-for-update
+    |~  vase
+    *(unit resource)
+  ::
+  ::  +take-update: handle update from store
+  ::
+  ::    Given an update from the store, do other things after proxying
+  ::    the update
+  ::
+  ++  take-update
+    |~  vase
+    *[(list card) _^|(..on-init)]
+  ::  +should-proxy-update: should forward update to store
+  ::
+  ::    If %.y is produced, then the update is forwarded to the local
+  ::    store. If %.n is produced then the update is not forwarded and
+  ::    the poke fails.
+  ::
+  ++  should-proxy-update
+    |~  vase
+    *?
+  ::  +initial-watch: produce initial state for a subscription
+  ::
+  ::    .resource is the resource being subscribed to.
+  ::    .path is any additional information in the subscription wire.
+  ::    This would typically be used to encode state that the subscriber
+  ::    already has. For example, a chat client might encode
+  ::    the number of messages that it already has, or the date it last
+  ::    received an update.
+  ::
+  ::    If +initial-watch crashes, the subscription fails.
+  ::
+  ++  initial-watch
+    |~  [path resource]
+    *vase
   ::  from agent:gall
   ::
   ++  on-init
@@ -99,48 +139,6 @@
   ++  on-fail
     |~  [term tang]
     *[(list card) _^|(..on-init)]
-  ::
-  ::  +resource-for-update: get affected resource from an update
-  ::  
-  ::    Given a vase of the update, the mark of which is
-  ::    update-mark.config, produce the affected resource, if any.
-  ::
-  ++  resource-for-update
-    |~  vase
-    *(unit resource)
-  ::
-  ::  +on-update: handle update from store
-  ::
-  ::    Given an update from the store, do other things after proxying
-  ::    the update
-  ::
-  ++  take-update
-    |~  vase
-    *[(list card) _^|(..on-init)]
-  ::  +should-proxy-update: should forward update to store
-  ::
-  ::    If %.y is produced, then the update is forwarded to the local
-  ::    store. If %.n is produced then the update is not forwarded and
-  ::    the poke fails.
-  ::
-  ++  should-proxy-update
-    |~  vase
-    *?
-  ::  +initial-watch: produce initial state for a subscription
-  ::
-  ::    .resource is the resource being subscribed to.
-  ::    .path is any additional information in the subscription wire.
-  ::    This would typically be used to encode state that the subscriber
-  ::    already has. For example, a chat client might encode
-  ::    the number of messages that it already has, or the date it last
-  ::    received an update.
-  ::
-  ::    If +initial-watch crashes, the subscription fails.
-  ::
-  ++  initial-watch
-    |~  [path resource]
-    *vase
-  ::
   --
 ++  agent
   |*  =config