This documents contains practical examples of a number of Jael's tasks.

General documentation of the tasks demonstrated here can be found in the API Reference document, and details of the data types mentioned can be found in the Data Types document.

%private-keys

Here we'll look at subscribing to private key updates from Jael. We'll use a thread to pass Jael a %private-keys task, take the %private-keys gift it returns, debug print it to the terminal and finally unsubscribe with a %nuke task.

sub-priv.hoon

/-  spider
/+  strandio
=,  strand=strand:spider
=,  card=card:agent:gall
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
;<  ~  bind:m  (send-raw-card:strandio %pass /sub-priv %arvo %j %private-keys ~)
;<  res=[=wire =sign-arvo]  bind:m  take-sign-arvo:strandio
?>  ?=([%sub-priv ~] wire.res)
?>  ?=([%jael *] sign-arvo.res)
~&  +.sign-arvo.res
;<  ~  bind:m  (send-raw-card:strandio %pass /sub-priv %arvo %j %nuke ~)
(pure:m !>(~))

Save the above thread in the /ted directory of your %base desk and |commit %base.

Now let's run the thread:

> -sub-priv

You should see the %private-key gift it returns in the Dojo:

[ %private-keys
  life=1
    vein
  { [ p=1
        q
      1.729.646.917.183.337.[...truncated for brevity]
    ]
  }
]

At this point our thread unsubscribes again with a %nuke task but without that it would send a new %private-key gift each time the private keys were changed.

%public-keys and %nuke

Here we'll look at both subscribing and unsubscribing to updates of a ship's public keys in Jael. We'll subscribe by sending Jael a %public-keys task, take the %public-keys gift it responds with, print it to the terminal, scry for the set of ducts subscribed to the ship in question, print them to the terminal, and finally send Jael a %nuke task to unsubscribe.

Here's a thread that performs these actions:

sub-pub.hoon

/-  spider
/+  strandio
=,  strand=strand:spider
=,  card=card:agent:gall
=>
|%
+$  subs
  $:  yen=(jug duct ship)
      ney=(jug ship duct)
      nel=(set duct)
  ==
--
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
=/  =@p  (need !<((unit @p) arg))
::
::  sub to public updates for specified ship
=/  c1=card  [%pass /sub-pubkeys %arvo %j %public-keys (silt ~[p])]
;<  ~  bind:m  (send-raw-card:strandio c1)
::
::  take response from jael & print it
;<  res=[=wire =sign-arvo]  bind:m  take-sign-arvo:strandio
?>  ?=([%sub-pubkeys ~] wire.res)
?>  ?=([%jael %public-keys *] sign-arvo.res)
~&  +.sign-arvo.res
::
::  scry for tracking subs for specified ship in jael & print
;<  =subs  bind:m  (scry:strandio ,subs /j/subscriptions/1)
=/  ducts=(set duct)  (~(get ju ney.subs) p)
~&  ducts
::
::  unsub from public updates for specified ships
=/  c2=card  [%pass /sub-pubkeys %arvo %j %nuke (silt ~[p])]
;<  ~  bind:m  (send-raw-card:strandio c2)
(pure:m !>(~))

Note this example was performed on a comet as a fake ship won't have the required information in Jael.

Save the above thread in the /ted directory and |commit %base. The thread takes a ship as an argument, so we'll try to subscribe to pubkey updates for ~dopzod. Let's run the thread:

> -sub-pub ~dopzod

It first passes a %public-keys task to Jael that looks like [%public-keys (silt ~[~dopzod])] in order to subscribe. Jael will immediately respond with a %public-keys gift that contains a %full $public-keys-result. The (map ship point) contained will (for each ship specified in the task) include the current pubkeys for the ship's current life as well as previous keys for previous lifes. It thus contains a complete record of keys up to the present for each ship. Our thread will print these out to the terminal like so:

