pico-engine 1.9.5 → 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 (126) hide show
  1. package/README.md +11 -5
  2. package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
  3. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
  4. package/demos/echo/com.example.echo.bootstrap.krl +10 -7
  5. package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
  6. package/demos/json_query/README.md +11 -0
  7. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  8. package/demos/json_query/com.example.json_query.krl +162 -0
  9. package/demos/json_query/try-it.md +5 -0
  10. package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
  11. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
  12. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
  13. package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
  14. package/demos/try-it-order.json +1 -1
  15. package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
  16. package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
  17. package/dist/cli.js +5 -1
  18. package/dist/engineConfig.js +1 -1
  19. package/dist/identity/portableMove.js +5 -1
  20. package/dist/index.js +44 -12
  21. package/dist/internalAccess.js +110 -0
  22. package/dist/oauth/OAuthService.js +172 -10
  23. package/dist/oauth/acg.js +194 -24
  24. package/dist/oauth/cimd.js +381 -0
  25. package/dist/oauth/discovery.js +175 -0
  26. package/dist/runMcp.js +1 -1
  27. package/dist/server.js +197 -48
  28. package/dist/subtreeWrangler.js +8 -5
  29. package/dist/uiChannelPolicies.js +2 -0
  30. package/krl/io.picolabs.pds.krl +109 -21
  31. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  32. package/krl/io.picolabs.wrangler.krl +21 -9
  33. package/mcp/devResources.js +52 -0
  34. package/mcp/devTools.js +40 -9
  35. package/mcp/docs/CLAUDE.md +3 -2
  36. package/mcp/docs/cookbook/README.md +23 -0
  37. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  38. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  39. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  40. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  41. package/mcp/docs/cookbook/collection/README.md +21 -0
  42. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  43. package/mcp/docs/cookbook/echo/README.md +19 -0
  44. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  45. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  46. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  47. package/mcp/docs/cookbook/json_query/README.md +26 -0
  48. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  49. package/mcp/docs/cookbook/kblog/README.md +60 -0
  50. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  51. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  52. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  53. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  54. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  55. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  56. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  57. package/mcp/docs/cookbook/secrets/README.md +25 -0
  58. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  59. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  60. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  61. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  62. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  63. package/mcp/docs/developing/README.md +28 -0
  64. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  65. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  66. package/mcp/docs/developing/converting-time-formats.md +28 -0
  67. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  68. package/mcp/docs/developing/decoding-form-data.md +67 -0
  69. package/mcp/docs/developing/engine-log-files.md +34 -0
  70. package/mcp/docs/developing/event-loop.md +77 -0
  71. package/mcp/docs/developing/events-from-email.md +80 -0
  72. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  73. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  74. package/mcp/docs/developing/misconceptions.md +467 -0
  75. package/mcp/docs/developing/names-and-scope.md +44 -0
  76. package/mcp/docs/developing/postman.md +159 -0
  77. package/mcp/docs/developing/querying-another-pico.md +47 -0
  78. package/mcp/docs/developing/singleton-picos.md +36 -0
  79. package/mcp/docs/developing/tabular-data.md +67 -0
  80. package/mcp/docs/developing/tips.md +251 -0
  81. package/mcp/docs/developing/webhook-signatures.md +56 -0
  82. package/mcp/docs/developing/workflow.md +106 -0
  83. package/mcp/docs/exp/README.md +46 -0
  84. package/mcp/docs/exp/event.md +110 -0
  85. package/mcp/docs/exp/query.md +94 -0
  86. package/mcp/docs/lessons/README.md +59 -0
  87. package/mcp/docs/lessons/events-and-queries.md +247 -0
  88. package/mcp/docs/lessons/gossip.md +28 -0
  89. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  90. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  91. package/mcp/docs/lessons/pico-state.md +267 -0
  92. package/mcp/docs/lessons/pico-views.md +290 -0
  93. package/mcp/docs/lessons/quickstart.md +157 -0
  94. package/mcp/docs/lessons/relationships.md +530 -0
  95. package/mcp/docs/lessons/scatter-gather.md +362 -0
  96. package/mcp/docs/pico-engine.md +7 -5
  97. package/mcp/docs/pico-overview.md +3 -3
  98. package/mcp/docs/wrangler/README.md +47 -0
  99. package/mcp/docs/wrangler/channels.md +235 -0
  100. package/mcp/docs/wrangler/oauth.md +56 -0
  101. package/mcp/docs/wrangler/pds.md +423 -0
  102. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  103. package/mcp/docs/wrangler/relationships.md +297 -0
  104. package/mcp/docs/wrangler/wrangler.md +253 -0
  105. package/mcp/docs/wrangler/xmlui.md +60 -0
  106. package/mcp/engineClient.js +57 -5
  107. package/mcp/mcpScopes.js +118 -0
  108. package/mcp/meshHttp.js +151 -45
  109. package/mcp/runStdio.js +2 -0
  110. package/mcp/subtreeTools.js +184 -0
  111. package/mcp/tryItTools.js +202 -0
  112. package/package.json +14 -8
  113. package/public/pico-engine-ui.js +26 -26
  114. package/src/cli.ts +6 -2
  115. package/src/engineConfig.ts +5 -2
  116. package/src/identity/portableMove.ts +6 -1
  117. package/src/index.ts +469 -430
  118. package/src/internalAccess.ts +127 -0
  119. package/src/oauth/OAuthService.ts +243 -11
  120. package/src/oauth/acg.ts +289 -25
  121. package/src/oauth/cimd.ts +508 -0
  122. package/src/oauth/discovery.ts +233 -0
  123. package/src/runMcp.ts +3 -1
  124. package/src/server.ts +252 -52
  125. package/src/subtreeWrangler.ts +17 -5
  126. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,467 @@
