pico-engine 1.9.4 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,47 @@
1
+ # Querying another pico
2
+
3
+ To call a function another pico's ruleset shares, use `wrangler:picoQuery`. Two things are needed: a channel to the other pico whose query policy allows that function, and `io.picolabs.wrangler` as a module.
4
+
5
+ ```krl
6
+ meta {
7
+ use module io.picolabs.wrangler alias wrangler
8
+ }
9
+ ```
10
+
11
+ ```krl
12
+ rule ask_the_other_pico {
13
+ select when example question_asked
14
+ pre {
15
+ answer = wrangler:picoQuery(other_eci, "my.ruleset.id", "myFunction", {"arg1": "a", "arg2": "b"})
16
+ }
17
+ if answer{"error"}.isnull() then noop()
18
+ fired {
19
+ ent:last_answer := answer
20
+ }
21
+ }
22
+ ```
23
+
24
+ On the same engine, `picoQuery` calls the other pico directly. On another engine, or for a `did:` identifier, it goes over HTTP or DIDComm. Either way it returns the function's value, or a map with an `error` key if something went wrong.
25
+
26
+ ## Which channel
27
+
28
+ - **Your children.** `wrangler:children()` gives each child's family channel (`eci`). `picoQuery` can use it, because the parent owns it.
29
+ - **Picos you have a relationship with.** Use the relationship: `subscription:queryOnSub(Id, rid, name, args)` (see the [Two picos talking](/cookbook/two_picos/) demo), or `picoQuery` on the relationship's `Tx` channel.
30
+ - **Anyone else.** A channel they give you, made for the purpose, with a policy that allows the functions you need.
31
+
32
+ ## Don't query yourself
33
+
34
+ A pico handles one thing at a time. A query from a pico to itself would wait behind the work that's making it. `picoQuery` refuses: it returns `{"status_code": 400, ...}` with the error "Pico should not query itself". To use a function in another ruleset on the same pico, use that ruleset as a module instead.
35
+
36
+ ## With `http:get`
37
+
38
+ A pico has a URL, so `http:get` works too:
39
+
40
+ ```krl
41
+ response = http:get(meta:host + "/sky/cloud/" + other_eci + "/my.ruleset.id/myFunction", {"arg1": "a"})
42
+ answer = response{"content"}.decode()
43
+ ```
44
+
45
+ It's slower than `picoQuery` on the same engine, and it can't use family channels: the answer is an error, "This is a family channel and only the owner can use it". The HTTP status is still 200 in that case, so check the content for `error`, not just `status_code`.
46
+
47
+ *From the Pico Labs KRL Cookbook page "Accessing a Function Shared by Another Pico".*
@@ -0,0 +1,36 @@
1
+ # One pico per resource
2
+
3
+ Some things should be used by only one party at a time: a motor, a GPIO pin, a printer, an account with an outside service. Give each one its own pico. Everything else asks that pico, by event, to use the resource. Because a pico handles one event at a time, its rulesets are the only code that touches the resource, and requests can't collide.
4
+
5
+ A Pico Labs rover project did this with its wheels. Each of four wheel picos kept the index of the one motor it drove, and only its rules called the motor driver:
6
+
7
+ ```krl
8
+ rule set_motor_index {
9
+ select when rover motor_index_assigned
10
+ always {
11
+ ent:motor_index := event:attr("motor_index")
12
+ }
13
+ }
14
+ ```
15
+
16
+ A controller pico had a channel to each wheel. To move, it sent each wheel the direction that wheel should turn:
17
+
18
+ ```krl
19
+ to_wheels = defaction(type, fr, fl, br, bl) {
20
+ every {
21
+ event:send({"eci": ent:wheels{"FR"}, "domain": "rover", "type": type, "attrs": fr})
22
+ event:send({"eci": ent:wheels{"FL"}, "domain": "rover", "type": type, "attrs": fl})
23
+ event:send({"eci": ent:wheels{"BR"}, "domain": "rover", "type": type, "attrs": br})
24
+ event:send({"eci": ent:wheels{"BL"}, "domain": "rover", "type": type, "attrs": bl})
25
+ }
26
+ }
27
+ forward = defaction() {
28
+ to_wheels("run", {"direction": "fwd"}, {"direction": "back"}, {"direction": "back"}, {"direction": "fwd"})
29
+ }
30
+ ```
31
+
32
+ The controller could have driven the motors itself. But then every new pico that needed the wheels would need the motor code too, and two of them could drive the same motor at once. With a pico per wheel, any number of controllers can share the wheels safely.
33
+
34
+ Keep the channels to the resource picos in relationships (or, for children, in their family channels), not in ECIs written into the code. The original rover hard-coded them, and noted that relationships would be much better.
35
+
36
+ *From the Pico Labs KRL Cookbook page "Singleton Pattern".*
@@ -0,0 +1,67 @@
1
+ # Importing tables and CSV
2
+
3
+ Data exported from a spreadsheet or another system usually arrives as text: tab-separated (TSV) or comma-separated (CSV) lines. If the other system can export JSON, use that instead. `decode()` turns a JSON string into KRL data in one step.
4
+
5
+ ## Lines
6
+
7
+ Exports end lines with `\n` or, from Windows, `\r\n`. One regular expression handles both:
8
+
9
+ ```krl
10
+ lineBreak = re#\r?\n#
11
+ lines = content.split(lineBreak).filter(function(s) { s })
12
+ ```
13
+
14
+ `filter(function(s) { s })` drops empty lines: an empty string is falsy, and there is usually one after the last line break. Another way is to let a global regular expression find the lines: `content.extract(re#(.+)#g)`.
15
+
16
+ ## A table to an array of maps
17
+
18
+ When the first row names the columns, make each data row a map:
19
+
20
+ ```krl
21
+ tsv = function(content) {
22
+ lines = content.split(re#\r?\n#).filter(function(s) { s })
23
+ keys = lines.head().split(re#\t#)
24
+ lines.tail().map(function(line) {
25
+ values = line.split(re#\t#)
26
+ keys.reduce(function(m, k, i) { m.put(k, values[i]) }, {})
27
+ })
28
+ }
29
+ ```
30
+
31
+ Given
32
+
33
+ ```
34
+ A B
35
+ 1 2
36
+ 3 4
37
+ ```
38
+
39
+ `tsv(content)` is `[{"A": "1", "B": "2"}, {"A": "3", "B": "4"}]`. The `reduce` passes each key's index as its third argument, which picks the matching value.
40
+
41
+ ## CSV with a known shape
42
+
43
+ CSV is harder, because a value that contains a comma is wrapped in double quotes. When you know what each line looks like, match the whole line with a regular expression and let the last group take the rest:
44
+
45
+ ```krl
46
+ graduands = function(content) {
47
+ content.extract(re#(.+)#g)
48
+ .tail()
49
+ .map(function(line) { line.extract(re#^([\w ]+),(\w+),(\d+),(\d+),(.*)$#) })
50
+ }
51
+ ```
52
+
53
+ `Ada Lovelace,AL,1,1843,"Notes, on the engine"` becomes `["Ada Lovelace", "AL", "1", "1843", "\"Notes, on the engine\""]`. Strip the quotes from that last field if you need to. `tail()` skips the header line.
54
+
55
+ ## Fetch the file
56
+
57
+ Rather than passing a whole file to a function, give it a URL:
58
+
59
+ ```krl
60
+ import = function(url) {
61
+ tsv(http:get(url){"content"})
62
+ }
63
+ ```
64
+
65
+ A function that calls `http:get` runs on every query, so for a large file, import it once in a rule and store the result in an entity variable.
66
+
67
+ *From the Pico Labs KRL Cookbook pages "Converting a table to an Array of Maps" and "Importing data from other systems".*
@@ -0,0 +1,251 @@
1
+ # Tips
2
+
3
+ Practical notes for running the engine and writing KRL. Engine setup is below; technique pages (from the old Patterns and tips / KRL Cookbook) are indexed further down. The [operator guide](/pico-engine) is the full configuration reference.
4
+
5
+ ## Managing your engine
6
+
7
+ ### Install, update, and check the version
8
+
9
+ ```sh
10
+ npm install -g pico-engine # install, or update to the latest
11
+ npm install -g pico-engine@<version> # a specific version
12
+ pico-engine # run it (port 3000 by default)
13
+ pico-engine --version # which version is this?
14
+ npm ls -g --depth 0 pico-engine # what npm has installed
15
+ ```
16
+
17
+ Back up your data directory (`~/.pico-engine` by default) before you update, and especially before you *downgrade*. A different engine version may not read what a newer one wrote.
18
+
19
+ The version also appears at the bottom of the developer UI's root page.
20
+
21
+ <img src="/developing/_media/31544297-version.png" alt="The developer UI footer: Powered by pico-engine, with the version number" width="50%">
22
+
23
+ To remove the engine code (not your picos, which live in the data directory):
24
+
25
+ ```sh
26
+ npm rm -g pico-engine
27
+ ```
28
+
29
+ ### Start over
30
+
31
+ The engine keeps everything in its data directory, `PICO_ENGINE_HOME`, which defaults to `~/.pico-engine`:
32
+
33
+ | Folder | What's in it |
34
+ |--------|--------------|
35
+ | `db/` | Picos, channels, users, identity |
36
+ | `rulesets-db/` | Which URL each ruleset came from (rebuildable) |
37
+ | `rulesets/` | Compiled rulesets (rebuildable) |
38
+
39
+ To wipe all picos and begin with a fresh engine, stop the engine and delete the data directory. You then register a new passkey on your next visit, and get a new root pico:
40
+
41
+ ```sh
42
+ rm -r ~/.pico-engine
43
+ ```
44
+
45
+ > **There is no undo.** Deleting `db/` deletes your picos. Deleting only `rulesets-db/` and `rulesets/` is harmless: they're rebuilt when rulesets are installed again. Adjust the path if you set `PICO_ENGINE_HOME` to somewhere else.
46
+
47
+ ### Keep separate projects apart
48
+
49
+ The data directory is an *image* of the engine's state: all its picos and rulesets. Point `PICO_ENGINE_HOME` at different directories to keep projects separate, and return to where you left off in each:
50
+
51
+ ```sh
52
+ PICO_ENGINE_HOME=~/.game_image pico-engine
53
+ PICO_ENGINE_HOME=~/.iot_image pico-engine
54
+ ```
55
+
56
+ ### Run more than one engine
57
+
58
+ To run several engines on one machine at once, give each its own port, its own data directory, and the matching public URL:
59
+
60
+ ```sh
61
+ PORT=3001 PICO_ENGINE_HOME=~/.pico-engine-1 pico-engine
62
+ ```
63
+
64
+ Never point two running engines at the same data directory. Engines can also be configured with a config file per process (`pico-engine -c file.json`). See [Multiple engines on one host](/pico-engine#multiple-engines-on-one-host).
65
+
66
+ ### The base URL
67
+
68
+ The engine knows its own address, `http://localhost:3000` by default, and gives it to your KRL as `meta:host` (and uses it to build links). To use another address, such as a machine's name or a public domain, set `PICO_ENGINE_BASE_URL`:
69
+
70
+ ```sh
71
+ PICO_ENGINE_BASE_URL=http://my-machine.local:3000 pico-engine
72
+ ```
73
+
74
+ This is also what passkeys are bound to: the browser's passkey only works at the address the engine thinks it has. If you open the engine from a different host name than the one you registered with, sign-in fails; see `webauthn` in the operator guide.
75
+
76
+ The engine reads the address once, at startup. TLS isn't terminated by the engine, so for HTTPS put a reverse proxy in front of it and set the base URL to the public HTTPS address.
77
+
78
+ ### Docker
79
+
80
+ There's an official image, `picolabs/pico-engine`. Mount a volume for the data directory and set the same variables you'd set for the command line:
81
+
82
+ ```sh
83
+ docker run -p 3001:3000 \
84
+ -v ~/images/pico-image:/var/pico-image \
85
+ -e PICO_ENGINE_HOME=/var/pico-image \
86
+ -e PICO_ENGINE_BASE_URL=http://localhost:3001 \
87
+ picolabs/pico-engine:<version>
88
+ ```
89
+
90
+ You can run the image several times with different ports and volumes to get several independent engines. Don't share one volume between running containers. The package README covers Docker Compose and AWS Fargate with EFS.
91
+
92
+ ### Windows
93
+
94
+ WSL 2 (a Linux environment on Windows) is a good way to run the engine on Windows. If a browser on Windows can't reach an engine running in WSL 2, the usual culprit is bridging the port between Windows and the virtual machine. Also check that the base URL matches the address the browser uses.
95
+
96
+ ## Hosting, flushing, and checking rulesets
97
+
98
+ ### Host the source where the engine can reach it
99
+
100
+ The engine installs a ruleset from a URL and remembers it:
101
+
102
+ - **Your own files**, while you work: `file:///path/to/my.ruleset.krl` (three slashes). The engine must be on the same machine.
103
+ - **GitHub:** use the *raw* URL, `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>.krl`, not the page that displays the file. GitHub caches raw files for a few minutes. For a private repository the engine needs a URL that includes an access token.
104
+ - **The engine's own:** `http://<engine>/krl/<rid>.krl` for rulesets that ship with it, and `/krl/demos/...` for demos.
105
+ - **S3 or any static host:** make sure the URL is readable by the engine.
106
+
107
+ ### Flush after every change
108
+
109
+ The engine compiles each ruleset once and caches it. After you change the source, flush it so the engine fetches and compiles it again:
110
+
111
+ - **From the UI.** On the pico's **Rulesets** tab, click **flush** next to the ruleset.
112
+ - **From a rule.** `raise wrangler event "rulesets_need_flushing"` re-fetches every ruleset installed in the pico and then raises `wrangler:rulesets_flushed`.
113
+
114
+ <img src="/developing/_media/31544297-flush.png" alt="The Rulesets tab with hello_world installed, and its flush and uninstall buttons" width="50%">
115
+
116
+ If the changed source doesn't compile, the flush fails and the error appears next to the ruleset:
117
+
118
+ <img src="/developing/_media/31544297-flush-error.png" alt="The Rulesets tab showing a ParseError next to hello_world after a flush" width="50%">
119
+
120
+ Flushing is by URL. The engine keeps one compiled version per URL, so every pico with that ruleset gets the update. Flushing does **not** raise `wrangler:ruleset_installed` again, so rules that run on install don't run. If you change what such a rule sets up (for example a channel's policy), run that rule again yourself. The [Bootstrap and channels](/cookbook/bootstrap/) demo shows how.
121
+
122
+ The UI uses `/api/flush?url=<ruleset url>`, which needs the signed-in browser session, so it doesn't work from a plain `curl`; use the UI or the wrangler event instead.
123
+
124
+ ### Check your KRL before the engine sees it
125
+
126
+ ```sh
127
+ npm install -g krl-compiler
128
+ krl-check my.ruleset.krl
129
+ ```
130
+
131
+ `krl-check` parses and compiles, and lints doc comments and views. It exits with status 1 on an error and prints warnings to stderr. With no file, it reads standard input. Keep `krl-compiler` at the same version as your engine.
132
+
133
+ <img src="/developing/_media/31544297-screen-shot-2020-11-16-at-11.31.18-am.png" alt="Editor with krl-check validation output before flushing a ruleset" width="50%">
134
+
135
+ A Git pre-commit hook that checks the *staged* version of each `.krl` file:
136
+
137
+ ```sh
138
+ #!/bin/sh
139
+ status=0
140
+ for f in $(git diff --cached --name-only --diff-filter=ACM -- '*.krl'); do
141
+ if ! git show ":$f" | krl-check >/dev/null; then
142
+ echo "krl-check failed: $f"
143
+ status=1
144
+ fi
145
+ done
146
+ exit $status
147
+ ```
148
+
149
+ Save it as `.git/hooks/pre-commit` and make it executable. `git show ":$f"` is the staged copy, so a fix you haven't staged yet doesn't hide an error. See also [Programming Workflow](/developing/workflow).
150
+
151
+ ## Writing and debugging
152
+
153
+ ### Use the Testing and Logging tabs
154
+
155
+ - The **Testing** tab builds a form for each event and query a ruleset offers, using the ruleset's doc comments (`@attr`, `@param`, `@example`). Document your rules and shared functions and the forms write themselves.
156
+ - The **Logging** tab shows what the pico did for each event or query: the channel and its policy decision, the attributes, which rules were selected and which fired, directives, raised events, and `klog` output. Use the filters to narrow it to a ruleset, an event, or errors. It keeps recent transactions per pico in memory (200 by default, `PICO_ENGINE_LOG_RING`), so a restart clears it. The log file on disk keeps the full record; see [Reading the engine's log files](/developing/engine-log-files).
157
+ - `.klog("label: ")` returns the value it's applied to, so you can add it in the middle of an expression without changing the code.
158
+
159
+ ### "Not allowed by channel policy"
160
+
161
+ This is the most common surprise when calling a pico from outside. The channel you used doesn't permit that event or query. Try another channel on the **Channels** tab, or give the channel a policy that allows what you need. See [Managing channels](/wrangler/channels).
162
+
163
+ ### Initialize a ruleset when it's installed
164
+
165
+ Rulesets often need setup: default values for entity variables, a scheduled event, a channel. Wrangler raises `wrangler:ruleset_installed` when a ruleset is installed in a pico, and a rule in your ruleset can select on that event. Always check that the ruleset that was installed is yours, or the rule runs every time *any* ruleset is installed:
166
+
167
+ ```krl
168
+ rule initialize_ruleset {
169
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
170
+ if ent:heartbeat_period.isnull() then noop()
171
+ fired {
172
+ ent:heartbeat_period := event:attr("heartbeat_period") || 60;
173
+ ent:emitter_state := "running"
174
+ }
175
+ }
176
+ ```
177
+
178
+ Two cautions:
179
+
180
+ - The event isn't raised again on a flush, so a change to this rule's setup doesn't take effect on picos that already have the ruleset.
181
+ - Guard each initialization with `isnull()` so you never overwrite state that has accumulated.
182
+
183
+ More: [Initializing entity variables](/developing/initializing-entity-variables) and [Bootstrap and channels](/cookbook/bootstrap/).
184
+
185
+ ### Wrangler, not `ctx`, in application rulesets
186
+
187
+ For children, channels, ruleset installation, and queries between picos, use wrangler's events and functions (`wrangler:new_child_request`, `wrangler:picoQuery`, and so on). The engine's lower-level `ctx:*` actions exist for wrangler and the platform to use. See [Wrangler](/wrangler/).
188
+
189
+ ## Technique tips
190
+
191
+ Short techniques for writing KRL and working with picos, checked against this engine. For runnable examples, see the [Cookbook](/cookbook/) and the **Try It!** tab. Event and query URLs live in the [Event Exchange Protocol](/exp/).
192
+
193
+ ### Working with data
194
+
195
+ | Page | What it covers |
196
+ |------|----------------|
197
+ | [Initializing entity variables](/developing/initializing-entity-variables) | `defaultsTo`, a guard rule, or a rule that runs on install |
198
+ | [Arrays and maps](/developing/arrays-and-maps) | Loops with `reduce`, flattening, and sorting arrays of maps by one key or two |
199
+ | [Decoding form-encoded data](/developing/decoding-form-data) | Turning `a=1&b=2` into a map, keeping repeated names, and decoding `+` and `%xx` |
200
+ | [Importing tables and CSV](/developing/tabular-data) | Tab- and comma-separated exports to arrays and maps, fetched with `http:get` |
201
+ | [Converting time formats](/developing/converting-time-formats) | RSS (RFC 2822) dates to the RFC 3339 form the time library uses |
202
+ | [What's in a name?](/developing/names-and-scope) | KRL's separate kinds of names, and how a `pre` declaration shadows a global |
203
+
204
+ ### HTTP and the outside world
205
+
206
+ | Page | What it covers |
207
+ |------|----------------|
208
+ | [Cookies and redirects](/developing/cookies-and-redirects) | The `_cookie` and `_redirect` directives, reading cookies, and a URL shortener |
209
+ | [Events from email](/developing/events-from-email) | A mail webhook to an event, routing by address, and turning message lines into events |
210
+ | [Reading the engine's log files](/developing/engine-log-files) | Where the logs are, how they rotate, and one pico's history with `grep` and `jq` |
211
+ | [Event and Query URLs with Postman](/developing/postman) | Building Sky requests in Postman or `curl` |
212
+
213
+ ### Picos working together
214
+
215
+ | Page | What it covers |
216
+ |------|----------------|
217
+ | [Querying another pico](/developing/querying-another-pico) | `wrangler:picoQuery`, which channel to use, why a pico can't query itself, and `http:get` |
218
+ | [Accepting relationship requests](/developing/accepting-relationship-requests) | An approving rule, wrangler's auto-accept configuration, and a ruleset that accepts later and removes itself |
219
+ | [One pico per resource](/developing/singleton-picos) | Giving a device or account its own pico, so requests can't collide |
220
+
221
+ ### Patterns that became demos
222
+
223
+ | Pattern | Demo |
224
+ |---------|------|
225
+ | Idempotency and guard rules; authorize, then use | [Guard rules](/cookbook/guard_rules/) |
226
+ | Splitting rules for clarity and extensibility; layering functionality with rulesets; semantic translation | [Layered rulesets](/cookbook/layered_rulesets/) |
227
+ | Collection picos | [Collection](/cookbook/collection/) |
228
+ | Access tokens and other secrets; keeping keys safe | [Configuration and secrets](/cookbook/secrets/) |
229
+ | Installing a multi-ruleset application; creating a channel for a ruleset | [Bootstrap and channels](/cookbook/bootstrap/) |
230
+ | An echo server | [Echo](/cookbook/echo/) |
231
+ | A score tracker | [Score tracker](/cookbook/score_tracker/) |
232
+ | A child pico for an asynchronous task | [Child pico tasks](/cookbook/child_tasks/) |
233
+ | Automatic replies to relationship requests; querying over a relationship | [Two picos talking](/cookbook/two_picos/) |
234
+ | An event hierarchy across rulesets | [KBlog](/cookbook/kblog/) |
235
+
236
+ ### In the KRL manual
237
+
238
+ - [Persistent variables](/krl/persistent-variables/)
239
+ - [User-defined actions](/krl/krl-expression-language/user-defined-actions)
240
+
241
+ ### Left out of the old cookbook
242
+
243
+ - **Sending secure messages** used `engine:signChannelMessage` and its relatives, which are gone. Relationships can use DIDComm; see [Relationships](/wrangler/relationships).
244
+ - **Shorter URL for a query or event** used `io.picolabs.rewrite` on the root pico, removed in engine 1.0. A ruleset can do the same with `_redirect`: see [Cookies and redirects](/developing/cookies-and-redirects).
245
+ - **Account management using the root pico** described owner picos from before engine 1.0.
246
+ - **Generate an image with KRL**, **Using Foursquare data**, **Using Wovyn sensors**, **Using Git**, and **Using a Google sheet** are about particular services rather than KRL.
247
+ - **Proposals, experiments, and proofs of concept** were experiments on earlier engines.
248
+
249
+ ---
250
+
251
+ <small>Merges the [Developer Tips](https://picolabs.atlassian.net/wiki/spaces/docs/pages/31544297) wiki page (last edited there 2021-04-12) with the Patterns and tips / KRL Cookbook pages that still apply, updated for this engine.</small>
@@ -0,0 +1,56 @@
1
+ # Webhook signatures
2
+
3
+ A webhook such as Square's is an HTTP event. The sender signs the exact bytes of the body. The parsed attributes are not those bytes: a space or the order of keys would change the signature. The channel has to keep the raw body, and the comparison has to take the same time whether or not it matches.
4
+
5
+ ## Keep the raw body
6
+
7
+ On the Channels tab, check **Keep the raw request body**. From KRL, pass `rawBody: true` when the channel is created:
8
+
9
+ ```krl
10
+ raise wrangler event "new_channel_request" attributes {
11
+ "tags": ["square", "webhook"],
12
+ "eventPolicy": { "allow": [{ "domain": "square", "name": "webhook" }], "deny": [] },
13
+ "queryPolicy": { "allow": [], "deny": [] },
14
+ "rawBody": true
15
+ }
16
+ ```
17
+
18
+ `event:raw_body()` then returns the body as a string. On a channel without that setting it returns `null`, and so does `event:send` or a scheduled event. The body is not an attribute. Storing `event:attrs` does not store it. A rule that raises another event in the same transaction can still read it.
19
+
20
+ ## The signing key
21
+
22
+ Keep the key in the ruleset's own PDS settings and mark it secret. `settings` then returns `{ "secret": true, "set": true }`. The ruleset reads the key with `pds:config_value("signatureKey")`. See [PDS settings](/wrangler/pds).
23
+
24
+ ## Square
25
+
26
+ Square's `x-square-hmacsha256-signature` header is the base64 HMAC-SHA256 of the notification URL concatenated with the raw body, using the webhook signature key. The URL is the one configured in Square, exactly, not whatever host the request happened to arrive on. Header names on the event are lowercase.
27
+
28
+ ```krl
29
+ ruleset com.example.square_webhook {
30
+ meta {
31
+ use module io.picolabs.pds alias pds
32
+ shares verdict
33
+ }
34
+ global {
35
+ notification_url = "https://example.com/sky/event/<eci>/none/square/webhook"
36
+ verdict = function() { ent:verdict || "none" }
37
+ }
38
+ rule verify {
39
+ select when square webhook
40
+ pre {
41
+ key = pds:config_value("signatureKey")
42
+ body = event:raw_body()
43
+ given = event:attr("_headers"){"x-square-hmacsha256-signature"}.defaultsTo("")
44
+ ready = body.typeof() == "String" && key.typeof() == "String"
45
+ expected = ready => math:hmac("sha256", key, notification_url + body, "base64") | ""
46
+ ok = ready && math:timing_safe_equal(expected, given)
47
+ }
48
+ noop()
49
+ fired {
50
+ ent:verdict := ok => "accepted" | "rejected"
51
+ }
52
+ }
53
+ }
54
+ ```
55
+
56
+ `math:timing_safe_equal` compares the two strings without stopping at the first different byte. Use it instead of `==` for the signature. `math:hmac` is described in the [math library](/krl/libraries/math).
@@ -0,0 +1,106 @@
1
+ # Programming Workflow
2
+
3
+ A suggested workflow for new pico developers. Programming picos uses a small tool chain, used more or less in sequence. This page is organized by its stages:
4
+
5
+ <img src="/developing/_media/32754595-pico-tool-chain.png" alt="The pico tool chain: Develop (editor, Git), Build (Pico Labs, Git), Deploy and Test (Pico Labs), Release (AWS, GitHub)" width="50%">
6
+
7
+ The loop you'll spend most of your time in is Develop → Build → Deploy (flush) → Test. Release only matters when someone other than you depends on the ruleset.
8
+
9
+ ## Develop
10
+
11
+ Use Git (or any version control) and your favorite editor. A KRL ruleset is a plain text file, by convention named after its ruleset id with a `.krl` extension.
12
+
13
+ ```sh
14
+ mkdir myproject
15
+ cd myproject
16
+ git init
17
+ ```
18
+
19
+ Create a ruleset file in the repository, for example `io.picolabs.hello_world.krl`. Editors don't need special support, but KRL is close enough to JavaScript that syntax highlighting for JavaScript is a reasonable fallback.
20
+
21
+ Write `/** … */` doc comments on your rules and shared functions, using the `@attr`, `@param`, and `@example` tags. The compiler turns them into the ruleset's *schema*, which the **Testing** tab uses to build forms. They don't change what the ruleset does. The [Quickstart](/lessons/quickstart) shows an example.
22
+
23
+ ## Build
24
+
25
+ "Building" a ruleset means making sure it parses and compiles. Use `krl-check`, which ships with `krl-compiler`:
26
+
27
+ ```sh
28
+ npm install -g krl-compiler
29
+ krl-check my.ruleset.krl
30
+ ```
31
+
32
+ `krl-check` parses and compiles the file, and also lints doc comments and views. It exits with status 1 when there is an error, and prints warnings to stderr. With no file argument it reads standard input. `--json` prints a machine-readable result.
33
+
34
+ > **Note:** `krl-check` replaces the old parse-only hook scripts (`krl-compiler --verify`, and the hooks built on the old parser). If you still have one of those in a repository, replace it.
35
+
36
+ Run it often, from your editor or a file watcher. To make sure nothing that fails to compile is ever committed, add a Git pre-commit hook. [Tips](/developing/tips) has the hook, and it checks the *staged* version of each file, which is what you want.
37
+
38
+ Then add and commit as usual:
39
+
40
+ ```sh
41
+ git add io.picolabs.hello_world.krl
42
+ git commit -m "initial commit"
43
+ ```
44
+
45
+ With the hook in place, a ruleset that commits is one that compiles. (It doesn't promise the rules do what you want. That's the Test stage.)
46
+
47
+ ## Deploy
48
+
49
+ Deploying means installing the ruleset in each pico that needs it. If it's already installed, you only need to flush it.
50
+
51
+ ### Install
52
+
53
+ Open the developer UI at <http://localhost:3000> (port 3000 is the default), click the pico, and use the **Rulesets** tab's **Install Ruleset by URL** form. You need the ruleset's URL:
54
+
55
+ - **Local file.** While developing on the same machine as the engine, use `file://` followed by the full path. The path starts with a slash, so you end up with three slashes: `file:///Users/you/myproject/io.picolabs.hello_world.krl`. The **Browse…** button stages a *copy* of the file, which is convenient for a first install but is not reread by a later flush; type the `file:///` URL yourself if you want flush to see your edits.
56
+ - **GitHub.** Use the *raw* URL, `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>.krl`, not the page GitHub shows. GitHub caches raw files for a few minutes, so a change you just pushed may not be visible right away.
57
+ - **The engine's own rulesets and demos.** `http://localhost:3000/krl/<rid>.krl` and `/krl/demos/…`.
58
+
59
+ When the engine can't compile the ruleset, the install fails and the UI shows the error with its line and column.
60
+
61
+ <img src="/developing/_media/32754595-screen-shot-2021-01-07-at-11.06.49-am.png" alt="Rulesets tab: Install Ruleset by URL form with a file URL entered" width="50%">
62
+
63
+ ### Flush
64
+
65
+ The engine compiles a ruleset once and keeps the result. After you change the source, **flush** it so the engine fetches the URL and compiles it again. On the **Rulesets** tab, click **flush** next to the ruleset. Flushing is per URL: every pico on this engine that has the ruleset installed from that URL gets the new version. The ruleset's hash changes with each new version of the source.
66
+
67
+ <img src="/developing/_media/32754595-screen-shot-2021-01-07-at-11.26.13-am.png" alt="Installed Rulesets list with flush and uninstall buttons next to each ruleset" width="50%">
68
+
69
+ You can also flush from KRL, which is handy in scripts:
70
+
71
+ ```krl
72
+ raise wrangler event "rulesets_need_flushing"
73
+ ```
74
+
75
+ That re-fetches and recompiles every ruleset installed in the pico, and then raises `wrangler:rulesets_flushed`.
76
+
77
+ Flushing doesn't raise `wrangler:ruleset_installed`, so a rule that initializes the ruleset on install doesn't run again. If you changed what that rule sets up, run it yourself (or reinstall in a fresh pico). If a ruleset doesn't compile, the flush fails with the same kind of error you see on install.
78
+
79
+ ## Test
80
+
81
+ The **Testing** tab sends events and queries to the pico without you building URLs. Choose a channel (ECI) and a ruleset. The forms come from the ruleset's schema, so the doc comments you wrote in the Develop stage become the form fields and presets. The tab keeps a history so you can send the same thing again. See [Events and Queries](/lessons/events-and-queries) for a walk-through.
82
+
83
+ The **Logging** tab is where you find out why a rule did or didn't run. It lists each event and query the pico handled, newest first, with the channel and policy decision, the attributes, which rules were selected and which fired, any `klog` output, the directives returned, and the events the rules raised. Add `klog` to a binding to see a value:
84
+
85
+ ```krl
86
+ my_name = event:attr("name").klog("saw name: ")
87
+ ```
88
+
89
+ For repeatable tests, or to try an event from a script, use `curl` or [Postman](/developing/postman) against the [Event and Query APIs](/exp/).
90
+
91
+ If you run the engine under a different host name or port than `localhost:3000`, remember the browser's passkey is tied to that address (see the operator guide's `baseUrl` and `webauthn` settings). Otherwise you can ignore passkeys in the workflow: you register once, on the first visit.
92
+
93
+ ## Release
94
+
95
+ For local development there is nothing to do beyond Deploy.
96
+
97
+ When others use your ruleset, they need a *stable* version, even while you keep working. Any HTTP server will do:
98
+
99
+ - **GitHub.** Make a Git tag or a GitHub release for each version, and give users the raw URL at that tag (for example `https://raw.githubusercontent.com/<owner>/<repo>/v1.2.0/<path>.krl`). Keep `master` for work in progress.
100
+ - **Object storage such as S3.** Use a directory per release. Make sure the engine can read the URL.
101
+
102
+ Users install from that URL. A flush rereads the same URL, so a tagged URL stays put until they choose a new one.
103
+
104
+ ---
105
+
106
+ <small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/32754595) (last edited there 2021-01-07), and updated for this engine.</small>
@@ -0,0 +1,46 @@
1
+ # Event Exchange Protocol
2
+
3
+ Picos talk to the outside world over HTTP. The **Event Exchange Protocol** (EXP) is that HTTP surface: raise an event, or ask a query, on a specific [channel](/wrangler/channels). **Sky** is the current version of EXP — the path prefix is `/sky/…`. A later version would keep the same ideas under a new prefix; these pages describe the protocol, and name Sky where the current URLs matter.
4
+
5
+ ## The event-query model
6
+
7
+ The pico API is **not RESTful**. A pico is not a collection of resources you manipulate with GET, POST, PUT, and DELETE. HTTP is only the transport. The shape of the API is closer to [Command Query Separation](https://martinfowler.com/bliki/CommandQuerySeparation.html): one path changes state, another only reads it. There are no "commands" as such — there are **events** — so we call it an **event-query** model.
8
+
9
+ | Kind | What it does | HTTP (Sky) |
10
+ |------|----------------|------------|
11
+ | **Event** | Something happened (or should happen). Rules may fire, change state, raise further events, and answer with directives. | [Event API](/exp/event) — `/sky/event/…` |
12
+ | **Query** | Ask a shared function for a value. No rule selection; the function runs and returns. Queries use a different code path from events and are usually cheaper. | [Query API](/exp/query) — `/sky/query/…` |
13
+
14
+ EXP is also a **meta-API**: it describes the *pattern* for talking to a pico, not a fixed list of operations. Each pico's concrete API is whatever its installed rulesets provide — which events their rules select on, and which functions they list in `shares` — and that can change over the pico's life as rulesets are installed or removed. Salience (from the rules' `select when` expressions) and the shared-function list are how you learn what a given pico will respond to; the developer UI's **Testing** tab and each pico's `discovery` channel surface that.
15
+
16
+ <img src="/exp/_media/1189953-event_query_api.png" alt="Event query model in a pico: the event API feeds rules, the query API reads from functions, both backed by persistent storage" width="50%">
17
+
18
+ A better analogy than REST is a cloud-based persistent object: you send it messages (events) and ask it questions (queries), the same way you would talk to an object in an OO program. In return you get actors that scale by sharding, can live on different engines, and keep the user in control of their data.
19
+
20
+ Picos are not empty vessels for long. New children come with [Wrangler](/wrangler/) and the other platform rulesets already installed, so they already speak EXP. Application rulesets (and frameworks such as Manifold) add a more specific event-query surface and a data schema on top — a vehicle pico, a sensor pico, a community pico — which gives developers leverage without inventing a new HTTP style for each type.
21
+
22
+ ## Channels and authorization
23
+
24
+ An EXP URL always includes an **ECI** (event channel identifier). That one token says which pico and which channel the request is for. The channel's [policy](/wrangler/channels) decides whether the event or query is allowed. On a mesh with [OAuth](/wrangler/oauth) turned on, most `/sky/*` requests also need a bearer token.
25
+
26
+ Both event and query accept GET and POST. POST with a JSON body is preferred when you have attributes or arguments.
27
+
28
+ The same operations exist for the developer UI on `/c/*` (passkey session). Integrators, webhooks, pico views, and Home Assistant use `/sky/*`. A machine-readable subset of the surface is in the [OpenAPI spec](/openapi.yaml).
29
+
30
+ ## Try it
31
+
32
+ - The [Echo](/cookbook/echo/) demo raises events from a page and from `curl`, and shows the directives that come back.
33
+ - The [Querying JSON](/cookbook/json_query/) demo calls a shared function over `/sky/query`.
34
+ - On any pico's **Testing** tab, pick a ruleset and send a documented event or query on a channel you choose.
35
+
36
+ ## See also
37
+
38
+ - [Persistent Compute Objects](/pico-overview) — where the event-query model sits in the pico picture
39
+ - [Managing channels](/wrangler/channels) — ECIs, tags, and policies
40
+ - [Cookies and redirects](/developing/cookies-and-redirects) — `_cookie` and `_redirect` directives on event responses
41
+ - [Pico views](/pico-views) — pages that call EXP from the browser
42
+ - [OAuth](/wrangler/oauth) — when `/sky/*` needs a bearer token
43
+
44
+ ---
45
+
46
+ <small>Ported from the Pico Labs wiki pages [Event Exchange Protocol](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189914/Event+Exchange+Protocol) (2021-02-20) and [Event-Query API](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189953/Event-Query+API) (2021-02-03), and updated for this engine.</small>