[ %public-keys
    public-keys-result
  [ %full
      points
    { [ p=~dopzod
          q
        [ rift=2
          life=3
            keys
          { [ p=1
                q
              [ crypto-suite=1
                  pass
                939.529.329.928[...truncated for brevity...]
              ]
            ]
            [ p=2
                q
              [ crypto-suite=1
                  pass
                2.215.774.809.906.200.376.0[...truncated for brevity...]
              ]
            ]
            [ p=3
                q
              [ crypto-suite=1
                  pass
                707.070.568.606.374.[...truncated for brevity...]
              ]
            ]
          }
          sponsor=~
        ]
      ]
    }
  ]
]

Along with giving us the current information, Jael will also subscribe us to any future updates for the ships in question. Such updates will come as additional %public-keys gifts, but rather than a %full public-keys-result, they'll instead contain either a %diff or %breach public-keys-result, depending on what's happened to the ship in question. It's difficult to simulate such events for demonstrative purposes so an example is not included, but you can look at the $public-keys-result to get an idea.

Jael maintains a (jug duct ship) and its reverse (jug ship duct) in its state to track subscriptions. If we do a subscriptions scry and filter the result for ~dopzod, we can see the duct of our thread has now been added to the ~dopzod set. Our thread does this, and will output something like:

{~[/gall/use/spider/0w1.vGVi-/~sampel-palnet/thread/~.dojo_0v6.0hlak.dam1b.bcdou.ai7gq.19fi8/sub-pubkeys /dill //term/1]}

At this point our thread will send a %nuke task like [%nuke (silt ~[~dopzod])] to cancel our subscription. Jael doesn't respond to it, but now, with our thread having finished and exited, we can again scry & filter for subscriptions to ~dopzod:

> =/(a .^([yen=(jug duct ship) ney=(jug ship duct) nel=(set duct)] %j /=subscriptions=/1) (~(get ju ney.a) ~dopzod))
~

As you can see the set is now empty, so we know the %nuke succeeded and Jael will no longer send us pubkey updates for ~dopzod. One thing to note about %nuke is that it must come from the same duct as the original subscription. You can't unsubscribe another app, ship, thread or what have you, so if we'd tried %nukeing the subscription from a separate thread it wouldn't have worked.

%turf

Here we'll look at using a %turf task to get Jael's list of domains. Note on a fake ship the list will be empty, so you may with to run it on a comet or moon.

Here's a simple thread that'll pass Jael a %turf task, take the %turf gift it sends back and print it to the terminal:

turf.hoon

/-  spider
/+  strandio
=,  strand=strand:spider
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
=/  =task:jael  [%turf ~]
=/  =card:agent:gall  [%pass /get-domains %arvo %j task]
;<  ~  bind:m  (send-raw-card:strandio card)
;<  resp=[=wire =sign-arvo]  bind:m  take-sign-arvo:strandio
?>  ?=([%get-domains ~] wire.resp)
?>  ?=([%jael %turf *] sign-arvo.resp)
~&  +.sign-arvo.resp
(pure:m !>(~))

Save in in the /ted directory of your ship and |commit %base. Next, let's try running it:

> -turf
[%turf turf=~[<|org urbit|>]]

As you see, the %turf gift contains urbit.org as ~['org' 'urbit'].

%step

Here we'll look at changing the web login code with a %step task.

First, let's see the current step with a %step scry:

> .^(@ud %j /=step=/(scot %p our))
0

...and the current code with the +code generator:

> +code
lidlut-tabwed-pillex-ridrup

Now, let's pass Jael a %step task by using |pass in the dojo:

> |pass [%j %step ~]

Jael will pass Eyre a %code-changed task:eyre to let Eyre know the code's changed so you'll see a message from Eyre in the terminal:

eyre: code-changed: throwing away cookies and sessions

Now let's again scry for the step and see that it's been incremented:

> .^(@ud %j /=step=/(scot %p our))
1

And finally, let's again run +code and see there's now a new web login code:

> +code
raldev-topnul-mirnut-lablut