mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-11-13 08:38:43 +03:00
Merge pull request #3243 from urbit/lf/lib-hooks-docs
lib-hooks: document with comments
This commit is contained in:
matildepark
GitHub
commit
d136c50ccc
@ -1,3 +1,23 @@
|
||||
:: 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:
|
||||
::
|
||||
:: The inner door may interact with the library by producing cards.
|
||||
:: Do not pass any cards on a wire beginning with /helper as these
|
||||
:: wires are reserved by this library. Any watches/pokes/peeks not
|
||||
:: listed below will be routed to the inner door.
|
||||
::
|
||||
:: ## Subscription paths
|
||||
::
|
||||
:: /tracking: The set of resources we are pulling
|
||||
::
|
||||
:: ## Pokes
|
||||
::
|
||||
:: %pull-hook-action: Add/remove a resource from pulling.
|
||||
::
|
||||
/- *pull-hook
|
||||
/+ default-agent, resource
|
||||
::
|
||||
@ -5,12 +25,24 @@
|
||||
|%
|
||||
+$ card card:agent:gall
|
||||
::
|
||||
:: $config: configuration for the pull hook
|
||||
::
|
||||
:: .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
|
||||
update-mark=term
|
||||
push-hook-name=term
|
||||
==
|
||||
::
|
||||
:: $state-0: state for the pull hook
|
||||
::
|
||||
:: .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
|
||||
@ -37,7 +69,29 @@
|
||||
|* 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)]
|
||||
::
|
||||
@ -75,26 +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.
|
||||
::
|
||||
++ 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
|
||||
@ -209,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)
|
||||
|
||||
@ -1,8 +1,41 @@
|
||||
:: 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
|
||||
:: proxies remote pokes to the store.
|
||||
::
|
||||
:: ## Interfacing notes:
|
||||
::
|
||||
:: The inner door may interact with the library by producing cards.
|
||||
:: Do not pass any cards on a wire beginning with /helper as these
|
||||
:: wires are reserved by this library. Any watches/pokes/peeks not
|
||||
:: listed below will be routed to the inner door.
|
||||
::
|
||||
:: ## Subscription paths
|
||||
::
|
||||
:: /resource/[resource]: Receive initial state and updates to
|
||||
:: .resource. .resource should be encoded with en-path:resource from
|
||||
:: /lib/resource. Facts on this path will be of mark
|
||||
:: update-mark.config
|
||||
::
|
||||
:: ## Pokes
|
||||
::
|
||||
:: %push-hook-action: Add/remove a resource from pushing.
|
||||
:: [update-mark.config]: A poke to proxy to the local store
|
||||
::
|
||||
/- *push-hook
|
||||
/+ default-agent, resource
|
||||
|%
|
||||
+$ card card:agent:gall
|
||||
::
|
||||
:: $config: configuration for the push hook
|
||||
::
|
||||
:: .store-name: name of the store to proxy pokes and
|
||||
:: subscriptions to
|
||||
:: .store-path: subscription path to receive updates on
|
||||
:: .update-mark: mark that updates will be tagged with
|
||||
:: .pull-hook-name: name of the corresponding pull-hook
|
||||
::
|
||||
+$ config
|
||||
$: store-name=term
|
||||
store-path=path
|
||||
@ -10,6 +43,12 @@
|
||||
update-mark=term
|
||||
pull-hook-name=term
|
||||
==
|
||||
::
|
||||
:: $state-0: state for the push hook
|
||||
::
|
||||
:: .sharing: resources that the push hook is proxying
|
||||
:: .inner-state: state given to internal door
|
||||
::
|
||||
+$ state-0
|
||||
$: %0
|
||||
sharing=(set resource)
|
||||
@ -21,6 +60,48 @@
|
||||
$_ ^|
|
||||
|_ 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
|
||||
*[(list card) _^|(..on-init)]
|
||||
::
|
||||
@ -58,35 +139,6 @@
|
||||
++ on-fail
|
||||
|~ [term tang]
|
||||
*[(list card) _^|(..on-init)]
|
||||
:: +resource-for-update: get affected resource from an update
|
||||
++ resource-for-update
|
||||
|~ vase
|
||||
*(unit resource)
|
||||
::
|
||||
:: +on-update: handle update from store
|
||||
::
|
||||
:: Do extra stuff on store 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
|
||||
::
|
||||
++ initial-watch
|
||||
|~ [path resource]
|
||||
*vase
|
||||
::
|
||||
--
|
||||
++ agent
|
||||
|* =config
|
||||
|
||||
Loading…
Reference in New Issue
Block a user