1
+ # KRL misconceptions and common errors
2
+
3
+ KRL is the programming language for picos. It's a notation for how a pico reacts to events and how it answers queries. This page collects the places where habits from other languages mislead, and the small mistakes that are hard to see. Skim the headings first: most readers recognize their own bug.
4
+
5
+ ## KRL is not JavaScript
6
+
7
+ KRL's syntax looks like JavaScript's: braces, arithmetic and Boolean expressions, things that look like assignment, function definitions and calls, `if`. There is no `for` or `while`, and there are constructs JavaScript doesn't have, such as `select when`, `foreach`, and `defaction`.
8
+
9
+ It has a different execution model and a different memory model. KRL compiles to JavaScript, and the engine is a Node.js program, but a ruleset isn't a program that runs. It's a set of rules that a pico evaluates in reaction to events. The unit of compilation is the ruleset. Rule names must be unique within it, and the *order* the rules are written in matters. Its `global` block can define functions, which evaluate in the context of the ruleset and the pico they're installed in.
10
+
11
+ ## Common misconceptions
12
+
13
+ ### Request/response vs. event/action and query/response
14
+
15
+ If you know HTTP programming, you may think of a pico as a resource. With REST, a GET shouldn't change the resource and a POST or PUT often does. With picos:
16
+
17
+ - A **query** can never change the pico. It calls a function the ruleset lists in `shares` and returns the value, given the current state. Functions can't change state, and an HTTP POST isn't allowed in one. (KRL does let a function make a synchronous HTTP GET to use outside information, and a poorly designed resource may change in response to a GET, but that is the outside world's problem.)
18
+ - Only an **event** can change a pico. Rules react by (conditionally) taking actions on the outside world and by changing entity variables in the postlude, and they can raise more events to the same pico.
19
+
20
+ Think of a pico as a state machine: queries tell you what state it's in; events (maybe) change it.
21
+
22
+ An event's rules can change things in two places: **outside** the pico, through actions, and **inside** it, through the postlude.
23
+
24
+ <img src="/developing/_media/676397057-pico.png" alt="A pico with changes outside (action) above it and changes inside (postlude) within it" width="50%">
25
+
26
+ Queries are `GET`s to `/sky/query/<eci>/<rid>/<function>?…` and events are `POST`s (or `GET`s) to `/sky/event/<eci>/<eid>/<domain>/<type>`. The first path component is the giveaway. The event URL names the pico, the domain, and the type, but **not a ruleset**: every installed ruleset with a salient rule gets a chance. A query names the ruleset and function, and only that one answers. See the [Event API](/exp/event), the [Query API](/exp/query), and [Event Loop Introduction](/developing/event-loop).
27
+
28
+ The response to an event isn't produced until the whole cycle, including the rules that events raised along the way scheduled, has finished. Actions on the outside world happen as the rules evaluate, not at the end.
29
+
30
+ ### Name binding is not variable assignment
31
+
32
+ Most languages have an assignment that replaces the value at an address. KRL has two different things, and they're written differently.
33
+
34
+ **Declarations bind a name to a value.** In a `global` or `pre` block, `x = 3` binds the name `x`. The left side is always a plain name. There is no assignment, and the binding is in force from that point on: through the rest of the `global` block and the rules, or through the rest of the rule. Names are also bound by `setting(...)` in an event expression, by an action, and by `foreach`.
35
+
36
+ Don't declare a name twice. A second declaration doesn't change the first. It shadows it, and functions that closed over the first still see the first. The compiler warns about a duplicate declaration, so take notice of that.
37
+
38
+ ```krl
39
+ pre {
40
+ x = 3
41
+ y = function(a){ x + a }
42
+ x = 5 // shadows, doesn't change; y(6) is still 9
43
+ }
44
+ ```
45
+
46
+ Rather than "refining" a binding, give each step its own name. See [Declaration Semantics](/krl/rulesets/rules/prelude/declarations/declaration-semantics).
47
+
48
+ **Entity variable assignment** changes pico state. It uses `:=`, only in a rule's postlude, so only events can change state:
49
+
50
+ ```krl
51
+ fired {
52
+ ent:count := ent:count.defaultsTo(0) + 1;
53
+ ent:rooms{[room, "temp"]} := temp // path assignment for a nested key
54
+ }
55
+ ```
56
+
57
+ Use the *composite path* form, `ent:m{[a, "b"]} := v`, to set a nested key. Chained braces (`ent:m{a}{"b"} := v`) don't parse as an assignment target, and building a new map with `put` and assigning the whole thing back is more work and slower for large values.
58
+
59
+ Each pico keeps its own state: the entity variables of each ruleset installed in it, which persist.
60
+
61
+ ### Operators produce new values
62
+
63
+ KRL's operators never change a structure in place. They return a new one. A line like this
64
+
65
+ ```krl
66
+ temp = ent:var
67
+ temp[1].put("b", temp[1]{"b"} + 1) // computes a new map; changes neither temp nor ent:var
68
+ ```
69
+
70
+ computes a new value and then throws it away, because nothing receives it. Even if you used it, the result would be only the changed *part*, not the whole structure. To change state, assign the new whole value, or a path, in a postlude:
71
+
72
+ ```krl
73
+ fired {
74
+ ent:counts{[room, "n"]} := ent:counts{[room, "n"]}.defaultsTo(0) + 1
75
+ }
76
+ ```
77
+
78
+ ### Order of rule evaluation
79
+
80
+ When an event arrives, the engine builds a **schedule** of the rules salient for it. Rules in one ruleset are in the order they're written. Across rulesets the order is undefined. Evaluation then runs down the schedule.
81
+
82
+ A `raise` in a postlude doesn't run anything. The engine finds the rules salient for the raised event and **appends** them to the end of the schedule. They run after *all* the rules already on it. The lexical order applies each time rules are looked up, once for the arriving event and again for each raised one, so it can produce surprising results.
83
+
84
+ Here's a real example. A ruleset records temperature readings to a spreadsheet at `ent:url`. To change the URL each month, someone added a rule *before* the recording rule, so it would run first when `wovyn:new_temperature_reading` arrived:
85
+
86
+ ```krl
87
+ rule set_up_url {
88
+ select when probe_temp_recorder new_url url re#^(http.*)# setting(url)
89
+ fired {
90
+ ent:url := url;
91
+ ent:urlInEffectSince := time:now()
92
+ }
93
+ }
94
+ rule check_for_new_month {
95
+ select when wovyn new_temperature_reading
96
+ pre { … }
97
+ if new_month && new_url then noop()
98
+ fired {
99
+ raise probe_temp_recorder event "new_url" attributes { "url": new_url }
100
+ }
101
+ }
102
+ rule record_probe_temp_to_sheet {
103
+ select when wovyn new_temperature_reading where ent:url
104
+ …
105
+ http:post(ent:url, qs = data) setting(response)
106
+ }
107
+ ```
108
+
109
+ `set_up_url` is written first, but the schedule for the original event was `check_for_new_month` then `record_probe_temp_to_sheet`. The raised `new_url` event put `set_up_url` at the *end*, so it ran last: the first reading of a new month went to the old URL.
110
+
111
+ The fix was to do the work directly: put the postlude statements of `set_up_url` in `check_for_new_month`'s postlude instead of raising. It's tempting to avoid the repetition by chaining with `raise`, but that doesn't work when the order matters. If one rule's result must be visible to another rule in the same cycle, do the assignment in the first rule's postlude (rules later in the schedule see it) rather than through a raised event.
112
+
113
+ ### Interference between rulesets
114
+
115
+ An event goes to *every* installed ruleset with a salient rule. Usually just one ruleset cares, but make sure your rules react only to what they should.
116
+
117
+ The standard example is `wrangler:ruleset_installed`, raised when a ruleset is installed in a pico. Every installed ruleset sees it, not only the one just installed. The `rids` attribute lists the rulesets that were installed, so guard with it:
118
+
119
+ ```krl
120
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
121
+ ```
122
+
123
+ Another example is creating a child. A rule that asks wrangler for a child with `raise wrangler event "new_child_request"` gets `wrangler:new_child_created` back, but so does any other rule in any ruleset that selects it, whether or not it asked. Correlate with an attribute that passes through, such as `meta:txnId`, which is unique to this schedule:
124
+
125
+ ```krl
126
+ rule make_child {
127
+ select when app new_thing name re#(.+)# setting(name)
128
+ fired {
129
+ raise wrangler event "new_child_request" attributes {
130
+ "name": name, "txn_id": meta:txnId
131
+ }
132
+ }
133
+ }
134
+
135
+ rule child_ready {
136
+ select when wrangler new_child_created where event:attr("txn_id") == meta:txnId
137
+ …
138
+ }
139
+ ```
140
+
141
+ The second rule only selects when the child it asked for is created, not when someone creates a child by hand in the UI. Wrangler passes the extra attributes of the request along. (Note `meta:txnId` works here because both rules run in the same cycle. If your reply arrives in a later one, which is common with `event:send`, pass a correlation id of your own instead.)
142
+
143
+ ### A rule's name is not its event
144
+
145
+ The name of a rule is for reference (in logs, for example) and must be unique within a ruleset. The event it listens to is in its `select when`. Rule names are usually verbs and event types usually nouns.
146
+
147
+ ```krl
148
+ rule send_twilio_sms_message {
149
+ select when twilio new_sms_message
150
+ …
151
+ }
152
+ ```
153
+
154
+ This rule is **not** triggered by raising `twilio:send_twilio_sms_message`. That's a common mistake: rules aren't procedures that you call by raising an event named after them. Raise the event the rule selects on, `twilio:new_sms_message`.
155
+
156
+ When two rules select the same event, both are scheduled, in the order written. That makes this pattern work:
157
+
158
+ ```krl
159
+ rule check_for_a_known_number {
160
+ select when twilio new_sms_message
161
+ if ent:known_numbers >< event:attr("to") then noop()
162
+ notfired {
163
+ last
164
+ }
165
+ }
166
+ rule send_twilio_sms_message {
167
+ select when twilio new_sms_message
168
+ …
169
+ }
170
+ ```
171
+
172
+ If the number is unknown, `last` in the postlude stops the rest of *this ruleset's* rules for the event. `send_twilio_sms_message` was selected but isn't evaluated. (`last` doesn't affect other rulesets' rules on the schedule.)
173
+
174
+ ### One action block and one postlude
175
+
176
+ A rule has at most **one** condition, one action block, and one postlude:
177
+
178
+ ```krl
179
+ rule name {
180
+ select when domain type
181
+ pre { x = event:attr("x") }
182
+ if cond then every { action1(); action2() }
183
+ fired {
184
+ ent:things{[id, "name"]} := x;
185
+ raise domain event "next" attributes { "x": x }
186
+ }
187
+ else {
188
+ error warn <<skipped: no x>>
189
+ }
190
+ }
191
+ ```
192
+
193
+ - Several actions go in one `every { … }` block. Don't write two `if … then` blocks, and there's no `else` on the action.
194
+ - The postlude is `fired`, `notfired`, or `always`. `fired` and `notfired` take an optional `else` (which runs in the opposite case), and an optional `finally`, which runs either way. Don't write `fired { } notfired { }` as two blocks. `finally` can only come after `fired` or `notfired`. Use `always` when you want something to run whatever happened, with nothing else.
195
+ - `event:send` is an action, so it goes in the action block, not in a postlude.
196
+ - `if X then noop()` with `fired { … }` runs the postlude when `X` is **true**. Use `notfired` for the other case.
197
+
198
+ ### Strings: double quotes and chevrons
199
+
200
+ A double-quoted string is a constant. It can't contain line breaks, and the compiler turns it into a JavaScript string.
201
+
202
+ A chevron-quoted string (`<< … >>`) can contain line breaks and unescaped double quotes. It can also contain **beestings**, `#{expression}`, which are evaluated at run time, so the value can differ each time. When that happens depends on where it appears: in `global`, when the ruleset is installed; in a function, each time it's called; in a prelude, each time the rule selects; in a postlude, each time it runs.
203
+
204
+ ```krl
205
+ url = <<#{meta:host}/sky/event/#{eci}/none/byu_hr_login/logout_request>>
206
+ ```
207
+
208
+ A beesting can contain a chevron string:
209
+
210
+ ```krl
211
+ #{is_self => << title="this is you">> | ""}
212
+ ```
213
+
214
+ (or, less readable, `#{is_self => " title=\"this is you\"" | ""}`).
215
+
216
+ When a chevron string holds markup, put the closing `>>` on its own line, and the opening `<<` too if the first thing is a tag. `>>>` is ambiguous (the compiler sees `>>`, then a stray `>`):
217
+
218
+ ```krl
219
+ <<
220
+ <option#{e == el => " selected" | ""}>#{e}</option>
221
+ >>
222
+ ```
223
+
224
+ <img src="/developing/_media/676397057-screen-shot-2020-01-16-at-9.41.39-am.png" alt="KRL chevron string with beestings for selected option markup" width="50%">
225
+
226
+ ### KRL isn't Java: `raise` is not a call
227
+
228
+ A ruleset installed as a module doesn't make an object. The pico pre-existed, and the ruleset's entity variables belong to that pico. Consider a ruleset that offers a "setter" by event:
229
+
230
+ ```krl
231
+ ruleset holder {
232
+ meta { provides getter }
233
+ global { getter = function(){ ent:stuff } }
234
+ rule stuffer {
235
+ select when holder setter
236
+ fired {
237
+ ent:stuff := event:attrs{"stuff"};
238
+ raise holder event "stuffed" attributes event:attrs
239
+ }
240
+ }
241
+ }
242
+ ```
243
+
244
+ and a naive caller:
245
+
246
+ ```krl
247
+ ruleset java_pattern {
248
+ meta { use module holder }
249
+ rule checker {
250
+ select when user checker
251
+ pre { value = random:word() }
252
+ fired {
253
+ ent:value := value;
254
+ raise holder event "setter" attributes {"stuff": value} // schedules the setter, doesn't call it
255
+ }
256
+ }
257
+ rule tester {
258
+ select when user checker
259
+ send_directive("result", {"okay": ent:value == holder:getter()}) // false
260
+ }
261
+ }
262
+ ```
263
+
264
+ The schedule when `user:checker` arrives is `checker`, then `tester`. `holder:setter` is *appended*, so `tester` runs before `stuffer` does and reports `false`. "Saves it away" should have been read as "schedules it to be saved, later."
265
+
266
+ The right pattern uses the terminal event the module raises, `holder:stuffed`, which it provides for exactly this purpose:
267
+
268
+ ```krl
269
+ rule tester {
270
+ select when holder stuffed
271
+ send_directive("result", {"okay": ent:value == holder:getter()})
272
+ }
273
+ ```
274
+
275
+ A module that does work in response to events should raise a *terminal* event, one it doesn't react to itself, so callers know when it has finished.
276
+
277
+ ## Common errors
278
+
279
+ ### Regular expression capture groups
280
+
281
+ `setting` binds to a capture group, which needs parentheses in the regular expression:
282
+
283
+ ```krl
284
+ select when phone incoming number re#\d{10}# setting(caller_id) // caller_id is never bound
285
+ select when phone incoming number re#(\d{10})# setting(caller_id) // right
286
+ ```
287
+
288
+ Without the parentheses `caller_id` stays unbound and evaluates to `null` when used.
289
+
290
+ ### Regular expression capture vs. explicit binding
291
+
292
+ These look equivalent and aren't:
293
+
294
+ ```krl
295
+ select when console incoming attr_name re#(.+)# setting(local_name)
296
+ ```
297
+
298
+ ```krl
299
+ select when console incoming
300
+ pre { local_name = event:attr("attr_name") }
301
+ ```
302
+
303
+ The first only selects when `attr_name` matches. Regular expressions work on a single line, so with a multi-line value, don't count on getting more than the first line. The second binds the whole attribute value, which is also what you want when the value might be empty or absent. Use `event:attr` in the prelude for a multi-line value.
304
+
305
+ ### Forgetting the parentheses on a function call
306
+
307
+ A function is called with parentheses, even with no arguments: `f()`. Without them, the name evaluates to the function itself, and the errors that follow can be astonishing.
308
+
309
+ ### Dots, colons, and braces
310
+
311
+ - **Dots** introduce operators: `list.length()`. Don't use a dot to get a map key, as in JavaScript.
312
+ - **Colons** separate a module or library name from what it provides: `time:now()`, `ent:name`. A dot in its place gives an unknown operator error.
313
+ - **Curly braces** after a map get the value for a key or path: `m{"k"}`, `m{["a","b"]}`.
314
+ - **Square brackets** index arrays: `a[0]`.
315
+
316
+ ### A name or a string in a map reference
317
+
318
+ Inside braces, a quoted key is the literal string; a bare name is the value the name is bound to. It's easy to get this wrong:
319
+
320
+ ```krl
321
+ their_key = event:attr("sender_key")
322
+ se = ent:se{"their_key"} // the key "their_key", almost certainly null
323
+ se = ent:se{their_key} // the key the name is bound to
324
+ ```
325
+
326
+ The first always gives `null`, and the `http:post` that uses it will always fail.
327
+
328
+ ### The empty string isn't null
329
+
330
+ A blank form field arrives as the empty string, not as a missing attribute, so `event:attr("name")` is `""`, not `null`. Then:
331
+
332
+ - `isnull()` is `false`.
333
+ - `defaultsTo()` only replaces `null` (or a missing value), so `event:attr("name").defaultsTo(ent:name)` stays empty.
334
+
335
+ Use `||` when you also want to replace the empty string (and other false values):
336
+
337
+ ```krl
338
+ name = event:attr("name") || ent:name
339
+ ```
340
+
341
+ Also the string `"null"` is not `null`. `"null".decode()` is `null`, and so is `null.decode()`, so if you're not sure, decode. (`decode` returns a string unchanged if it isn't JSON.)
342
+
343
+ ### Regular expressions and case
344
+
345
+ A regex is case sensitive unless you flag it:
346
+
347
+ ```krl
348
+ "1E4C".match(re#1e4c#) // false
349
+ "1E4C".match(re#1e4c#i) // true
350
+ ```
351
+
352
+ A regex made from a string, `"1e4c".as("RegExp")`, has no way to carry the `i` flag. Change the case of the string you're matching (or the pattern) with `uc()` or `lc()` instead:
353
+
354
+ ```krl
355
+ "1E4C".match("1e4c".uc().as("RegExp")) // true
356
+ ```
357
+
358
+ ### Operator precedence
359
+
360
+ Infix operators rarely need parentheses, but sometimes you need them, and the bug is subtle. The conditional (`=>`) binds more loosely than `+`. This conditionally-added part didn't do what was intended:
361
+
362
+ ```krl
363
+ html:header("Tic Tac Toe", css)
364
+ + <<<h1>…</h1>
365
+ >>
366
+ + board
367
+ + need_detail => << Moves: #{moves.encode()} >> | "" // wrong: the whole sum is the test
368
+ + js
369
+ ```
370
+
371
+ Everything before `=>` was concatenated into the condition. It's a non-empty string, so true, and the result was just the "Moves" part. Parenthesize:
372
+
373
+ ```krl
374
+ + (need_detail => << Moves: #{moves.encode()} >> | "")
375
+ ```
376
+
377
+ A conditional inside a beesting is already enclosed, so it doesn't need them.
378
+
379
+ ### Attributes when you generate an event
380
+
381
+ There are two ways to generate an event from a rule, and each names its attributes differently.
382
+
383
+ **`event:send`** is an *action* (action block only, no `use module` needed). Its first argument is a map. Keys: `"eci"` (the target channel, usually another pico's), `"domain"`, `"type"` (or `"name"`), optionally `"eid"`, and `"attrs"` (a map of the attributes). The event goes out asynchronously, perhaps to another engine. If the ECI is your own pico's, the event is queued and handled in a later cycle.
384
+
385
+ **`raise … event … attributes …`** is a postlude statement. The event always goes to *this* pico, and the rules it selects are scheduled in the same cycle, after the ones already scheduled.
386
+
387
+ It's easy to write `"attributes"` where you mean `"attrs"`, or the other way around. And a key that `event:send` doesn't know is silently ignored, so this sends *no* attributes:
388
+
389
+ ```krl
390
+ event:send({
391
+ "eci": eci,
392
+ "domain": "wrangler",
393
+ "type": "ready_for_deletion",
394
+ "co_id": meta:rid // not a recognized key; ignored
395
+ })
396
+ ```
397
+
398
+ The attributes belong under `"attrs"`:
399
+
400
+ ```krl
401
+ event:send({
402
+ "eci": eci,
403
+ "domain": "wrangler",
404
+ "type": "ready_for_deletion",
405
+ "attrs": { "co_id": meta:rid }
406
+ })
407
+ ```
408
+
409
+ ### An empty array is truthy
410
+
411
+ KRL follows JavaScript's truthiness rules: `0`, `""`, `false`, and `null` are false, but an empty array is **true**. A test like
412
+
413
+ ```krl
414
+ pending => handle_them() | nothing_to_do() // pending is an array of requests
415
+ ```
416
+
417
+ is true even when `pending` is `[]`, so `handle_them()` is chosen when there's nothing to handle. Test the length, since zero is false:
418
+
419
+ ```krl
420
+ pending.length() => handle_them() | nothing_to_do()
421
+ ```
422
+
423
+ ### A domain isn't a ruleset id
424
+
425
+ An event domain is often similar to a ruleset id, but a ruleset id like `byu.hr.connect` has dots, which a bare event domain can't. So you can't use `meta:rid` where a domain is expected. Spell out the domain (`byu_hr_connect`), or convert: `"byu.hr.connect".replace(re#[.]#g, "_")`.
426
+
427
+ ### Initializing entity variables on install
428
+
429
+ A rule that gives entity variables initial values when a ruleset is installed needs two guards:
430
+
431
+ ```krl
432
+ rule initialize {
433
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
434
+ if ent:apps.isnull() then noop()
435
+ fired {
436
+ ent:apps := built_ins()
437
+ }
438
+ }
439
+ ```
440
+
441
+ - The `where` clause. Without it the rule selects whenever *any* ruleset is installed in the pico, and resets the variable each time, erasing changes made since.
442
+ - The `isnull()` test. It protects against the ruleset being initialized again. A pico's state can accumulate for months, and a reinstall that re-initializes it would throw that away. (Wrangler raises `ruleset_installed` only when the ruleset's id is new on the pico, and a flush doesn't raise it, but the guard is cheap and covers any other path to this rule.)
443
+
444
+ See [Initializing entity variables](/developing/initializing-entity-variables).
445
+
446
+ ### Regular expressions and multi-line strings
447
+
448
+ When an event expression captures an attribute value with a regular expression, only a single line of it is matched and kept. For a multi-line attribute, read it with `event:attr` in the prelude instead.
449
+
450
+ ### The ruleset id and the file name
451
+
452
+ By convention the file is named after the ruleset id, with `.krl` on the end, but nothing enforces it. If you don't follow the convention, know where each is used:
453
+
454
+ - The **rid** (what's in `ruleset <rid> { … }`, and `meta:rid`) goes in query URLs (`/sky/query/<eci>/<rid>/…`) and in the `rid` attribute of wrangler's install request.
455
+ - The **URL** ends with the whole file name, extension included, and is what the `url` attribute of an install request and the flush use.
456
+
457
+ The engine enforces uniqueness of installed rulesets in a pico by rid, not by URL.
458
+
459
+ ## See also
460
+
461
+ - [Event Loop Introduction](/developing/event-loop): how the schedule works
462
+ - [KRL manual](/krl/): the language reference
463
+ - [Guard rules](/cookbook/guard_rules/): demo of the guard patterns here
464
+
465
+ ---
466
+
467
+ <small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/676397057), and updated for this engine.</small>
@@ -0,0 +1,44 @@
1
+ # What's in a name?
2
+
3
+ KRL keeps many kinds of names apart: the ruleset id, rule names, event domains and types, attribute names, global and local names, function parameters, and directive names. As an exercise, here is a ruleset where every one of them is `name`:
4
+
5
+ ```krl
6
+ ruleset name {
7
+ meta {
8
+ shares name
9
+ }
10
+ global {
11
+ /**
12
+ * @param name String
13
+ */
14
+ name = function(name) {
15
+ name.klog("name") => name | "name"
16
+ }
17
+ }
18
+ rule name {
19
+ select when name name
20
+ pre {
21
+ name = event:attr("name").defaultsTo(name(name), "name")
22
+ }
23
+ send_directive("name", {"name": name || "name"})
24
+ }
25
+ rule name_provided {
26
+ select when name name name re#(.+)# setting(name)
27
+ send_directive("name", {"name": name})
28
+ }
29
+ }
30
+ ```
31
+
32
+ It works. Most of the uses can't collide: an event domain, a rule name, and a directive name live in different places. One line is worth a closer look:
33
+
34
+ ```krl
35
+ name = event:attr("name").defaultsTo(name(name), "name")
36
+ ```
37
+
38
+ The right-hand side is evaluated before the binding. At that moment `name` is still the global function, so `name(name)` calls the function with itself as the argument, and it returns itself, because a function is truthy. After the line, `name` is bound to the result, and the global function is shadowed for the rest of the rule.
39
+
40
+ Raise `name:name` with `name` set to `Ada` and both rules answer `{"name": "Ada"}`. Raise it without the attribute and `defaultsTo` uses the function (logging `"name"`). The directive's `name` is then a function, which doesn't survive conversion to JSON, so the reply shows `{}`.
41
+
42
+ So: a name declared in `pre` hides a global of the same name for the rest of that rule. That is legal, and usually a mistake. And a name in `pre` can't be declared twice. KRL declarations are not assignments.
43
+
44
+ *From the Pico Labs KRL Cookbook page "What's in a name?".*
@@ -0,0 +1,159 @@
1
+ # Event and Query URLs with Postman
2
+
3
+ [Postman](https://www.postman.com/) is a desktop tool for building and sending HTTP requests and examining the responses. It's handy for trying events and queries on a pico: you can save requests, change attributes quickly, and keep them in a collection.
4
+
5
+ Everything here is plain HTTP, so `curl` works equally well. Each Postman step has a `curl` equivalent. For the full API, see the [Event API](/exp/event) and [Query API](/exp/query). For a gentler introduction, see [Events and Queries](/lessons/events-and-queries).
6
+
7
+ The examples use `http://localhost:3000`, the engine's default address. Use your own host and port if you've changed them.
8
+
9
+ ## Before you start: pick a channel
10
+
11
+ Both events and queries are sent to a pico through one of its **channels**, and a channel is named by its ECI (event channel identifier). The channel's *policy* decides which events and queries it allows.
12
+
13
+ 1. Open the developer UI, click the pico, and open its **Channels** tab.
14
+ 2. Choose a channel whose policies allow what you want to send. The pico's own `self` channel (its ECI is the pico's id) allows everything, which is fine for experiments. For anything you'll leave around, make a channel that allows only what's needed. See [Managing channels](/wrangler/channels).
15
+ 3. Copy the ECI.
16
+
17
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-11.52.28-am.png" alt="Channels tab showing a channel and its ECI to copy" width="50%">
18
+
19
+ If a request is refused, you'll get HTTP 200 and `{"error":"Error: Not allowed by channel policy"}`. Use a channel with a more permissive policy.
20
+
21
+ If the mesh has [OAuth](/wrangler/oauth) turned on, requests also need an `Authorization: Bearer <token>` header, which in Postman is the **Authorization** tab.
22
+
23
+ ## Raising an event
24
+
25
+ The event URL looks like this:
26
+
27
+ ```
28
+ http://localhost:3000/sky/event/<eci>/<eid>/<domain>/<type>
29
+ ```
30
+
31
+ - `<eci>`: the channel
32
+ - `<eid>`: an event id you choose, for your own tracing (`none` is common)
33
+ - `<domain>` and `<type>`: the event's domain and type, which rules select on
34
+
35
+ This example asks wrangler to create a child pico: the domain is `wrangler` and the type is `new_child_request`.
36
+
37
+ > **Older docs and rulesets** call this event `child_creation`. The current wrangler event is `wrangler:new_child_request`. Likewise, in URLs `/sky/query/` replaces `/sky/cloud/`.
38
+
39
+ ### In Postman
40
+
41
+ 1. Create a new request tab.
42
+
43
+ <img src="/developing/_media/1177157666-att1177157745-screen-shot-2020-06-25-at-11.07.07-am.png" alt="Postman: create a new request tab" width="50%">
44
+
45
+ 2. Set the method to **POST**. (GET works for events, but POST is preferred because an event may change the pico.)
46
+
47
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-11.12.51-am.png" alt="Postman request method set to POST" width="50%">
48
+
49
+ 3. Enter the URL, with your ECI:
50
+
51
+ ```
52
+ http://localhost:3000/sky/event/<eci>/child_test/wrangler/new_child_request
53
+ ```
54
+
55
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.29.51-pm.png" alt="Postman address bar with the Sky event URL" width="50%">
56
+
57
+ 4. Open the **Body** tab, choose **raw**, and set the type to **JSON**. Put the event's attributes in the body as a JSON object:
58
+
59
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.19.02-pm.png" alt="Postman Body tab with raw and JSON selected" width="50%">
60
+
61
+ ```json
62
+ {
63
+ "name": "test child",
64
+ "backgroundColor": "#87cefa"
65
+ }
66
+ ```
67
+
68
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.34.56-pm.png" alt="Postman raw JSON body with event attributes" width="50%">
69
+
70
+ 5. Click **Send**.
71
+
72
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.35.59-pm.png" alt="Postman Send button to submit the request" width="50%">
73
+
74
+ *These screenshots are from an earlier release: they show port 8080 and the old `child_creation` event name. Use the URL and event above.*
75
+
76
+ A JSON body is the best way to send attributes: it keeps numbers, booleans, and nested maps as they are, and avoids URL-encoding. You can also send attributes as a query string (`?name=test%20child`) or as `application/x-www-form-urlencoded`. When a name appears in both body and query string, the body wins.
77
+
78
+ ### The response
79
+
80
+ The response is JSON. It carries the transaction id, any directives from rules that ran, which rules fired, and the events raised during the cycle:
81
+
82
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.35.46-pm.png" alt="Postman response JSON with directives and rule outcomes after Send" width="50%">
83
+
84
+ ```json
85
+ {
86
+ "eid": "…",
87
+ "directives": [ … ],
88
+ "ruleOutcomes": [ { "rid": "io.picolabs.wrangler", "rule": "createChild", "status": "fired" } ],
89
+ "events": [ { "domain": "wrangler", "name": "new_child_created", "attrs": { … } } ]
90
+ }
91
+ ```
92
+
93
+ For a wrangler event like this one there may be no directive: the `events` list and the new child in the developer UI are your confirmation. A rule that calls `send_directive` shows up under `directives`. The [Event API](/exp/event#response) page describes every field.
94
+
95
+ ### With curl
96
+
97
+ ```sh
98
+ curl -X POST "http://localhost:3000/sky/event/<eci>/child_test/wrangler/new_child_request" \
99
+ -H 'content-type: application/json' \
100
+ -d '{"name": "test child", "backgroundColor": "#87cefa"}'
101
+ ```
102
+
103
+ ## Querying a pico
104
+
105
+ A query calls a function that a ruleset lists in its `shares`, and returns the function's value. It can't change the pico. The URL looks like this:
106
+
107
+ ```
108
+ http://localhost:3000/sky/query/<eci>/<rid>/<function>?<arguments>
109
+ ```
110
+
111
+ - `<rid>`: the ruleset id that shares the function
112
+ - `<function>`: the function's name
113
+ - arguments: the function's parameters, by name (order doesn't matter)
114
+
115
+ ### In Postman
116
+
117
+ 1. Create a new request tab and set the method to **GET**.
118
+
119
+ <img src="/developing/_media/1177157666-att1177157745-screen-shot-2020-06-25-at-11.07.07-am.png" alt="Postman: create a new request tab for a query" width="50%">
120
+
121
+ <img src="/developing/_media/1177157666-att1177157757-screen-shot-2020-06-25-at-11.16.39-am.png" alt="Postman request method set to GET" width="50%">
122
+
123
+ 2. Choose the pico, the ruleset, and a function that ruleset shares. The pico's **Testing** tab lists the queries a ruleset shares, and the **Channels** tab has the ECI. This example uses wrangler's `children` query:
124
+
125
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-11.46.05-am.png" alt="Developer UI Testing tab: pico, ruleset, and shared function" width="50%">
126
+
127
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-11.46.24-am.png" alt="Channels tab ECI for the query URL" width="50%">
128
+
129
+ ```
130
+ http://localhost:3000/sky/query/<eci>/io.picolabs.wrangler/children
131
+ ```
132
+
133
+ 3. For a function with parameters, add them on the **Params** tab (Postman builds the query string), such as `name = Ada` for `…/io.picolabs.hello_world/hello?name=Ada`. The names must match the function's parameter names.
134
+
135
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.09.26-pm.png" alt="Postman Params tab and query URL with parameters" width="50%">
136
+
137
+ 4. Click **Send**. The body is the function's return value, as JSON.
138
+
139
+ <img src="/developing/_media/1177157666-screen-shot-2020-06-25-at-12.08.57-pm.png" alt="Postman response body showing the query result as JSON" width="50%">
140
+
141
+ If the function isn't in the ruleset's `shares` list, or the ruleset isn't installed in that pico, the response has an `error` field instead of a value. A GET is the natural method, though POST with a form-encoded or JSON body also works and is useful for long arguments.
142
+
143
+ ### With curl
144
+
145
+ ```sh
146
+ curl "http://localhost:3000/sky/query/<eci>/io.picolabs.wrangler/children"
147
+ curl "http://localhost:3000/sky/query/<eci>/io.picolabs.hello_world/hello?name=Ada"
148
+ ```
149
+
150
+ ## Tips
151
+
152
+ - Use Postman **variables** (such as `{{eci}}` and `{{base}}`) for the base URL and ECI, so a saved request works on another pico or engine by changing one value.
153
+ - Add `.txt` or `.html` to a function name (`…/page.html`) to get the function's string result as plain text or a web page. See the [Query API](/exp/query#text-and-html).
154
+ - If a rule doesn't seem to run, open the pico's **Logging** tab and look at the transaction your request created.
155
+ - To exercise a whole system, not one pico, the [Programming lessons](/lessons/) and the [EXP](/exp/) pages show how events and queries fit together.
156
+
157
+ ---
158
+
159
+ <small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1177157666) (last edited there 2020-06-26), and updated for this engine.</small>