docs/tutorials/gall/http.udon · urbit.org

git.iko.soy/urbit.org

on c19bc7a help sign in

urbit.org/docs/tutorials/gall/http.udon

215 lines 8.1 kB history raw

1:- :~ navhome/'/docs/'

2 navuptwo/'true'

3 next/'true'

4 sort/'7'

5 title/'HTTP requests and timers'

6 ==

7;>

9# Writing an HTTP request

11There's a variety of arvo services we haven't touched on yet.

12Let's figure out how to make HTTP requests and set timers.

14Let's build an uptime-monitoring system. It'll ping a web

15service periodically and print out an error when the response

16code isn't 2xx. Save the following as `app/up.hoon`:

18```

19:: Up-ness monitor. Accepts atom url, 'on', or 'off'

20::

21:::: /hoon/up/app

22 ::

23/? 314

24|%

25+$ move [bone card]

26+$ card

27 $% [%hiss wire unit-iden=$~ mark=%httr cage=[mark=%purl vase=purl:eyre]]

28 [%wait wire @da]

29 ==

30+$ action

31 $% [%on $~] :: enable polling('on')

32 [%off $~] :: disable polling('off)

33 [%target p=cord] :: set poll target('http://...')

34 ==

35--

36|_ [hid=bowl:gall on=_| in-progress=_| target=@t]

37++ poke-atom

38 |= url-or-command=@t ^- (quip move _+>)

39 =+ ^- act/action

40 ?: ?=($on url-or-command) [%on ~]

41 ?: ?=($off url-or-command) [%off ~]

42 [%target url-or-command]

43 ?- -.act

44 $target [~ +>.$(target p.act)]

45 $off [~ +>.$(on |)]

46 $on

47 :- ?: |(on in-progress) ~

48 [ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]~

49 +>.$(on &, in-progress &)

50 ==

51++ sigh-httr

52 |= [wir=wire code=@ud headers=mess:eyre body=(unit octs)]

53 ~& 'arrive here'

54 ^- [(list move) _+>.$]

55 ?: &((gte code 200) (lth code 300))

56 ~& [%all-is-well code]

57 :_ +>.$

58 [ost.hid %wait /timer (add ~s10 now.hid)]~

59 ~& [%we-have-a-problem code]

60 ~& [%headers headers]

61 ~& [%body body]

62 :_ +>.$

63 [ost.hid %wait /timer (add ~s10 now.hid)]~

64++ wake-timer

65 |= [wir=wire $~] ^- (quip move _+>)

66 ?: on

67 :_ +>.$

68 [ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]~

69 [~ +>.$(in-progress |)]

70::

71++ prep ~& target _`. :: computed when the source file changes;

72-- :: here it prints target then resets our state

73```

75There's some fancy stuff going on here. We'll go through it line by

76line, though.

78There's two kinds of cards we're sending to arvo. A `%hiss` move tells

79`%eyre` to make an HTTP request. It expects a `(unit iden)`, which will

80be null here because we aren't doing any authentication; a mark, in this

81case the http request mark `&httr`; and some data in the form of a

82`cage`, which is a `[mark vase]`. This is confusing, so the mold in the

83code quoted above includes a bunch of otherwise unnecessary faces for

84the purpose of illustration. Compare: `[%hiss p=(unit iden) q=mark

85r=cage]` from `zuse`.

87> You can grep zuse.hoon and arvo.hoon for most of these definitions. However, beware the ambiguity surrounding "hiss": there's ++hiss in section 3bI of `zuse` ("Arvo structures"), and there's `%hiss` the move that is sent to %eyre to make our HTTP request happen. Here we're talking about the latter. See `++kiss-eyre` in `zuse`.

89> Recall that `++unit` means "maybe". Formally, "`(unit a)` is either null or a pair of null and a value in `a`". Also recall that to pull a value out of a unit (`u.unit`), you must first verify that the unit is not null (for example with `?~`). See `++need`.

91A `purl:eyre` is a parsed url structure, which can be created with `de-purl:html`,

92which is a function that takes a url as text and parses it into a `(unit

93purl:eyre)`. Thus, the result is null if and only if the url is malformed.

94'Purl' is also the mark which will be applied to this result.

96When you send this request, you can expect a `%sigh` with the

97response, which we handle later on in `++sigh-httr`.

99For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will

100produce a `%wake` when the time comes.

101

102> A timer is guaranteed to not be triggered before the given time, but it's currently impossible to guarantee the timer will be triggered at exactly the requested time.

103

104Let's take a look at our state:

105

106```

107|_ [hid=bowl:gall on=_| in-progress=_| target=@t]

108```

109

110We have three pieces of app-specific state. `target` is the url

111we're monitoring. `on` and `in-progress` are booleans

112representing, respectively, whether or not we're supposed to keep

113monitoring and whether or not we're in the middle of a request.

114

115The type of booleans is usually written as `?`, which is a union

116of `&` (true) and `|` false. This type defaults to `&` (true). In our

117case, we want both of these to default to `|` (false). Because

118of that, we use `_|` as the type. `_value` means "take the type

119of `value`, but make the default value be `value`". Thus, our

120type is still a boolean, just like `?`, but the default value is

121`|` (false).

122

123> This is the same `_` used in `_+>.$`, which means "the same type as the value "+>.$". In other words, the same type as our current context and state.

124

125Let's take a look at `++poke-atom`. When we're poked with an atom, we

126first check whether the atom is `'off'`. If so, we set our state

127variable `on` to false.

128

129If not, we check whether the atom is `'on'`. If so, we set `on` and

130`in-progress` to true. If it was already either on or in progress, then

131we don't take any other immediate action. If it was both off and not in

132progress, then we send an HTTP request.

133

134If the argument is neither 'off' nor 'on', then we assume it's an

135actual url, so we save it in `target`.

136

137Here's the move that sends the HTTP request:

138

139```

140[ost.hid %hiss /request ~ %httr %purl (need (de-purl:html target))]

141```

142

143> Remember, we are expected to produce a *list* of moves. Note the `~` after the move in the full example. This is a convenient shortcut for creating a list of a single element. It's part of a small family of such shortcuts. `~[a b c]` is `[a b c ~]`, `[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`. These may be mixed and matched to create various convoluted structures and emojis.

144

145The correspondence between this move and `[bone card]` can be hard to

146visualize on one line. Here it is more pedantically:

147

148```

149:* bone=ost.hid :: the move

150 term=%hiss

151 wire=/request

152 unit-iden=~

153 mark=%httr

154 cage=[%purl (need (de-purl:html target))]

155==