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,139 @@
1
+ /**
2
+ * Task runner: hands each task to a new child pico, so this pico never waits.
3
+ * task:start creates a child and installs com.example.task_worker on it with
4
+ * the task. The worker does the work, sends task:done back, and asks wrangler to
5
+ * delete it. This pico records the result and notes when the child is gone.
6
+ */
7
+ ruleset com.example.task_runner {
8
+ meta {
9
+ name "Task runner"
10
+ description "Runs each task in its own child pico, which reports back and deletes itself."
11
+ author "PICOLABS"
12
+
13
+ use module io.picolabs.wrangler alias wrangler
14
+ use module io.picolabs.xmlui alias ui
15
+
16
+ shares tasks, tasksPage
17
+ }
18
+
19
+ global {
20
+ channel_tags = ["task_runner", "app"]
21
+ worker_rid = "com.example.task_worker"
22
+
23
+ /**
24
+ * Every task, newest first.
25
+ * @returns Array of { id, n, status, primes, worker, started, finished }
26
+ */
27
+ tasks = function() {
28
+ ent:tasks.defaultsTo({}).values()
29
+ .sort(function(a, b) { b{"id"} <=> a{"id"} })
30
+ }
31
+
32
+ /**
33
+ * Start tasks and watch child picos do them.
34
+ * @view "Tasks"
35
+ */
36
+ tasksPage = function() {
37
+ tasks_url = ui:query_url("tasks", meta:rid, meta:eci)
38
+ start_url = ui:event_url("task", "start")
39
+ <<
40
+ <Component name="TasksPage">
41
+ <DataSource id="list" url="#{tasks_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="2" />
42
+ <APICall id="start" method="post" url="#{start_url}" headers="{appGlobals.auth}" body="{$param}"
43
+ onSuccess="list.refetch()" />
44
+ <PicoTheme>
45
+ <Card title="Tasks"
46
+ subtitle="Each task counts the primes up to n in its own child pico. Watch the children appear in the developer UI and go away when they finish." />
47
+ <Form saveLabel="Start a task" onSubmit="(data) => start.execute(data)">
48
+ <FormItem bindTo="n" label="Count primes up to" type="integer" initialValue="20000" />
49
+ </Form>
50
+ <Table data="{list}">
51
+ <Column bindTo="id" header="Task" />
52
+ <Column bindTo="n" header="n" />
53
+ <Column bindTo="status" header="Status" />
54
+ <Column bindTo="primes" header="Primes" />
55
+ <Column bindTo="worker" header="Worker pico" />
56
+ </Table>
57
+ </PicoTheme>
58
+ </Component>
59
+ >>
60
+ }
61
+ }
62
+
63
+ /**
64
+ * Start a task: count the primes up to n in a new child pico.
65
+ * @attr n Number "count primes up to this number"
66
+ * @example "twenty thousand" { "n": "20000" }
67
+ */
68
+ rule start_task {
69
+ select when task start
70
+ n re#^(\d+)$#
71
+ setting(n)
72
+ pre {
73
+ id = ent:next_id.defaultsTo(1)
74
+ key = id.as("String")
75
+ }
76
+ always {
77
+ ent:next_id := id + 1
78
+ ent:tasks{key} := {"id": id, "n": n.as("Number"), "status": "starting", "started": time:now()}
79
+ raise wrangler event "new_child_request" attributes
80
+ {"name": "Task " + key, "task_id": key, "n": n}
81
+ }
82
+ }
83
+
84
+ // The child is set up; give it the worker ruleset and the task.
85
+ rule hand_off_task {
86
+ select when wrangler child_initialized where event:attr("task_id")
87
+ pre {
88
+ key = event:attr("task_id")
89
+ child = event:attr("eci")
90
+ }
91
+ event:send({
92
+ "eci": child,
93
+ "domain": "wrangler",
94
+ "type": "install_ruleset_request",
95
+ "attrs": {
96
+ "absoluteURL": meta:rulesetURI,
97
+ "rid": worker_rid,
98
+ "task_id": key,
99
+ "n": event:attr("n")
100
+ }
101
+ })
102
+ always {
103
+ ent:tasks{[key, "status"]} := "working"
104
+ ent:tasks{[key, "worker"]} := event:attr("name")
105
+ ent:tasks{[key, "worker_eci"]} := child
106
+ }
107
+ }
108
+
109
+ /**
110
+ * A worker finished.
111
+ * @attr task_id String "the task"
112
+ * @attr primes Number "how many primes it found"
113
+ */
114
+ rule task_done {
115
+ select when task done
116
+ task_id re#(.+)#
117
+ setting(key)
118
+ always {
119
+ ent:tasks{[key, "status"]} := "done"
120
+ ent:tasks{[key, "primes"]} := event:attr("primes")
121
+ ent:tasks{[key, "finished"]} := time:now()
122
+ }
123
+ }
124
+
125
+ // Wrangler deleted a worker that asked to be deleted.
126
+ rule worker_deleted {
127
+ select when wrangler child_deleted
128
+ foreach ent:tasks.defaultsTo({}).values() setting(task)
129
+ if task{"worker_eci"} == event:attr("eci") then noop()
130
+ fired {
131
+ ent:tasks{[task{"id"}.as("String"), "worker"]} := task{"worker"} + " (deleted)"
132
+ }
133
+ }
134
+
135
+ rule create_app_channel {
136
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
137
+ ui:create_app_channel(channel_tags, ["task"], ["tasks", "tasksPage"], meta:rid)
138
+ }
139
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Task worker: installed on a new child pico with a task. It counts the primes
3
+ * up to n, sends task:done to its parent, and asks wrangler to delete it. The
4
+ * parent is never blocked while the work runs here.
5
+ */
6
+ ruleset com.example.task_worker {
7
+ meta {
8
+ name "Task worker"
9
+ description "Does one task, reports to its parent, and deletes itself."
10
+ author "PICOLABS"
11
+
12
+ use module io.picolabs.wrangler alias wrangler
13
+ }
14
+
15
+ global {
16
+ // True when no number from d up to the square root of k divides k.
17
+ noDivisorFrom = function(k, d) {
18
+ d * d > k => true |
19
+ k % d == 0 => false |
20
+ noDivisorFrom(k, d + 1)
21
+ }
22
+
23
+ countPrimes = function(n) {
24
+ n < 2 => 0 |
25
+ 2.range(n).filter(function(k) { noDivisorFrom(k, 2) }).length()
26
+ }
27
+ }
28
+
29
+ rule do_task {
30
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
31
+ pre {
32
+ n = event:attr("n").as("Number")
33
+ primes = countPrimes(n)
34
+ }
35
+ event:send({
36
+ "eci": wrangler:parent_eci(),
37
+ "domain": "task",
38
+ "type": "done",
39
+ "attrs": {"task_id": event:attr("task_id"), "n": n, "primes": primes}
40
+ })
41
+ always {
42
+ raise wrangler event "ready_for_deletion"
43
+ }
44
+ }
45
+ }
@@ -0,0 +1,5 @@
1
+ - Open **Tasks**. The three seeded tasks are done, and each worker pico is marked "(deleted)".
2
+ - Start a task with `n` set to 200000. It takes about ten seconds. While it runs, leave the **Try It!** tab, close the pico, and look at the pico tree: the task runner has a child named after the task. It disappears when the task is done.
3
+ - Start several large tasks one after another. Each gets its own child, and the runner keeps taking new tasks while they work.
4
+ - Open the task runner's **Logging** tab and follow one task: `task:start`, then `wrangler:child_initialized` from the new child, `task:done` from the worker, and its `wrangler:child_deletion_request`. That one shows `wrangler:child_deleted` under **Raised**.
5
+ - In `com.example.task_worker.krl`, comment out the line that raises `ready_for_deletion` and click **Flush**. New workers stay around after they finish, so you can open one and look inside.
@@ -0,0 +1,13 @@
1
+ # Collection demo
2
+
3
+ A pico that keeps a collection of other picos over relationships, accepts members by role, and reports on all of them.
4
+
5
+ - Overview: [`docs/cookbook/collection/README.md`](../../docs/cookbook/collection/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/collection/)
6
+ - Instructions: [`docs/cookbook/collection/instructions.md`](../../docs/cookbook/collection/instructions.md)
7
+
8
+ | File | Shows |
9
+ |------|-------|
10
+ | `com.example.collection.krl` | The collection: accepts members by role, turns away other roles, removes members, and provides `members()` |
11
+ | `com.example.collection.room.krl` | A member: has a temperature, joins, leaves, and rejoins |
12
+ | `com.example.collection.report.krl` | Uses the collection as a module, asks every member for its reading, and has the Rooms page |
13
+ | `com.example.collection.bootstrap.krl` | Creates the collection and five rooms on a new pico (one asks in the wrong role); the **Try It!** tab runs it |
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Try It! bootstrap for the Collection demo. Install it on a new pico: it
3
+ * creates a Rooms child with the collection and report rulesets, then five more
4
+ * children with the room ruleset. Four ask to join as members; the fifth,
5
+ * Stranger, asks in another role and is turned away. tryIt() reports how many
6
+ * have joined and links to the report.
7
+ *
8
+ * Each child gets its install requests and then the event that uses them. A
9
+ * pico handles events one at a time, in the order they arrive, so the rulesets
10
+ * are installed before that event is handled.
11
+ */
12
+ ruleset com.example.collection.bootstrap {
13
+ meta {
14
+ name "Collection"
15
+ description "Shows the collection pattern: members as relationships, accepting and rejecting by role, a ruleset used as a module, and querying every member to report on all of them."
16
+ author "PICOLABS"
17
+
18
+ use module io.picolabs.wrangler alias wrangler
19
+
20
+ shares tryIt
21
+ }
22
+
23
+ global {
24
+ collection_rid = "com.example.collection"
25
+ report_rid = "com.example.collection.report"
26
+ room_rid = "com.example.collection.room"
27
+ xmlui_rid = "io.picolabs.xmlui"
28
+ rooms = [
29
+ {"name": "Kitchen", "temperature": 68},
30
+ {"name": "Office", "temperature": 71},
31
+ {"name": "Garage", "temperature": 64},
32
+ {"name": "Bedroom", "temperature": 75},
33
+ {"name": "Stranger", "temperature": 99, "as": "visitor"}
34
+ ]
35
+
36
+ host = function() {
37
+ meta:host.defaultsTo("").replace(re#/$#, "")
38
+ }
39
+
40
+ collectionQuery = function(func) {
41
+ installed = ent:collection
42
+ => wrangler:picoQuery(ent:collection, "io.picolabs.wrangler", "installedRIDs") | []
43
+ answer = (installed.typeof() == "Array" && installed >< collection_rid)
44
+ => wrangler:picoQuery(ent:collection, collection_rid, func) | []
45
+ answer.typeof() == "Array" => answer | []
46
+ }
47
+
48
+ reportLink = function() {
49
+ channel = ent:collection
50
+ => wrangler:picoQuery(ent:collection, "io.picolabs.wrangler", "channels", {"tags": "collection,app"}).head()
51
+ | null
52
+ channel => {"label": "Rooms", "url": host() + "/ui/" + channel{"id"} + "/" + report_rid + "/"} | null
53
+ }
54
+
55
+ /**
56
+ * Progress of this demo's setup, and the links to open when it is ready.
57
+ * @returns Map
58
+ */
59
+ tryIt = function() {
60
+ joined = collectionQuery("members").length()
61
+ turned_away = collectionQuery("rejections").length()
62
+ ready = joined >= 4 && turned_away >= 1
63
+ link = ready => reportLink() | null
64
+ status = {
65
+ "ready": (ready && link) => true | false,
66
+ "stage": ready => "ready" | ent:collection => joined.as("String") + " of 4 rooms joined" | "starting",
67
+ "links": link => [link] | []
68
+ }
69
+ status
70
+ }
71
+ }
72
+
73
+ rule start {
74
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
75
+ always {
76
+ raise wrangler event "new_channel_request" attributes {
77
+ "tags": ["try_it"],
78
+ "eventPolicy": {"allow": [], "deny": []},
79
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "tryIt"}], "deny": []}
80
+ }
81
+ raise wrangler event "new_child_request" attributes
82
+ {"name": "Rooms", "collection_demo": "collection", "backgroundColor": "#c8e6c9"}
83
+ }
84
+ }
85
+
86
+ // The collection pico is set up: install its rulesets, then create the rooms.
87
+ rule set_up_collection {
88
+ select when wrangler child_initialized where event:attr("collection_demo") == "collection"
89
+ pre {
90
+ child = event:attr("eci")
91
+ }
92
+ every {
93
+ event:send({
94
+ "eci": child,
95
+ "domain": "wrangler",
96
+ "type": "install_ruleset_request",
97
+ "attrs": {"url": host() + "/krl/" + xmlui_rid + ".krl"}
98
+ })
99
+ event:send({
100
+ "eci": child,
101
+ "domain": "wrangler",
102
+ "type": "install_ruleset_request",
103
+ "attrs": {"absoluteURL": meta:rulesetURI, "rid": collection_rid}
104
+ })
105
+ event:send({
106
+ "eci": child,
107
+ "domain": "wrangler",
108
+ "type": "install_ruleset_request",
109
+ "attrs": {"absoluteURL": meta:rulesetURI, "rid": report_rid}
110
+ })
111
+ }
112
+ always {
113
+ ent:collection := child
114
+ raise collection_demo event "rooms_needed"
115
+ }
116
+ }
117
+
118
+ rule create_rooms {
119
+ select when collection_demo rooms_needed
120
+ foreach rooms setting(room)
121
+ always {
122
+ raise wrangler event "new_child_request" attributes room.put("collection_demo", "room")
123
+ }
124
+ }
125
+
126
+ // A room is set up: install the room ruleset, then ask it to join.
127
+ rule set_up_room {
128
+ select when wrangler child_initialized where event:attr("collection_demo") == "room"
129
+ pre {
130
+ child = event:attr("eci")
131
+ well_known = wrangler:picoQuery(ent:collection, "io.picolabs.subscription", "wellKnown_Rx"){"id"}
132
+ }
133
+ every {
134
+ event:send({
135
+ "eci": child,
136
+ "domain": "wrangler",
137
+ "type": "install_ruleset_request",
138
+ "attrs": {"absoluteURL": meta:rulesetURI, "rid": room_rid, "temperature": event:attr("temperature")}
139
+ })
140
+ event:send({
141
+ "eci": child,
142
+ "domain": "collection",
143
+ "type": "join_requested",
144
+ "attrs": {"wellKnown_Tx": well_known, "as": event:attr("as") || "member"}
145
+ })
146
+ }
147
+ }
148
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Collection: keeps a collection of other picos. Each member is a relationship
3
+ * in which this pico plays the role "collection" and the other pico plays
4
+ * "member". This ruleset only manages the collection: it accepts members,
5
+ * turns away requests in any other role, removes members, and raises
6
+ * collection:member_added and collection:member_removed. Other rulesets on this
7
+ * pico use the members; com.example.collection.report is one.
8
+ */
9
+ ruleset com.example.collection {
10
+ meta {
11
+ name "Collection"
12
+ description "Accepts member picos by relationship role and provides them to other rulesets."
13
+ author "PICOLABS"
14
+
15
+ use module io.picolabs.subscription alias subscription
16
+
17
+ provides members, rejections
18
+ shares members, rejections
19
+ }
20
+
21
+ global {
22
+ /**
23
+ * Every member: the relationships in which the other pico is a member.
24
+ * @returns Array of relationships (Id, Tx, Rx, Tx_role, Rx_role, ...)
25
+ */
26
+ members = function() {
27
+ subscription:established("Tx_role", "member")
28
+ }
29
+
30
+ /**
31
+ * Requests this collection turned away, oldest first.
32
+ * @returns Array of { name, role, time }
33
+ */
34
+ rejections = function() {
35
+ ent:rejections.defaultsTo([])
36
+ }
37
+ }
38
+
39
+ /**
40
+ * Accept a request to join as a member. Reject a request in any other role,
41
+ * and remember it.
42
+ */
43
+ rule accept_member {
44
+ select when wrangler inbound_pending_subscription_added
45
+ pre {
46
+ acceptable = event:attr("Rx_role") == "collection" && event:attr("Tx_role") == "member"
47
+ }
48
+ if acceptable then noop()
49
+ fired {
50
+ raise wrangler event "pending_subscription_approval" attributes event:attrs
51
+ }
52
+ else {
53
+ ent:rejections := rejections().append({
54
+ "name": event:attr("name"),
55
+ "role": event:attr("Tx_role"),
56
+ "time": time:now()
57
+ })
58
+ raise wrangler event "inbound_rejection" attributes event:attrs
59
+ raise collection event "member_rejected" attributes event:attrs
60
+ }
61
+ }
62
+
63
+ /**
64
+ * Remove a member. Only relationships with members can be removed this way.
65
+ * @attr Id String "the member's relationship id"
66
+ */
67
+ rule remove_member {
68
+ select when collection member_removal_requested
69
+ Id re#(.+)#
70
+ setting(id)
71
+ pre {
72
+ member = members().filter(function(bus) { bus{"Id"} == id }).head()
73
+ }
74
+ if member then noop()
75
+ fired {
76
+ raise wrangler event "subscription_cancellation" attributes {"Id": id}
77
+ }
78
+ }
79
+
80
+ rule member_added {
81
+ select when wrangler subscription_added
82
+ where event:attr("bus"){"Tx_role"} == "member"
83
+ always {
84
+ raise collection event "member_added" attributes event:attrs
85
+ }
86
+ }
87
+
88
+ rule member_removed {
89
+ select when wrangler subscription_removed
90
+ where event:attr("bus"){"Tx_role"} == "member"
91
+ always {
92
+ raise collection event "member_removed" attributes event:attrs
93
+ }
94
+ }
95
+ }
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Room report: uses com.example.collection as a module. It asks every member
3
+ * for its reading over the relationship, averages the temperatures, and shows
4
+ * them on a page. It knows nothing about how members join; that is the
5
+ * collection ruleset's job.
6
+ */
7
+ ruleset com.example.collection.report {
8
+ meta {
9
+ name "Room report"
10
+ description "Reports the temperature of every room in the collection."
11
+ author "PICOLABS"
12
+
13
+ use module com.example.collection alias collection
14
+ use module io.picolabs.subscription alias subscription
15
+ use module io.picolabs.xmlui alias ui
16
+
17
+ shares report, rejections, reportPage
18
+ }
19
+
20
+ global {
21
+ channel_tags = ["collection", "app"]
22
+ room_rid = "com.example.collection.room"
23
+
24
+ readingOf = function(bus) {
25
+ reading = subscription:queryOnSub(bus{"Id"}, room_rid, "reading")
26
+ row = {"Id": bus{"Id"}, "name": reading{"name"}, "temperature": reading{"temperature"}}
27
+ row
28
+ }
29
+
30
+ /**
31
+ * Every member's reading, and the average temperature.
32
+ * @returns Map { members, count, average }
33
+ */
34
+ report = function() {
35
+ rows = collection:members().map(readingOf)
36
+ temperatures = rows
37
+ .map(function(row) { row{"temperature"} })
38
+ .filter(function(t) { t.typeof() == "Number" })
39
+ average = temperatures.length() > 0
40
+ => math:round(temperatures.reduce(function(a, b) { a + b }, 0) / temperatures.length(), 1)
41
+ | null
42
+ result = {"members": rows, "count": rows.length(), "average": average}
43
+ result
44
+ }
45
+
46
+ /**
47
+ * Requests the collection turned away.
48
+ * @returns Array of { name, role, time }
49
+ */
50
+ rejections = function() {
51
+ collection:rejections()
52
+ }
53
+
54
+ /**
55
+ * The rooms in the collection and their temperatures.
56
+ * @view "Rooms"
57
+ */
58
+ reportPage = function() {
59
+ report_url = ui:query_url("report", meta:rid, meta:eci)
60
+ rejections_url = ui:query_url("rejections", meta:rid, meta:eci)
61
+ remove_url = ui:event_url("collection", "member_removal_requested")
62
+ <<
63
+ <Component name="ReportPage">
64
+ <DataSource id="report" url="#{report_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="3" />
65
+ <DataSource id="rejected" url="#{rejections_url}" headers="{appGlobals.auth}" pollIntervalInSeconds="3" />
66
+ <APICall id="remove" method="post" url="#{remove_url}" headers="{appGlobals.auth}" body="{$param}"
67
+ onSuccess="report.refetch()" />
68
+ <PicoTheme>
69
+ <Card title="Rooms"
70
+ subtitle="{report.value.count + ' rooms in the collection' + (report.value.average === null ? '' : ', averaging ' + report.value.average + ' F')}" />
71
+ <Table data="{report.value.members}">
72
+ <Column bindTo="name" header="Room" />
73
+ <Column bindTo="temperature" header="Temperature (F)" />
74
+ <Column header="">
75
+ <Button label="Remove" variant="outlined" onClick="remove.execute({Id: $item.Id})" />
76
+ </Column>
77
+ </Table>
78
+ <Card title="Turned away" subtitle="Requests to join in a role other than member." />
79
+ <Table data="{rejected}">
80
+ <Column bindTo="name" header="Pico" />
81
+ <Column bindTo="role" header="Asked to be" />
82
+ </Table>
83
+ </PicoTheme>
84
+ </Component>
85
+ >>
86
+ }
87
+ }
88
+
89
+ rule create_app_channel {
90
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
91
+ ui:create_app_channel(channel_tags, ["collection"], ["report", "rejections", "reportPage"], meta:rid)
92
+ }
93
+ }
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Room: a member pico. It has a temperature, joins a collection through the
3
+ * collection's well-known channel, and can leave and rejoin.
4
+ */
5
+ ruleset com.example.collection.room {
6
+ meta {
7
+ name "Room"
8
+ description "A pico with a temperature that joins a collection as a member."
9
+ author "PICOLABS"
10
+
11
+ use module io.picolabs.wrangler alias wrangler
12
+ use module io.picolabs.subscription alias subscription
13
+
14
+ shares reading, membership
15
+ }
16
+
17
+ global {
18
+ /**
19
+ * This room's name and temperature.
20
+ * @returns Map
21
+ */
22
+ reading = function() {
23
+ result = {"name": wrangler:name(), "temperature": ent:temperature}
24
+ result
25
+ }
26
+
27
+ /**
28
+ * The relationship with the collection, or null when this room isn't in one.
29
+ * @returns Map
30
+ */
31
+ membership = function() {
32
+ subscription:established("Tx_role", "collection").head()
33
+ }
34
+ }
35
+
36
+ rule installed {
37
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
38
+ if event:attr("temperature") then noop()
39
+ fired {
40
+ ent:temperature := event:attr("temperature").as("Number")
41
+ }
42
+ }
43
+
44
+ /**
45
+ * Set this room's temperature.
46
+ * @attr temperature Number "degrees F"
47
+ * @example "70" { "temperature": "70" }
48
+ */
49
+ rule new_temperature {
50
+ select when room new_temperature
51
+ temperature re#^(-?\d+(?:[.]\d+)?)$#
52
+ setting(temperature)
53
+ always {
54
+ ent:temperature := temperature.as("Number")
55
+ }
56
+ }
57
+
58
+ /**
59
+ * Ask to join a collection.
60
+ * @attr wellKnown_Tx String "the collection's well-known channel id"
61
+ * @attr as String optional "the role to ask for: member, unless you want to see a request turned away"
62
+ */
63
+ rule join {
64
+ select when collection join_requested
65
+ wellKnown_Tx re#(.+)#
66
+ setting(well_known)
67
+ always {
68
+ ent:collection_wellKnown := well_known
69
+ raise wrangler event "subscription" attributes {
70
+ "wellKnown_Tx": well_known,
71
+ "name": wrangler:name(),
72
+ "Rx_role": event:attr("as") || "member",
73
+ "Tx_role": "collection"
74
+ }
75
+ }
76
+ }
77
+
78
+ /**
79
+ * Leave the collection.
80
+ */
81
+ rule leave {
82
+ select when collection leave_requested
83
+ pre {
84
+ bus = membership()
85
+ }
86
+ if bus then noop()
87
+ fired {
88
+ raise wrangler event "subscription_cancellation" attributes {"Id": bus{"Id"}}
89
+ }
90
+ }
91
+
92
+ /**
93
+ * Join the last collection this room asked to join, again.
94
+ */
95
+ rule rejoin {
96
+ select when collection rejoin_requested where ent:collection_wellKnown
97
+ always {
98
+ raise collection event "join_requested" attributes {"wellKnown_Tx": ent:collection_wellKnown}
99
+ }
100
+ }
101
+ }
@@ -0,0 +1,6 @@
1
+ - Open **Rooms**: four rooms averaging 69.5 F, and Stranger under **Turned away**.
2
+ - To see the mesh the demo built, leave the **Try It!** tab and close the pico. The demo's child has six children: Rooms, Kitchen, Office, Garage, Bedroom, and Stranger.
3
+ - Click into each one and open its **Relationships** tab. Rooms has a relationship with each room, with Rooms in the role `collection` and the room in the role `member`. Each room has the same relationship, seen from its side. Stranger has none.
4
+ - Why was Stranger turned away? Read `accept_member` in `com.example.collection.krl`, then see how the bootstrap set Stranger up. (The cookbook has the answer.)
5
+ - On **Rooms**, click **Remove** next to a room, then look at that room's **Relationships** tab. The relationship is gone on both sides.
6
+ - On a room's **Testing** tab, raise `collection` `leave_requested`, then `collection` `rejoin_requested`, and watch the Rooms page.
@@ -0,0 +1,11 @@
1
+ # Echo demo
2
+
3
+ The hello world of events: send an event to a pico and get back the directive a rule answers with.
4
+
5
+ - Overview: [`docs/cookbook/echo/README.md`](../../docs/cookbook/echo/README.md) (on the docs site: https://docs.picolabs.io/#/cookbook/echo/)
6
+ - Instructions: [`docs/cookbook/echo/instructions.md`](../../docs/cookbook/echo/instructions.md)
7
+
8
+ | File | Shows |
9
+ |------|-------|
10
+ | `com.example.echo.krl` | Two rules that answer `echo:hello` and `echo:message` with a `say` directive, and a page that sends both |
11
+ | `com.example.echo.bootstrap.krl` | Sets up the demo on a new pico; the **Try It!** tab runs it |