@@ -0,0 +1,146 @@
2+title = "Foreign Ships"
7+Here we'll looking at making `clay` requests to a foreign ship.
9+As it currently stands, it's not possible to write to a foreign desk. Additionally, remote scries are not implemented. That leaves requests to read files (`%warp`) and merge desks (`%merg`).
13+- [%warp](#warp) - Read files and directories.
14+- [%merg](#merg) - Merge a foreign desk into a local one.
18+To read files on a foreign desk, you just send clay a `%warp` `task:clay` (as you would for a local read) and specify the target ship in the `wer` field. For details on making such requests, see the [Read and Subscribe](@/docs/arvo/clay/read.md) document.
20+Clay only allows a subset of cares to be used remotely. They are:
22+- `%u` - Check for existence of file.
23+- `%v` - Get entire `dome:clay` state of a desk.
24+- `%w` - Get revision number.
25+- `%x` - Get data of file.
26+- `%y` - Get `arch` of file or directory.
27+- `%z` - Get content hash of file or directory.
29+Any other `care` will crash with a `%clay-bad-foreign-request-care` error.
31+The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details.
33+Note that if you're reading a whole desk or directory, all subfolders and files must also permit reading. If even a single file does not permit you reading it, the foreign ship will not respond to the request.
37+We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.
39+First we'll set permissions on the foreign ship. Here's a simple thread that just sends a task to clay:
41+**`send-clay-task.hoon`**
46+=, strand=strand:spider
51+=/ uarg !< (unit task:clay) arg
53+ (strand-fail:strand %no-arg ~)
55+=/ =card:agent:gall [%pass /foo %arvo %c task]
56+;< ~ bind:m (send-raw-card:strandio card)
60+Create a file called `foo.txt` in the `%home` of ~nes. Save the above thread to `ted/send-clay/task.hoon`, `|commit %home`, and then send a `%perm` request to allow ~zod to read and write the file:
63+> -send-clay-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]
66+If we scry the file for its permissions with a `%p` care, we'll see ~zod is now whitelisted:
69+> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)
70+[r=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]] w=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]]]
73+Next, save the following thread to `ted/send-task-take-gift.hoon` on ~zod:
75+**`send-task-take-gift.hoon`**
80+=, strand=strand:spider
85+=/ uarg !< (unit task:clay) arg
87+ (strand-fail:strand %no-arg ~)
89+=/ =card:agent:gall [%pass /foo %arvo %c task]
90+;< ~ bind:m (send-raw-card:strandio card)
91+;< res=[wire sign-arvo] bind:m take-sign-arvo:strandio
96+`|commit %home`, and send a `%x` read request for `/foo/txt` on ~nes like:
99+> -send-task-take-gift [%warp ~nes %home ~ %sing %x da+now /foo/txt]
103+ [ p=[p=%x q=[%da p=~2021.5.3..08.24.22..9ce7] r=%home]
105+ r=[p=%txt q=[#t/txt=*'' q=[7.303.014 0]]]
111+As you can see, we've received a `%writ` containing the requested data just as we would with a local request. Let's try a `%u`:
114+> -send-task-take-gift [%warp ~nes %home ~ %sing %u da+now /foo/txt]
118+ [ p=[p=%u q=[%da p=~2021.5.3..08.26.32..88cf] r=%home]
120+ r=[p=%flag q=[#t/?(%.y %.n) q=0]]
126+If we send a `%d` request however, it will crash:
129+> -send-receive-task [%warp ~nes %home ~ %sing %d da+now /foo/txt]
131+/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>
133+/sys/vane/clay/hoon:<[1.365 7].[1.365 51]>
134+[ %clay-bad-foreign-request-care
135+ [%sing mood=[care=%d case=[%da p=~2021.5.3..20.04.57..1092] path=/foo/txt]]
137+/sys/vane/clay/hoon:<[1.365 48].[1.365 50]>
142+To merge a foreign desk into a local one, you just send clay a `%merg` `task:clay` (as you would for a local merge) and specify the foreign ship in the `her` field. For details on making such requests, see the [Merge Desks](@/docs/arvo/clay/merge.md) document.
144+The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` desk.
146+Note that all subfolders and individual files within the desk must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.