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.
- package/README.md +11 -5
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
- package/demos/echo/com.example.echo.bootstrap.krl +10 -7
- package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
- package/demos/json_query/README.md +11 -0
- package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
- package/demos/json_query/com.example.json_query.krl +162 -0
- package/demos/json_query/try-it.md +5 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
- package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
- package/demos/try-it-order.json +1 -1
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
- package/dist/cli.js +5 -1
- package/dist/engineConfig.js +1 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +44 -12
- package/dist/internalAccess.js +110 -0
- package/dist/oauth/OAuthService.js +172 -10
- package/dist/oauth/acg.js +194 -24
- package/dist/oauth/cimd.js +381 -0
- package/dist/oauth/discovery.js +175 -0
- package/dist/runMcp.js +1 -1
- package/dist/server.js +197 -48
- package/dist/subtreeWrangler.js +8 -5
- package/dist/uiChannelPolicies.js +2 -0
- package/krl/io.picolabs.pds.krl +109 -21
- package/krl/io.picolabs.pico-engine-ui.krl +13 -7
- package/krl/io.picolabs.wrangler.krl +21 -9
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +3 -2
- package/mcp/docs/cookbook/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
- package/mcp/docs/cookbook/child_tasks/README.md +20 -0
- package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
- package/mcp/docs/cookbook/collection/README.md +21 -0
- package/mcp/docs/cookbook/collection/instructions.md +93 -0
- package/mcp/docs/cookbook/echo/README.md +19 -0
- package/mcp/docs/cookbook/echo/instructions.md +59 -0
- package/mcp/docs/cookbook/guard_rules/README.md +22 -0
- package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
- package/mcp/docs/cookbook/json_query/README.md +26 -0
- package/mcp/docs/cookbook/json_query/instructions.md +64 -0
- package/mcp/docs/cookbook/kblog/README.md +60 -0
- package/mcp/docs/cookbook/kblog/instructions.md +102 -0
- package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
- package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
- package/mcp/docs/cookbook/moving_picos/README.md +44 -0
- package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
- package/mcp/docs/cookbook/score_tracker/README.md +19 -0
- package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
- package/mcp/docs/cookbook/secrets/README.md +25 -0
- package/mcp/docs/cookbook/secrets/instructions.md +98 -0
- package/mcp/docs/cookbook/two_picos/README.md +20 -0
- package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
- package/mcp/docs/cookbook/xmlui/README.md +23 -0
- package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
- package/mcp/docs/developing/README.md +28 -0
- package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
- package/mcp/docs/developing/arrays-and-maps.md +77 -0
- package/mcp/docs/developing/converting-time-formats.md +28 -0
- package/mcp/docs/developing/cookies-and-redirects.md +81 -0
- package/mcp/docs/developing/decoding-form-data.md +67 -0
- package/mcp/docs/developing/engine-log-files.md +34 -0
- package/mcp/docs/developing/event-loop.md +77 -0
- package/mcp/docs/developing/events-from-email.md +80 -0
- package/mcp/docs/developing/initializing-entity-variables.md +83 -0
- package/mcp/docs/developing/mcp-ai-tools.md +98 -0
- package/mcp/docs/developing/misconceptions.md +467 -0
- package/mcp/docs/developing/names-and-scope.md +44 -0
- package/mcp/docs/developing/postman.md +159 -0
- package/mcp/docs/developing/querying-another-pico.md +47 -0
- package/mcp/docs/developing/singleton-picos.md +36 -0
- package/mcp/docs/developing/tabular-data.md +67 -0
- package/mcp/docs/developing/tips.md +251 -0
- package/mcp/docs/developing/webhook-signatures.md +56 -0
- package/mcp/docs/developing/workflow.md +106 -0
- package/mcp/docs/exp/README.md +46 -0
- package/mcp/docs/exp/event.md +110 -0
- package/mcp/docs/exp/query.md +94 -0
- package/mcp/docs/lessons/README.md +59 -0
- package/mcp/docs/lessons/events-and-queries.md +247 -0
- package/mcp/docs/lessons/gossip.md +28 -0
- package/mcp/docs/lessons/modules-and-apis.md +270 -0
- package/mcp/docs/lessons/pico-based-systems.md +470 -0
- package/mcp/docs/lessons/pico-state.md +267 -0
- package/mcp/docs/lessons/pico-views.md +290 -0
- package/mcp/docs/lessons/quickstart.md +157 -0
- package/mcp/docs/lessons/relationships.md +530 -0
- package/mcp/docs/lessons/scatter-gather.md +362 -0
- package/mcp/docs/pico-engine.md +7 -5
- package/mcp/docs/pico-overview.md +3 -3
- package/mcp/docs/wrangler/README.md +47 -0
- package/mcp/docs/wrangler/channels.md +235 -0
- package/mcp/docs/wrangler/oauth.md +56 -0
- package/mcp/docs/wrangler/pds.md +423 -0
- package/mcp/docs/wrangler/portable-subtree.md +44 -0
- package/mcp/docs/wrangler/relationships.md +297 -0
- package/mcp/docs/wrangler/wrangler.md +253 -0
- package/mcp/docs/wrangler/xmlui.md +60 -0
- package/mcp/engineClient.js +57 -5
- package/mcp/mcpScopes.js +118 -0
- package/mcp/meshHttp.js +151 -45
- package/mcp/runStdio.js +2 -0
- package/mcp/subtreeTools.js +184 -0
- package/mcp/tryItTools.js +202 -0
- package/package.json +14 -8
- package/public/pico-engine-ui.js +26 -26
- package/src/cli.ts +6 -2
- package/src/engineConfig.ts +5 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -430
- package/src/internalAccess.ts +127 -0
- package/src/oauth/OAuthService.ts +243 -11
- package/src/oauth/acg.ts +289 -25
- package/src/oauth/cimd.ts +508 -0
- package/src/oauth/discovery.ts +233 -0
- package/src/runMcp.ts +3 -1
- package/src/server.ts +252 -52
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Two picos talking
|
|
2
|
+
|
|
3
|
+
Picos talk to each other over **relationships**. A relationship is a pair of channels, one on each pico, made for that connection and labeled with each side's role. This demo has two picos. Alice is an *answerer* who knows some facts about herself. Bob is an *asker*. Bob asks Alice for a relationship, Alice accepts, and Bob asks her questions by querying her over it.
|
|
4
|
+
|
|
5
|
+
Neither pico needs the other's family channels or knows where it lives in the pico tree. Bob reaches Alice only through the relationship, and only for what Alice's ruleset shares.
|
|
6
|
+
|
|
7
|
+
To run it, follow the [instructions](/cookbook/two_picos/instructions).
|
|
8
|
+
|
|
9
|
+
## The rulesets
|
|
10
|
+
|
|
11
|
+
| Ruleset | File | What it shows |
|
|
12
|
+
|---------|------|---------------|
|
|
13
|
+
| Answerer (Alice) | [`com.example.two_picos.answerer.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.answerer.krl) | Accepting relationship requests by role (`inbound_pending_subscription_added`, `pending_subscription_approval`), a shared `answer` function, and a page to teach Alice facts |
|
|
14
|
+
| Asker (Bob) | [`com.example.two_picos.asker.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.asker.krl) | Asking for a relationship through a well-known channel (`wrangler:subscription`), reacting to `subscription_added`, and querying the other side with `subscription:queryOnSub`. Has a conversation page |
|
|
15
|
+
| Bootstrap | [`com.example.two_picos.bootstrap.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.bootstrap.krl) | Creates Alice and Bob as children, installs their rulesets, and introduces Bob to Alice's well-known channel. The developer UI's **Try It!** tab runs it |
|
|
16
|
+
|
|
17
|
+
## What you need
|
|
18
|
+
|
|
19
|
+
- A running pico engine (1.9.4 or later for the pages, which use the shared `PicoTheme` component).
|
|
20
|
+
- `io.picolabs.xmlui` on Alice and Bob for their pages. The bootstrap installs it.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Two picos talking: instructions
|
|
2
|
+
|
|
3
|
+
These steps use the developer UI of a running engine at `http://localhost:3000`. Replace that with your engine's URL. See the [overview](/cookbook/two_picos/) for what the demo shows.
|
|
4
|
+
|
|
5
|
+
## The quick way: Try It!
|
|
6
|
+
|
|
7
|
+
On the root pico in the developer UI, open the **Try It!** tab, click **Two picos talking**, then **Run in a new child pico**. The bootstrap creates two children, Alice and Bob, and introduces them. When it shows **ready**, Bob has already asked his first question. Open **Bob's conversation** and **What Alice knows**.
|
|
8
|
+
|
|
9
|
+
## By hand
|
|
10
|
+
|
|
11
|
+
1. Create two child picos, Alice and Bob.
|
|
12
|
+
2. On each, install `io.picolabs.xmlui` from the engine: `http://localhost:3000/krl/io.picolabs.xmlui.krl`.
|
|
13
|
+
3. On Alice, install `http://localhost:3000/krl/demos/two_picos/com.example.two_picos.answerer.krl`.
|
|
14
|
+
4. On Bob, install `http://localhost:3000/krl/demos/two_picos/com.example.two_picos.asker.krl`.
|
|
15
|
+
5. Find Alice's well-known channel: on Alice's **Channels** tab, it is the channel tagged `wellknown_rx, tx_rx`. Copy its id.
|
|
16
|
+
6. On Bob's **Testing** tab, raise `two_picos` `introduce` with `wellKnown_Tx` set to that id.
|
|
17
|
+
7. Both picos' **Relationships** tabs now show the relationship, and Bob has asked about Alice's favorite color. Open Bob's page on his `two_picos, asker` channel and Alice's on her `two_picos, answerer` channel (**View** on the **Rulesets** tab).
|
|
18
|
+
|
|
19
|
+
## Try it
|
|
20
|
+
|
|
21
|
+
- On Bob's page, ask about `cat`, `hometown`, or `name`. Each answer comes from Alice's pico.
|
|
22
|
+
- Ask about something Alice doesn't know, such as `favorite food`. She says she doesn't know it yet.
|
|
23
|
+
- On Alice's page, teach her that fact, then ask Bob to ask again.
|
|
24
|
+
- Look at the **Relationships** tab on each pico. Bob's role is `asker`, Alice's is `answerer`, and each side has its own channel for the other.
|
|
25
|
+
|
|
26
|
+
## How it works
|
|
27
|
+
|
|
28
|
+
**Bob asks for a relationship.** Every pico has a well-known channel that accepts only relationship requests. Given Alice's, Bob asks for a relationship and names both roles:
|
|
29
|
+
|
|
30
|
+
```krl
|
|
31
|
+
raise wrangler event "subscription" attributes {
|
|
32
|
+
"wellKnown_Tx": well_known,
|
|
33
|
+
"name": "Bob and Alice",
|
|
34
|
+
"Rx_role": "asker",
|
|
35
|
+
"Tx_role": "answerer"
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**Alice accepts.** The request arrives at Alice as `wrangler:inbound_pending_subscription_added`, with the roles swapped to her point of view: her `Rx_role` is `answerer`. She accepts only requests that cast her in that role:
|
|
40
|
+
|
|
41
|
+
```krl
|
|
42
|
+
rule accept_asker {
|
|
43
|
+
select when wrangler inbound_pending_subscription_added
|
|
44
|
+
where event:attr("Rx_role") == "answerer"
|
|
45
|
+
always {
|
|
46
|
+
raise wrangler event "pending_subscription_approval" attributes event:attrs
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Bob hears back.** When Alice accepts, Bob's wrangler raises `wrangler:subscription_added`. Bob's `connected` rule checks that the other side is an answerer, tells the parent pico, and asks a first question.
|
|
52
|
+
|
|
53
|
+
**Bob queries Alice.** `ask` finds the relationship by role and calls Alice's shared `answer` function over it:
|
|
54
|
+
|
|
55
|
+
```krl
|
|
56
|
+
bus = subscription:established("Tx_role", "answerer").head()
|
|
57
|
+
reply = subscription:queryOnSub(bus{"Id"}, answerer_rid, "answer", {"question": question})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The query goes to the channel Alice made for Bob when she accepted. Bob uses that channel, not Alice's family channel or her app channel. Relationship channels allow every event and query, so what Bob can do to Alice is up to the rulesets she has installed.
|
|
61
|
+
|
|
62
|
+
**The bootstrap.** It creates Alice and Bob with `new_child_request` and installs their rulesets when `child_initialized` arrives. Each child sends `two_picos:child_ready` to the parent when its ruleset is installed. When both are ready, the parent queries Alice's well-known channel id (`wrangler:picoQuery(alice, "io.picolabs.subscription", "wellKnown_Rx")`) and sends Bob `two_picos:introduce`. That starts everything above.
|
|
63
|
+
|
|
64
|
+
## Change it and watch
|
|
65
|
+
|
|
66
|
+
The **Try It!** window lists each file with its path on disk. Edit a file there, click **Flush**, and use the pages again.
|
|
67
|
+
|
|
68
|
+
- In `com.example.two_picos.answerer.krl`, change how Alice answers. For example, make `answer` return `known.uc()`.
|
|
69
|
+
- Change `initial_facts`. The facts are set when the answerer is installed, so run the demo again to see new ones, or teach them on Alice's page.
|
|
70
|
+
- In `com.example.two_picos.asker.krl`, change the first question in `connected` from `favorite color` to another topic, and run the demo again.
|
|
71
|
+
- Let Bob teach Alice. Add a rule to `com.example.two_picos.asker.krl` that sends her an event over the relationship:
|
|
72
|
+
|
|
73
|
+
```krl
|
|
74
|
+
rule teach {
|
|
75
|
+
select when two_picos teach
|
|
76
|
+
pre {
|
|
77
|
+
bus = subscription:established("Tx_role", "answerer").head()
|
|
78
|
+
}
|
|
79
|
+
if bus then event:send({
|
|
80
|
+
"eci": bus{"Tx"},
|
|
81
|
+
"domain": "two_picos",
|
|
82
|
+
"type": "fact_learned",
|
|
83
|
+
"attrs": {"topic": event:attr("topic"), "value": event:attr("value")}
|
|
84
|
+
})
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Flush it, raise `two_picos` `teach` on Bob's **Testing** tab with a `topic` and `value`, and Alice's page shows the new fact.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Pico views
|
|
2
|
+
|
|
3
|
+
Seven small rulesets that serve [XMLUI](https://xmlui.org) pages from a pico. Each one adds one idea, from a static page to a view that shows another pico's data. They are also the test fixtures for the engine's view routes.
|
|
4
|
+
|
|
5
|
+
Read [Pico views](/pico-views) for how views work. To install and open these, follow the [instructions](/cookbook/xmlui/instructions).
|
|
6
|
+
|
|
7
|
+
## The rulesets
|
|
8
|
+
|
|
9
|
+
| Ruleset | File | What it shows |
|
|
10
|
+
|---------|------|---------------|
|
|
11
|
+
| Hello | [`com.example.hello.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.hello.krl) | A `@view` function and nothing else |
|
|
12
|
+
| Favorite color | [`com.example.fav_color.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.fav_color.krl) | Reading with `ui:query` and writing with `ui:event`, then refreshing |
|
|
13
|
+
| Guestbook | [`com.example.guestbook.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.guestbook.krl) | An app channel created on install with `ui:create_app_channel` |
|
|
14
|
+
| Contacts | [`com.example.contacts.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.contacts.krl) | A list page and a detail page (`/contact/:id`), seeded with two contacts |
|
|
15
|
+
| Thermostat | [`com.example.thermostat.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.thermostat.krl) | Two channels with different policies (viewer and admin), an app `@component`, and the shared `PicoSettings`, `PicoThemeField`, and `PicoTheme` components |
|
|
16
|
+
| Thermostat bootstrap | [`com.example.thermostat.bootstrap.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.thermostat.bootstrap.krl) | Sets up the whole Thermostat demo on a new pico. The developer UI's **Try It!** tab runs it |
|
|
17
|
+
| Temperature sensors (data) | [`temperature_sensors.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/temperature_sensors.krl) | Sample readings on a data pico |
|
|
18
|
+
| Temperature sensors (view) | [`com.example.temperature_sensors_view.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.temperature_sensors_view.krl) | A view on one pico over data on another, reached through a relationship |
|
|
19
|
+
|
|
20
|
+
## What you need
|
|
21
|
+
|
|
22
|
+
- A running pico engine. Components (`@component` and the shared `Pico*` components, used by Thermostat) need pico-engine 1.9.4 or later.
|
|
23
|
+
- `io.picolabs.xmlui` installed on each pico that serves a view. The engine ships it at `/krl/io.picolabs.xmlui.krl` but does not install it anywhere by default.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Pico views: instructions
|
|
2
|
+
|
|
3
|
+
These steps use the developer UI of a running engine at `http://localhost:3000`. Replace that with your engine's URL. See the [overview](/cookbook/xmlui/) for what each ruleset shows.
|
|
4
|
+
|
|
5
|
+
## The quick way: Try It!
|
|
6
|
+
|
|
7
|
+
Open the root pico in the developer UI and choose the **Try It!** tab. (Operators can show the tab on every pico, or hide it, with `show_tryit_menu` in the engine config.) Click **Thermostat**, then **Run in a new child pico**. The tab creates a child pico and installs `com.example.thermostat.bootstrap` on it. That one ruleset installs `io.picolabs.xmlui` and the thermostat, and records three readings. When the demo shows **ready**, open the dashboard links. **Delete Child** deletes the child pico.
|
|
8
|
+
|
|
9
|
+
The same window shows **the code**: the bootstrap and the rulesets it installed, each with its path on the engine's machine. Change one. For example, in `com.example.thermostat.krl` change `ent:threshold.defaultsTo(80)` to `65`, click **Flush**, and reload the dashboard: it says "Alert above 65 F". To contribute a change, make it in a clone of the [pico-engine repository](https://github.com/Picolab/pico-engine) and open a pull request.
|
|
10
|
+
|
|
11
|
+
The steps below do the same by hand, for every demo.
|
|
12
|
+
|
|
13
|
+
## 1. Prepare a pico
|
|
14
|
+
|
|
15
|
+
1. Open the developer UI and sign in.
|
|
16
|
+
2. Pick the pico that will serve the views. A new child pico keeps the demos apart from everything else.
|
|
17
|
+
3. On its **Rulesets** tab, install `io.picolabs.xmlui` from the engine:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
http://localhost:3000/krl/io.picolabs.xmlui.krl
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 2. Install a demo
|
|
24
|
+
|
|
25
|
+
On the same **Rulesets** tab, install the demo by URL. Use the raw GitHub file:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
https://raw.githubusercontent.com/Picolab/pico-engine/master/demos/xmlui/com.example.hello.krl
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
or a `file://` URL to your checkout of the repository:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
file:///path/to/pico-engine/demos/xmlui/com.example.hello.krl
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Install the others the same way: `com.example.fav_color.krl`, `com.example.guestbook.krl`, `com.example.contacts.krl`, `com.example.thermostat.krl`.
|
|
38
|
+
|
|
39
|
+
## 3. Open it
|
|
40
|
+
|
|
41
|
+
A ruleset with a `@view` function has a **View** button on the Rulesets tab. Click it, pick a channel, and open the app. The page is at:
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
http://localhost:3000/ui/<eci>/<rid>/
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`http://localhost:3000/ui/<eci>/` lists every app that channel can open.
|
|
48
|
+
|
|
49
|
+
The channel must allow `io.picolabs.xmlui` / `file` and the view's functions. Guestbook, Contacts, and Thermostat create channels like that when they are installed. Use those channels (tags `guestbook, app`, `contacts, app`, `thermostat, viewer`, `thermostat, admin`).
|
|
50
|
+
|
|
51
|
+
## 4. Try each demo
|
|
52
|
+
|
|
53
|
+
**Hello.** The page shows a heading and the ruleset id. There is nothing to click.
|
|
54
|
+
|
|
55
|
+
**Favorite color.** Enter a color such as `#3366cc` and submit. The card shows the color you picked. Reload the page: the pico remembers it.
|
|
56
|
+
|
|
57
|
+
**Guestbook.** Open it on the `guestbook, app` channel. Sign with a name and a message. The table refreshes with your entry.
|
|
58
|
+
|
|
59
|
+
**Contacts.** Open it on the `contacts, app` channel. It starts with Ada Lovelace and Grace Hopper. Add a contact, then click a name to open its detail page and add a note.
|
|
60
|
+
|
|
61
|
+
**Thermostat.** It has no readings until you send some. On the **Testing** tab, raise `thermostat` `new_reading` with `temperature` set to `72`, then `75`. Then open it on each of its channels:
|
|
62
|
+
|
|
63
|
+
- `thermostat, viewer` shows only the Dashboard. The Settings page is not reachable on this channel.
|
|
64
|
+
- `thermostat, admin` shows Dashboard and Settings. Settings changes the alert threshold.
|
|
65
|
+
|
|
66
|
+
On the Dashboard, **Display** opens a theme picker built from the shared `PicoSettings` and `PicoThemeField` components. The readings table is the ruleset's own `ReadingHistory` component.
|
|
67
|
+
|
|
68
|
+
**Temperature sensors (two picos).**
|
|
69
|
+
|
|
70
|
+
1. Create two child picos, one for the data and one for the view.
|
|
71
|
+
2. On the data pico, install `temperature_sensors.krl`.
|
|
72
|
+
3. On the view pico, install `io.picolabs.xmlui` and `com.example.temperature_sensors_view.krl`.
|
|
73
|
+
4. Create a relationship between the two picos. On the view pico's **Relationships** tab, note the relationship's `Id`. It is the same on both picos.
|
|
74
|
+
5. On the view pico, raise `temperature_sensors_view` `link_data_pico` with `relationship_id` set to that `Id`.
|
|
75
|
+
6. Open the view on its `temperature_sensors_view, app` channel. The table shows the data pico's readings.
|
|
76
|
+
|
|
77
|
+
## If something doesn't load
|
|
78
|
+
|
|
79
|
+
| Symptom | Check |
|
|
80
|
+
|---------|-------|
|
|
81
|
+
| HTTP 403 | The channel's query policy does not allow `io.picolabs.xmlui` / `file`, or the view function |
|
|
82
|
+
| HTTP 404, or a component not found | `io.picolabs.xmlui` is not installed on this pico, or the function is not a `@view` or `@component` the channel allows |
|
|
83
|
+
| The page loads but shows no data | The channel does not allow the page's queries or events, or (on an OAuth mesh) no access token is set |
|
|
84
|
+
| A change to the KRL doesn't show | Flush the ruleset on the Rulesets tab, then reload the page |
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Developing with Picos
|
|
2
|
+
|
|
3
|
+
Practical notes for people writing KRL and running picos on the pico engine: how a ruleset gets from your editor into a running pico, what the engine does when an event arrives, and the mistakes that cost the most time.
|
|
4
|
+
|
|
5
|
+
If you're new, start with the [Programming lessons](/lessons/), which build a working system step by step. Come back here when you want the "why did that happen?" and "how do I set things up?" answers.
|
|
6
|
+
|
|
7
|
+
## In this section
|
|
8
|
+
|
|
9
|
+
1. [Programming Workflow](/developing/workflow): develop, build, deploy, test, and release a ruleset.
|
|
10
|
+
2. [Event Loop Introduction](/developing/event-loop): the five phases a pico goes through for every event, and why rule order can surprise you.
|
|
11
|
+
3. [Tips](/developing/tips): engine setup, hosting and flushing rulesets, `krl-check`, and short technique tips (data, HTTP, picos working together).
|
|
12
|
+
4. [Event and Query URLs with Postman](/developing/postman): building Sky event and query requests in Postman (or `curl`).
|
|
13
|
+
5. [KRL misconceptions and common errors](/developing/misconceptions): where habits from other languages mislead, and the typos that are hard to see.
|
|
14
|
+
6. [Webhook signatures](/developing/webhook-signatures): check a Square-style signature over the raw body.
|
|
15
|
+
7. [AI tools over MCP](/developing/mcp-ai-tools): connect Claude, or another remote MCP client, to a channel or a mesh.
|
|
16
|
+
|
|
17
|
+
## Elsewhere in the docs
|
|
18
|
+
|
|
19
|
+
- [Programming lessons](/lessons/): hands-on lessons from the Quickstart to scatter-gather.
|
|
20
|
+
- [KRL manual](/krl/): the language and its libraries.
|
|
21
|
+
- [Event Exchange Protocol](/exp/): the Sky event and query APIs.
|
|
22
|
+
- [Cookbook](/cookbook/): runnable demos from the **Try It!** tab.
|
|
23
|
+
|
|
24
|
+
The engine listens on port 3000 by default, so the examples here use `http://localhost:3000`. Change that if you've configured another port or public URL (see the [operator guide](/pico-engine)).
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
<small>Section intro for pages ported from the Pico Labs wiki (Programming Workflow, Event Loop Introduction, Developer Tips, Event and Query URLs with Postman, KRL misconceptions, and the KRL Cookbook tips), updated for this engine.</small>
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Accepting relationship requests
|
|
2
|
+
|
|
3
|
+
When another pico asks for a relationship, the request waits on the receiving pico (its **Relationships** tab lists it) until something approves it. Here are three ways to approve requests automatically. The examples share one setup: a list pico asks participant picos to join it, in the role `participant list` for itself and `participant` for them.
|
|
4
|
+
|
|
5
|
+
## A rule that approves
|
|
6
|
+
|
|
7
|
+
On each participant:
|
|
8
|
+
|
|
9
|
+
```krl
|
|
10
|
+
rule accept_list {
|
|
11
|
+
select when wrangler inbound_pending_subscription_added
|
|
12
|
+
where event:attr("Rx_role") == "participant"
|
|
13
|
+
&& event:attr("Tx_role") == "participant list"
|
|
14
|
+
always {
|
|
15
|
+
raise wrangler event "pending_subscription_approval" attributes event:attrs
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Passing the event's attributes along tells wrangler which request to approve. Roles arrive from the receiving pico's point of view: `Rx_role` is this pico's, and `Tx_role` is the other pico's.
|
|
21
|
+
|
|
22
|
+
Don't approve every request. A rule without a `where` accepts a relationship with any pico that has your well-known channel. Accept only what you expect: the right roles, a request from your parent, a request that carries a shared secret. To refuse, raise `wrangler:inbound_rejection` with the same attributes. The [Collection](/cookbook/collection/) demo does both, and remembers whom it turned away.
|
|
23
|
+
|
|
24
|
+
## Wrangler's auto-accept configuration
|
|
25
|
+
|
|
26
|
+
Without writing a rule, give the participant a pattern to accept:
|
|
27
|
+
|
|
28
|
+
```krl
|
|
29
|
+
raise wrangler event "autoAcceptConfigUpdate" attributes {
|
|
30
|
+
"config": {"configName": "lists", "entries": {"Tx_role": ["^participant list$"]}}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Each entry maps an attribute of the request, as the participant sees it, to a list of regular expressions. A request that matches any of them is approved. Send the same event with `"delete": true` and the `configName` to remove it. `autoAcceptConfig()`, shared by `io.picolabs.subscription`, shows what is set. You can also send this event from the pico's **Testing** tab.
|
|
35
|
+
|
|
36
|
+
## Accept later, by installing a ruleset
|
|
37
|
+
|
|
38
|
+
If a request arrived before there was anything to approve it, install a ruleset that approves it and then removes itself:
|
|
39
|
+
|
|
40
|
+
```krl
|
|
41
|
+
ruleset acceptance {
|
|
42
|
+
meta {
|
|
43
|
+
use module io.picolabs.subscription alias subs
|
|
44
|
+
}
|
|
45
|
+
rule initialize {
|
|
46
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
47
|
+
pre {
|
|
48
|
+
s = subs:inbound("Tx_role", "participant list")
|
|
49
|
+
.filter(function(i) { i{"Rx_role"} == "participant" })
|
|
50
|
+
.head()
|
|
51
|
+
}
|
|
52
|
+
if s then noop()
|
|
53
|
+
fired {
|
|
54
|
+
raise wrangler event "pending_subscription_approval" attributes s
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
raise wrangler event "uninstall_ruleset_request" attributes {"rid": meta:rid}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
It looks for a pending request from a participant list, approves it, and uninstalls itself either way. This is handy when a parent asked many children to join before they could accept: install it on each child.
|
|
64
|
+
|
|
65
|
+
*From the Pico Labs KRL Cookbook pages "Automatic Replies to Subscription Requests" and "Accepting a subscription offer by installing a ruleset".*
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Arrays and maps
|
|
2
|
+
|
|
3
|
+
KRL has no `for` loop in expressions. Array operators do the same work: `map`, `filter`, `reduce`, `sort`, and the others in [Array operators](/krl/krl-expression-language/operators/array-operators). Here are a few patterns that come up often.
|
|
4
|
+
|
|
5
|
+
## Loop with `reduce`
|
|
6
|
+
|
|
7
|
+
To repeat a step a fixed number of times, `reduce` over a range and carry the state in the accumulator. This converts a number to an 8-byte array, high byte first, the way this JavaScript does:
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
for (var index = 0; index < byteArray.length; index++) {
|
|
11
|
+
var byte = long & 0xff;
|
|
12
|
+
byteArray[index] = byte;
|
|
13
|
+
long = (long - byte) / 256;
|
|
14
|
+
}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```krl
|
|
18
|
+
toByteArray = function(str) {
|
|
19
|
+
1.range(8)
|
|
20
|
+
.reduce(function(a, i) {
|
|
21
|
+
[a[0].append(a[1] % 256), math:int(a[1] / 256)]
|
|
22
|
+
}, [[], str.as("Number")])
|
|
23
|
+
.head()
|
|
24
|
+
.reverse()
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`1.range(8)` is `[1, 2, ... 8]`. It only counts; the function doesn't use `i`. The accumulator is a pair: the bytes so far, and what's left of the number. Each step appends the low byte and divides by 256. At the end, `head()` takes the bytes and `reverse()` puts the high byte first. `toByteArray("1551127401")` is `[0,0,0,0,92,116,83,105]`.
|
|
29
|
+
|
|
30
|
+
Add `.klog("step")` inside the function to watch the accumulator change on each step.
|
|
31
|
+
|
|
32
|
+
The inverse is one `reduce`. With no initial value, it starts from the first element:
|
|
33
|
+
|
|
34
|
+
```krl
|
|
35
|
+
fromByteArray = function(bytes) {
|
|
36
|
+
bytes.reduce(function(a, b) { a * 256 + b })
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Flatten an array of arrays
|
|
41
|
+
|
|
42
|
+
```krl
|
|
43
|
+
[[1, 2, 3], [4, 5, 6], [7, 8, 9]].reduce(function(a, b) { a.append(b) }, [])
|
|
44
|
+
// [1, 2, 3, 4, 5, 6, 7, 8, 9]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Sort an array of maps
|
|
48
|
+
|
|
49
|
+
`sort` takes a comparison function. A function that returns one, for a given key, reads well:
|
|
50
|
+
|
|
51
|
+
```krl
|
|
52
|
+
by = function(key) {
|
|
53
|
+
function(a, b) { a{key}.encode() cmp b{key}.encode() }
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`wrangler:channels().sort(by("id"))` reads "my channels, sorted by id". `cmp` compares strings, and `encode()` turns any value into a string, so `by` works whatever the values are. For numbers, compare them as numbers instead: `people.sort(function(a, b) { a{"born"} <=> b{"born"} })`.
|
|
58
|
+
|
|
59
|
+
For a primary and a secondary key:
|
|
60
|
+
|
|
61
|
+
```krl
|
|
62
|
+
by = function(key1, key2) {
|
|
63
|
+
key2 =>
|
|
64
|
+
function(a, b) {
|
|
65
|
+
a{key1}.encode() cmp b{key1}.encode() ||
|
|
66
|
+
a{key2}.encode() cmp b{key2}.encode()
|
|
67
|
+
}
|
|
68
|
+
|
|
|
69
|
+
function(a, b) { a{key1}.encode() cmp b{key1}.encode() }
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`||` stops at the first comparison that isn't zero, so the second key only breaks ties. `by("last", "first")` sorts by last name, then first name, and `by` still works with one key.
|
|
74
|
+
|
|
75
|
+
A key can also be a path, such as `by(["meta", "flushed"])`, because `a{["meta", "flushed"]}` looks up a nested value.
|
|
76
|
+
|
|
77
|
+
*From the Pico Labs KRL Cookbook pages "Looping using the reduce operator", "Flatten an Array of Arrays", and "Sorting an Array of Maps".*
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Converting time formats
|
|
2
|
+
|
|
3
|
+
The [time library](/krl/libraries/time) works with ISO 8601 / RFC 3339 times such as `2011-09-21T15:02:01-07:00`. Other formats need converting first. RSS feeds, for example, give dates like `Wed, 21 Sep 2011 15:02:01 -0700` (RFC 2822), and `time:new` rejects them: `time:new was given an invalid date string`.
|
|
4
|
+
|
|
5
|
+
This function rearranges the parts:
|
|
6
|
+
|
|
7
|
+
```krl
|
|
8
|
+
mon2num = {
|
|
9
|
+
"Jan": "01", "Feb": "02", "Mar": "03", "Apr": "04", "May": "05", "Jun": "06",
|
|
10
|
+
"Jul": "07", "Aug": "08", "Sep": "09", "Oct": "10", "Nov": "11", "Dec": "12"
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
rss2krlTime = function(pubDate) {
|
|
14
|
+
tarr = pubDate.split(re# #)
|
|
15
|
+
tzoff = tarr[5].replace(re#(\d\d)$#, ":$1")
|
|
16
|
+
tarr[3] + "-" + mon2num{tarr[2]} + "-" + tarr[1] + "T" + tarr[4] + tzoff
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`split` gives `["Wed,", "21", "Sep", "2011", "15:02:01", "-0700"]`. The offset `-0700` becomes `-07:00`, and `+0530` becomes `+05:30`. Then the time library can format it:
|
|
21
|
+
|
|
22
|
+
```krl
|
|
23
|
+
time:strftime(rss2krlTime("Wed, 21 Sep 2011 15:02:01 -0700"), "%b %d %Y") // "Sep 21 2011"
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
This expects a two-digit day, as RSS feeds use. For a feed that writes `1 Sep`, pad the day first, for example with `tarr[1].length() == 1 => "0" + tarr[1] | tarr[1]`.
|
|
27
|
+
|
|
28
|
+
*From the Pico Labs KRL Cookbook page "Converting Time Formats" (originally by Ed Orcutt). The time-zone handling here also covers offsets that aren't whole hours.*
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Cookies and redirects
|
|
2
|
+
|
|
3
|
+
Two directive names are special. When a rule sends one in response to an event raised over HTTP, the engine turns it into part of the HTTP response.
|
|
4
|
+
|
|
5
|
+
## Set a cookie: `_cookie`
|
|
6
|
+
|
|
7
|
+
```krl
|
|
8
|
+
rule set_cookie {
|
|
9
|
+
select when cookie needed
|
|
10
|
+
pre {
|
|
11
|
+
eci = wrangler:channels(["wellKnown_Rx", "Tx_Rx"]).head(){"id"} || meta:eci
|
|
12
|
+
}
|
|
13
|
+
send_directive("_cookie", {"cookie": <<wellKnown_Rx=#{eci}; Path=/sky>>})
|
|
14
|
+
}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The engine adds `Set-Cookie: wellKnown_Rx=<eci>; Path=/sky` to the response, and the browser sends the cookie back with later requests to the same engine. This one shares the pico's well-known channel, so other picos reached from the same browser could offer it a relationship. The ruleset uses `io.picolabs.wrangler` as a module.
|
|
18
|
+
|
|
19
|
+
## Read one cookie
|
|
20
|
+
|
|
21
|
+
`_headers` does not include the `Cookie` header. Read one cookie by name:
|
|
22
|
+
|
|
23
|
+
```krl
|
|
24
|
+
eci = http:cookie("wellKnown_Rx")
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
That is `"abc123"` when the browser sent `Cookie: wellKnown_Rx=abc123`. A cookie that was not sent is `null`. The engine's own session and ceremony cookies are not available to rulesets. `_cookie` and `_redirect` are unchanged: they still set the response.
|
|
28
|
+
|
|
29
|
+
## Redirect: `_redirect`
|
|
30
|
+
|
|
31
|
+
```krl
|
|
32
|
+
send_directive("_redirect", {"url": "https://picolabs.io/"})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The engine answers the event with HTTP 302 and that URL as the `Location`.
|
|
36
|
+
|
|
37
|
+
## A URL shortener
|
|
38
|
+
|
|
39
|
+
Together with a channel per link, `_redirect` makes a URL shortener. Each link gets its own channel, whose policy allows only the event that follows it. The channel id is the short URL:
|
|
40
|
+
|
|
41
|
+
```krl
|
|
42
|
+
ruleset s {
|
|
43
|
+
meta {
|
|
44
|
+
use module io.picolabs.wrangler alias wrangler
|
|
45
|
+
provides u
|
|
46
|
+
}
|
|
47
|
+
global {
|
|
48
|
+
u = function(eci) {
|
|
49
|
+
<<#{meta:host}/sky/event/#{eci}/none/s/u>>
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
rule recordShortcut {
|
|
53
|
+
select when s u
|
|
54
|
+
url re#(.+)# setting(url)
|
|
55
|
+
pre {
|
|
56
|
+
tag = event:attr("tag").lc().replace(re#[^a-z0-9_.-]#g, "-")
|
|
57
|
+
eid = tag => tag | "none"
|
|
58
|
+
}
|
|
59
|
+
every {
|
|
60
|
+
wrangler:createChannel(
|
|
61
|
+
[eid, "s"],
|
|
62
|
+
{"allow": [{"domain": "s", "name": "u"}], "deny": []},
|
|
63
|
+
{"allow": [], "deny": [{"rid": "*", "name": "*"}]}
|
|
64
|
+
) setting(channel)
|
|
65
|
+
send_directive("shortcut registered", {"tag": tag, "eci": channel{"id"}, "shortcut": u(channel{"id"}), "url": url})
|
|
66
|
+
}
|
|
67
|
+
fired {
|
|
68
|
+
ent:shortcuts{channel{"id"}} := url
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
rule redirectShortcut {
|
|
72
|
+
select when s u
|
|
73
|
+
where event:attr("url").isnull()
|
|
74
|
+
send_directive("_redirect", {"url": ent:shortcuts{meta:eci}})
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Another ruleset uses it as a module. It registers a link with `raise s event "u" attributes {"url": long_url, "tag": "docs"}`, then finds the channel with `wrangler:channels(["docs", "s"]).head()` and the short form with `s:u(eci)`. Opening the short URL redirects to the long one. The short URL can only raise `s:u`, and queries on it are all denied. Short links are handy in QR codes, which get smaller as the URL does.
|
|
80
|
+
|
|
81
|
+
*From the Pico Labs KRL Cookbook pages "Setting and reading cookies" and "Ruleset that provides a general purpose URL shortener".*
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Decoding form-encoded data
|
|
2
|
+
|
|
3
|
+
Form-encoded content, such as `q=5&value=%20space%20`, sometimes arrives as a single string: in a webhook body, a stored URL, or a query string you built. A chain of operators turns it into a map.
|
|
4
|
+
|
|
5
|
+
## Names and values
|
|
6
|
+
|
|
7
|
+
```krl
|
|
8
|
+
nv_split = function(x) { x.extract(re#([^=]*)=?(.*)#) } // "n=v" -> ["n", "v"]
|
|
9
|
+
frst = function(a) { a.head() }
|
|
10
|
+
dup_1st = function(v) { v[0][1] }
|
|
11
|
+
|
|
12
|
+
decodeContent = function(content) {
|
|
13
|
+
content // "n0=v0&n1=v1&..."
|
|
14
|
+
.split(re#&#) // ["n0=v0", "n1=v1", ...]
|
|
15
|
+
.map(nv_split) // [["n0", "v0"], ["n1", "v1"], ...]
|
|
16
|
+
.collect(frst) // {"n0": [["n0", "v0"]], "n1": [["n1", "v1"]], ...}
|
|
17
|
+
.map(dup_1st) // {"n0": "v0", "n1": "v1", ...}
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`decodeContent("q=5&value=%20space%20")` is `{"q": "5", "value": "%20space%20"}`.
|
|
22
|
+
|
|
23
|
+
- `split` makes an array of `name=value` strings.
|
|
24
|
+
- `extract` matches each one against a regular expression and returns its capture groups, the name and the value.
|
|
25
|
+
- `collect` groups the pairs into a map keyed by name. Each value is an array of every pair with that name.
|
|
26
|
+
- The map operator `map` keeps the first value for each name.
|
|
27
|
+
|
|
28
|
+
## Keep every value of a repeated name
|
|
29
|
+
|
|
30
|
+
When a name can repeat, keep all its values:
|
|
31
|
+
|
|
32
|
+
```krl
|
|
33
|
+
dup_all = function(v) {
|
|
34
|
+
v.length() == 1 => v[0][1] | v.map(function(w) { w[1] })
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Use `.map(dup_all)` in place of `.map(dup_1st)`. `a=1&a=2&b=3` becomes `{"a": ["1", "2"], "b": "3"}`.
|
|
39
|
+
|
|
40
|
+
## Decode `+` and `%xx`
|
|
41
|
+
|
|
42
|
+
`replace` accepts a function as its second argument. It is called with the match and then each capture group, and returns the replacement:
|
|
43
|
+
|
|
44
|
+
```krl
|
|
45
|
+
hexDigits = "0123456789abcdef"
|
|
46
|
+
|
|
47
|
+
hex2dec = function(hex) {
|
|
48
|
+
hex like re#^[0-9A-Fa-f]+$#
|
|
49
|
+
=> hex.lc().split("").reduce(function(a, h) { a * 16 + hexDigits.split("").index(h) }, 0)
|
|
50
|
+
| null
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
hex2char = function(encoded, hex) {
|
|
54
|
+
val = hex2dec(hex)
|
|
55
|
+
val && val < 128 => val.chr() | encoded
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
decode_val = function(s) {
|
|
59
|
+
s.replace(re#[+]#g, " ").replace(re#%([0-9A-Fa-f]{2})#g, hex2char)
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Replace `+` first: early encoders used it for a space, and a real plus sign arrives as `%2B`. Then use `function(v) { decode_val(v[0][1]) }` as the last step of the chain. `value=%20space%20&plus=a%2Bb&pct=100%25` becomes `{"value": " space ", "plus": "a+b", "pct": "100%"}`. This handles ASCII characters. Anything above 127 is left encoded.
|
|
64
|
+
|
|
65
|
+
Events and queries that arrive over HTTP are already decoded: the engine gives you their attributes as a map. This is for strings you have in hand.
|
|
66
|
+
|
|
67
|
+
*From the Pico Labs KRL Cookbook page "Decoding WWW-Form Encoded Content or Query Parameters".*
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Reading the engine's log files
|
|
2
|
+
|
|
3
|
+
The **Logging** tab shows recent events and queries for a pico, from the engine's memory. To look further back, or across every pico, read the log files.
|
|
4
|
+
|
|
5
|
+
## Where they are
|
|
6
|
+
|
|
7
|
+
The engine writes one JSON object per line to `pico-engine.log` in its home directory (`PICO_ENGINE_HOME`, `~/.pico-engine` by default). When the file reaches 100 MB it rotates: the older entries move to `pico-engine.log.1`, `pico-engine.log.2`, and so on, and the engine keeps up to twelve files. `PICO_ENGINE_LOG_FILE` writes somewhere else instead (`stdout` to write to standard output). See [the operator guide](/pico-engine) for the settings.
|
|
8
|
+
|
|
9
|
+
Each line has `level`, `time`, and `msg`, and lines about a pico's work have `picoId` and `txnId`. A transaction is one event or query and everything it caused.
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{"level":50,"time":"2026-11-13T18:46:16.317Z","picoId":"cmwfbv2y1001e4jysd0cn9w05","txnId":"cmwfbvcvx00244jysd16w7grz","txnKind":"query","error":"This is a family channel and only the owner can use it.","msg":"..."}
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## One pico's history
|
|
16
|
+
|
|
17
|
+
Find the pico's id on its **About** tab, then:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
cd ~/.pico-engine
|
|
21
|
+
grep -h '"picoId":"<pico id>"' pico-engine.log* | jq -s -c 'sort_by(.time)[]' > my_pico.log
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`grep` collects the lines from every file, and [`jq`](https://jqlang.org/) sorts them by time, since rotated files aren't in order relative to each other. To follow one event through everything it caused, filter on its `txnId` instead.
|
|
25
|
+
|
|
26
|
+
## What to look for
|
|
27
|
+
|
|
28
|
+
- `"msg":"txnQueued"` lines show each event or query as it arrived, with its attributes.
|
|
29
|
+
- `"error"` fields show what failed: a channel policy refusal, a KRL runtime error, a family channel used from outside.
|
|
30
|
+
- `klog` output from your own rules is in the log, with the message you gave it.
|
|
31
|
+
|
|
32
|
+
The logs hold every event's attributes. Anything secret that arrives in an event is in them. See the [Configuration and secrets](/cookbook/secrets/) demo.
|
|
33
|
+
|
|
34
|
+
*From the Pico Labs KRL Cookbook page "Examining pico-engine log files". The log format and rotation have changed since that page was written.*
|