@@ -87,6 +87,13 @@ The usual flow for implementing this tree of data makes heavy use
87of the `connector` library. This library is well documented in
87of the `connector` library. This library is well documented in
88the source, so check out `/=home=/lib/connector/hoon`.
88the source, so check out `/=home=/lib/connector/hoon`.
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
95+ =+ connector=(connector move sub-result) :: Set up connector library
90Most of the Github-specific logic is in `++places`, which is a
97Most of the Github-specific logic is in `++places`, which is a
91list of all the places we can request. A place consists of:
98list of all the places we can request. A place consists of:
@@ -120,23 +127,21 @@ list of all the places we can request. A place consists of:
120 `%y` request must produce an arch, unlike a `%x` request,
127 `%y` request must produce an arch, unlike a `%x` request,
121 which may produce data of any mark.
128 which may produce data of any mark.
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.
128Filling out the list of places is a lot of grunt work, but most
130Filling out the list of places is a lot of grunt work, but most
129places are fairly straightforward, and the `++read-*` helper
131places are fairly straightforward, and the `++read-*` helper
130functions are useful. Check out the library source for more
132functions are useful. Check out the library source for more
131information on those.
133information on those.
133Besides the list of places, we just need to handle the flow of
135Besides 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.
136- `++peek` should usually just produce `~`. If there are cases
140- `++peek` should usually just produce `~`. If there are cases
137 where we can respond directly to a `.^` request without
141 where we can respond directly to a `.^` request without
138 blocking on anything, we could do it here, but it's generally
142 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
141- `++peer-scry` is where the actual handling for a read request
146- `++peer-scry` is where the actual handling for a read request
142 goes. In general, we just need to call `++read` from the
147 goes. In general, we just need to call `++read` from the
@@ -145,11 +150,11 @@ control. There are four functions we need to define:
145 run either `++read-x` or `++read-y`, depending on the care.
150 run either `++read-x` or `++read-y`, depending on the care.
147- If `++read-x` or `++read-y` made a successful API request, then
152- 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
153+ the response will come back on `++sigh-httr`. Here, we just
149− out the wire and call `++sigh` from the `connector` library
154+ need to parse out the wire and call `++sigh` from the
150− with the list of places, care, path, and HTTP result. This
155+ `connector` library with the list of places, care, path, and
151− will match the path to the appropriate place and run either
156+ HTTP result. This will match the path to the appropriate place
152− `++sigh-x` or `++sigh-y`, depending on the care.
157+ and run either `++sigh-x` or `++sigh-y`, depending on the care.
154- If `++read-x` or `++read-y` made an API request that failed,
159- If `++read-x` or `++read-y` made an API request that failed,
155 then we'll get a stack trace in `++sigh-tang`. Here, we just
160 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.
166## Listening
171## Listening
168Listening for events is fairly service-specific. In some
173Listening for events is fairly service-specific. In some
169−services, we poll for changes. For an example of that, check out
174+services, we poll for changes. The Twitter connector has an
170−the Twitter connector. In Github, we power our event streams
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
171−with webhooks.
178+event streams with webhooks.
173For Github, when someone subscribes to
180For Github, when someone subscribes to
174`/listen/<user>/<repo>/<events...>`, we want to produce
181`/listen/<user>/<repo>/<events...>`, we want to produce