@@ -87,6 +87,13 @@ The usual flow for implementing this tree of data makes heavy use
8787of the `connector` library. This library is well documented in
8888the source, so check out `/=home=/lib/connector/hoon`.
8989
90+The `connector` library needs to be initialized with definitions
91+of `move` and `sub-result` (all the types of data that can be
92+returned by a place). This can just be a line at the top of the
93+main core:
94+
95+ =+ connector=(connector move sub-result) :: Set up connector library
96+
9097Most of the Github-specific logic is in `++places`, which is a
9198list of all the places we can request. A place consists of:
9299
@@ -120,23 +127,21 @@ list of all the places we can request. A place consists of:
120127 `%y` request must produce an arch, unlike a `%x` request,
121128 which may produce data of any mark.
122129
123−The `connector` library needs to be initialized with definitions
124−of `move` and `sub-result` (all the types of data that can be
125−returned by a place). `read-x` and `read-y` produce moves and
126−`sigh-x` produces a sub-result.
127−
128130Filling out the list of places is a lot of grunt work, but most
129131places are fairly straightforward, and the `++read-*` helper
130132functions are useful. Check out the library source for more
131133information on those.
132134
133135Besides the list of places, we just need to handle the flow of
134−control. There are four functions we need to define:
136+control. `++peek` and `++peer-scry` are the interface we expose
137+to the rest of the system while `++sigh-httr` and `++sigh-tang`
138+are used to handle responses when we make HTTP requests.
135139
136140- `++peek` should usually just produce `~`. If there are cases
137141 where we can respond directly to a `.^` request without
138142 blocking on anything, we could do it here, but it's generally
139− not worth the hassle.
143+ not worth the hassle since the same logic should be duplicated
144+ in `++peer-scry`.
140145
141146- `++peer-scry` is where the actual handling for a read request
142147 goes. In general, we just need to call `++read` from the
@@ -145,11 +150,11 @@ control. There are four functions we need to define:
145150 run either `++read-x` or `++read-y`, depending on the care.
146151
147152- If `++read-x` or `++read-y` made a successful API request, then
148− it'll come back on `++sigh-httr`. Here, we just need to parse
149− out the wire and call `++sigh` from the `connector` library
150− with the list of places, care, path, and HTTP result. This
151− will match the path to the appropriate place and run either
152− `++sigh-x` or `++sigh-y`, depending on the care.
153+ the response will come back on `++sigh-httr`. Here, we just
154+ need to parse out the wire and call `++sigh` from the
155+ `connector` library with the list of places, care, path, and
156+ HTTP result. This will match the path to the appropriate place
157+ and run either `++sigh-x` or `++sigh-y`, depending on the care.
153158
154159- If `++read-x` or `++read-y` made an API request that failed,
155160 then we'll get a stack trace in `++sigh-tang`. Here, we just
@@ -166,9 +171,11 @@ places are less than ten lines of code.
166171## Listening
167172
168173Listening for events is fairly service-specific. In some
169−services, we poll for changes. For an example of that, check out
170−the Twitter connector. In Github, we power our event streams
171−with webhooks.
174+services, we poll for changes. The Twitter connector has an
175+example of this, but note that it predates the `connector`
176+library and is thus more complicated than it needs to be, and the
177+interface it exposes isn't standard. In Github, we power our
178+event streams with webhooks.
172179
173180For Github, when someone subscribes to
174181`/listen/<user>/<repo>/<events...>`, we want to produce