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.
- package/README.md +13 -5
- package/demos/bootstrap/README.md +12 -0
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
- package/demos/bootstrap/com.example.visitors.format.krl +25 -0
- package/demos/bootstrap/com.example.visitors.krl +228 -0
- package/demos/bootstrap/try-it.md +5 -0
- package/demos/child_tasks/README.md +12 -0
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
- package/demos/child_tasks/com.example.task_runner.krl +139 -0
- package/demos/child_tasks/com.example.task_worker.krl +45 -0
- package/demos/child_tasks/try-it.md +5 -0
- package/demos/collection/README.md +13 -0
- package/demos/collection/com.example.collection.bootstrap.krl +148 -0
- package/demos/collection/com.example.collection.krl +95 -0
- package/demos/collection/com.example.collection.report.krl +93 -0
- package/demos/collection/com.example.collection.room.krl +101 -0
- package/demos/collection/try-it.md +6 -0
- package/demos/echo/README.md +11 -0
- package/demos/echo/com.example.echo.bootstrap.krl +84 -0
- package/demos/echo/com.example.echo.krl +73 -0
- package/demos/echo/try-it.md +5 -0
- package/demos/guard_rules/README.md +12 -0
- package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
- package/demos/guard_rules/com.example.archive.krl +213 -0
- package/demos/guard_rules/com.example.archive_store.krl +36 -0
- package/demos/guard_rules/try-it.md +5 -0
- 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/README.md +14 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
- package/demos/kblog/com.example.kblog.config.krl +50 -0
- package/demos/kblog/com.example.kblog.data.krl +75 -0
- package/demos/kblog/com.example.kblog.krl +184 -0
- package/demos/kblog/com.example.kblog.posting.krl +109 -0
- package/demos/kblog/try-it.md +6 -0
- package/demos/layered_rulesets/README.md +13 -0
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
- package/demos/layered_rulesets/com.example.invitations.krl +164 -0
- package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
- package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
- package/demos/layered_rulesets/try-it.md +5 -0
- package/demos/moving_picos/README.md +15 -0
- package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
- package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
- package/demos/score_tracker/README.md +11 -0
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
- package/demos/score_tracker/com.example.score_tracker.krl +162 -0
- package/demos/score_tracker/try-it.md +5 -0
- package/demos/secrets/README.md +12 -0
- package/demos/secrets/com.example.hook_service.krl +120 -0
- package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
- package/demos/secrets/com.example.notifier.krl +138 -0
- package/demos/secrets/try-it.md +5 -0
- package/demos/try-it-order.json +1 -0
- package/demos/two_picos/README.md +12 -0
- package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
- package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
- package/demos/two_picos/try-it.md +5 -0
- package/demos/xmlui/README.md +17 -0
- package/demos/xmlui/com.example.contacts.krl +132 -0
- package/demos/xmlui/com.example.fav_color.krl +39 -0
- package/demos/xmlui/com.example.guestbook.krl +61 -0
- package/demos/xmlui/com.example.hello.krl +19 -0
- package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
- package/demos/xmlui/com.example.thermostat.krl +124 -0
- package/demos/xmlui/temperature_sensors.krl +56 -0
- package/demos/xmlui/try-it.md +5 -0
- package/dist/bundledKrl.js +97 -12
- package/dist/cli.js +7 -1
- package/dist/engineConfig.js +20 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +45 -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 +210 -47
- 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/krl/io.picolabs.xmlui.krl +3 -2
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +6 -4
- 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 +10 -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 +18 -9
- package/public/.DS_Store +0 -0
- package/public/pico-engine-ui.css +1 -1
- package/public/pico-engine-ui.js +26 -25
- package/src/bundledKrl.ts +118 -12
- package/src/cli.ts +8 -2
- package/src/engineConfig.ts +33 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -422
- 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 +266 -51
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
# Relationships
|
|
2
|
+
|
|
3
|
+
Not every relationship between picos is parent and child. A flower shop may need a link to a delivery driver so it can broadcast a request and the driver can bid on it, and neither created the other. Many systems are built from peers. This lesson teaches picos to link to one another with **relationships**, and to use the link.
|
|
4
|
+
|
|
5
|
+
> **Terminology:** What the engine now calls a *relationship* was called a *subscription* before engine 1.6.2. The ideas are the same. The ruleset is still `io.picolabs.subscription`, and the older event names (`wrangler:subscription`, `wrangler:pending_subscription_approval`, …) still work next to the new ones. This lesson uses the new names. See [Relationships](/wrangler/relationships) for the full list.
|
|
6
|
+
|
|
7
|
+
## Objectives
|
|
8
|
+
|
|
9
|
+
When you finish you will be able to:
|
|
10
|
+
|
|
11
|
+
- explain what a relationship is: a named, two-way link with a channel and a role at each end
|
|
12
|
+
- say what `Tx`, `Rx`, `Tx_role`, `Rx_role`, and the well-known channel are
|
|
13
|
+
- create, approve, and inspect relationships in the developer UI
|
|
14
|
+
- create, approve, reject, and cancel relationships from rules
|
|
15
|
+
- send an event over a relationship and use it to tell friend from stranger
|
|
16
|
+
- say what changes when a relationship uses DIDs instead of a well-known channel
|
|
17
|
+
|
|
18
|
+
**Before you begin**, finish:
|
|
19
|
+
|
|
20
|
+
- [Quickstart](/lessons/quickstart): install rulesets
|
|
21
|
+
- [Events and Queries](/lessons/events-and-queries): channels, and events raised on them
|
|
22
|
+
- [Pico State](/lessons/pico-state): entity variables, simple and complex
|
|
23
|
+
- [Pico-Based Systems](/lessons/pico-based-systems): create and delete children, and install rulesets in them (you'll rebuild the registration system from it here)
|
|
24
|
+
|
|
25
|
+
and read [Relationships](/wrangler/relationships) in the Wrangler documentation.
|
|
26
|
+
|
|
27
|
+
## Relationships
|
|
28
|
+
|
|
29
|
+
A relationship has a name and **two channels**, one owned by each pico. Each pico sees it from its own side. In a relationship between picos A and B:
|
|
30
|
+
|
|
31
|
+
- A's **`Rx`** is the channel on which A *receives* events and queries. It's a channel in A, and its policy decides what B may do. It's B's `Tx`.
|
|
32
|
+
- A's **`Tx`** is the channel A *transmits* on, to reach B. It's B's `Rx`.
|
|
33
|
+
|
|
34
|
+
The two picos see the channels swapped, which is the point: each side keeps its own rules about who can do what to it.
|
|
35
|
+
|
|
36
|
+
Each end may also have a role. From A's perspective, **`Rx_role`** is A's role, "mine", and **`Tx_role`** is B's, "theirs". From B's perspective they are the other way round. Roles label a relationship (`student`, `section`, `owner`). They prove nothing. What a pico may do is decided by the policy of its `Rx` channel.
|
|
37
|
+
|
|
38
|
+
The relationship also has an **`Id`**, the same on both ends. It is the one field that is: there's one relationship with two ends, and the rest of its fields swap.
|
|
39
|
+
|
|
40
|
+
<img src="/lessons/_media/21659676-image2016-7-21-17-49-40.png" alt="A relationship between picos A and B. A's Tx is B's Rx, and A's Rx is B's Tx, and the relationship has a name" width="50%">
|
|
41
|
+
|
|
42
|
+
## The experiment
|
|
43
|
+
|
|
44
|
+
We continue the registration example. The root pico has two children, the **Registration** pico and the **Section Collection** pico. The Section Collection pico has a child pico for each section. Students are children of the Registration pico, and each student will have a relationship with each section they take:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
root pico
|
|
48
|
+
├── Registration pico
|
|
49
|
+
│ └── Student pico (Jane)
|
|
50
|
+
└── Section Collection pico
|
|
51
|
+
├── Section A HTG 100-1 pico
|
|
52
|
+
└── Section CS462-1 pico
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Parent-child links are the tree. Relationships are separate lines drawn across it: Jane to a section, and Jane to the Section Collection.
|
|
56
|
+
|
|
57
|
+
<img src="/lessons/_media/21659676-subs2.png" alt="The pico layout with the parent-child tree, and dashed pink lines for Jane's relationships to the section picos" width="50%">
|
|
58
|
+
|
|
59
|
+
To prepare, (re)build the registration system from [Pico-Based Systems](/lessons/pico-based-systems): install `app_section_collection` in the Section Collection pico and create two sections with `section:needed`. Then create a pico for a student, a child of the root named "Jane", with the About tab. Every pico has `io.picolabs.subscription` installed already, so you needn't install it.
|
|
60
|
+
|
|
61
|
+
## Create a relationship by hand
|
|
62
|
+
|
|
63
|
+
To form a relationship, Wrangler makes a new channel in each pico. To get started, it needs a channel that already exists in each one. That's the **well-known channel**.
|
|
64
|
+
|
|
65
|
+
*The screenshots below come from an earlier release, when the **Relationships** tab was called **Subscriptions**. The layout has changed since, but the steps are the same.*
|
|
66
|
+
|
|
67
|
+
### Find the well-known channel
|
|
68
|
+
|
|
69
|
+
Every pico has a **well-known channel**, created by `io.picolabs.subscription` when it's installed. Its policy is deliberately narrow: it accepts only the events that start a relationship (and one that removes an unaccepted request), and it answers a single query, for its own ID. That makes its ECI safe to pass around widely.
|
|
70
|
+
|
|
71
|
+
Visit a section pico and open its **Relationships** tab. The **Identity** panel shows the well-known channel, `wellKnown_Rx`. Copy it.
|
|
72
|
+
|
|
73
|
+
### Ask for a relationship
|
|
74
|
+
|
|
75
|
+
Open Jane's **Relationships** tab and find **New relationship**. Choose the classic (ECI) form and fill it in:
|
|
76
|
+
|
|
77
|
+
1. `wellKnown_Tx`: paste the section pico's well-known ECI
|
|
78
|
+
2. `Rx_role`: this pico's role: `student`
|
|
79
|
+
3. `Tx_role`: the other pico's role: `class`
|
|
80
|
+
4. `name`: a name for the relationship, such as `Jane-A HTG 100-1`
|
|
81
|
+
5. Leave the `channel_type` as it is (the default is `Tx_Rx`), and leave the password and host blank. A password is for auto-accept configuration, and the host is for a pico on another engine
|
|
82
|
+
|
|
83
|
+
Submit the form. It raises `wrangler:relationship` in Jane's pico.
|
|
84
|
+
|
|
85
|
+
<img src="/lessons/_media/21659676-ui-subs2.png" alt="The New relationship form on a pico's Relationships tab" width="50%">
|
|
86
|
+
|
|
87
|
+
### Look at what happened
|
|
88
|
+
|
|
89
|
+
On Jane's **Channels** tab there's a new channel for this relationship. It is Jane's `Rx`, and the section's `Tx`.
|
|
90
|
+
|
|
91
|
+
<img src="/lessons/_media/21659676-ui-subs1.png" alt="Jane's Channels tab showing the new relationship channel before acceptance" width="50%">
|
|
92
|
+
|
|
93
|
+
On Jane's **Relationships** tab, the relationship is under **Outbound pending**: proposed to the other pico, not yet accepted.
|
|
94
|
+
|
|
95
|
+
Visit the section pico. Its **Inbound pending** list has the same relationship. Expand both and compare. `Id` is the same. The roles are swapped and so are `Tx` and `Rx`. Jane doesn't yet have the section's ECI, because the section hasn't accepted.
|
|
96
|
+
|
|
97
|
+
<img src="/lessons/_media/21659676-ui-subs4.png" alt="A pico's Relationships tab with one inbound pending relationship" width="50%">
|
|
98
|
+
|
|
99
|
+
### Accept it
|
|
100
|
+
|
|
101
|
+
On the section pico, expand the inbound relationship and click **Approve**. That raises `wrangler:pending_relationship_approval` with the relationship's `Id`. Both sides now show it as **Established**. Jane has the section's channel, and the section has Jane's.
|
|
102
|
+
|
|
103
|
+
<img src="/lessons/_media/21659676-ui-subs5.png" alt="An expanded inbound relationship with its Rx_role, Tx_role, Id, Tx and Rx, and an Accept button" width="50%">
|
|
104
|
+
|
|
105
|
+
<img src="/lessons/_media/21659676-ui-subs8.png" alt="Jane's Channels tab after the relationship is accepted, showing the established channel" width="50%">
|
|
106
|
+
|
|
107
|
+
Do it again with Jane and the other section. Jane's established list now has two relationships. Their `Id`s differ.
|
|
108
|
+
|
|
109
|
+
<img src="/lessons/_media/21659676-ui-subs3.png" alt="The section pico's Relationships tab with an established relationship" width="50%">
|
|
110
|
+
|
|
111
|
+
<img src="/lessons/_media/21659676-ui-subs6.png" alt="The Relationships tab with the relationship now listed as established" width="50%">
|
|
112
|
+
|
|
113
|
+
<img src="/lessons/_media/21659676-ui-subs7.png" alt="The pico topology with magenta lines for Jane's established relationships" width="50%">
|
|
114
|
+
|
|
115
|
+
## Create a relationship from a rule
|
|
116
|
+
|
|
117
|
+
Everything the UI did, a rule can do, so the system can build itself. The challenge is the starting point: a rule can only use a well-known ECI that it has *found*. Someone must publish it. A natural place is the parent: a new pico tells its parent, and others ask the parent.
|
|
118
|
+
|
|
119
|
+
### Sections report their well-known channels
|
|
120
|
+
|
|
121
|
+
Replace `app_section` from the last lesson with this version. Its rule runs when the ruleset is installed, finds the pico's well-known channel, and tells the Section Collection pico:
|
|
122
|
+
|
|
123
|
+
```krl
|
|
124
|
+
ruleset app_section {
|
|
125
|
+
meta {
|
|
126
|
+
name "Section"
|
|
127
|
+
use module io.picolabs.wrangler alias wrangler
|
|
128
|
+
use module io.picolabs.subscription alias relationship
|
|
129
|
+
shares sectionId
|
|
130
|
+
}
|
|
131
|
+
global {
|
|
132
|
+
sectionId = function() {
|
|
133
|
+
ent:section_id
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
rule pico_ruleset_added {
|
|
138
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
139
|
+
pre {
|
|
140
|
+
section_id = event:attr("section_id")
|
|
141
|
+
well_known = relationship:wellKnown_Rx(){"id"}
|
|
142
|
+
}
|
|
143
|
+
event:send({
|
|
144
|
+
"eci": wrangler:parent_eci(),
|
|
145
|
+
"domain": "section",
|
|
146
|
+
"type": "identify",
|
|
147
|
+
"attrs": {"section_id": section_id, "wellKnown_eci": well_known}
|
|
148
|
+
})
|
|
149
|
+
always {
|
|
150
|
+
ent:section_id := section_id
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Look at the new parts: the `use module io.picolabs.subscription alias relationship` line gives access to the relationship functions. `relationship:wellKnown_Rx()` returns the well-known channel, a map with an `id`. `event:send` in the action block sends `section:identify` to the parent over the family channel.
|
|
157
|
+
|
|
158
|
+
Add these rules to `app_section_collection`. The first one stores what sections report:
|
|
159
|
+
|
|
160
|
+
```krl
|
|
161
|
+
rule accept_wellKnown {
|
|
162
|
+
select when section identify
|
|
163
|
+
section_id re#(.+)#
|
|
164
|
+
wellKnown_eci re#(.+)#
|
|
165
|
+
setting(section_id, wellKnown_eci)
|
|
166
|
+
always {
|
|
167
|
+
ent:sections{[section_id, "wellKnown_eci"]} := wellKnown_eci
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// A student asked for a relationship with this pico: this pico's role is registration.
|
|
172
|
+
rule accept_student {
|
|
173
|
+
select when wrangler inbound_pending_relationship_added
|
|
174
|
+
where event:attr("Rx_role") == "registration"
|
|
175
|
+
always {
|
|
176
|
+
raise wrangler event "pending_relationship_approval" attributes event:attrs
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
rule introduce_section_to_student {
|
|
181
|
+
select when section add_request
|
|
182
|
+
pre {
|
|
183
|
+
section_id = event:attr("section_id")
|
|
184
|
+
name = event:attr("name")
|
|
185
|
+
}
|
|
186
|
+
event:send({
|
|
187
|
+
"eci": ent:sections{[section_id, "wellKnown_eci"]},
|
|
188
|
+
"domain": "wrangler",
|
|
189
|
+
"type": "relationship",
|
|
190
|
+
"attrs": {
|
|
191
|
+
"wellKnown_Tx": event:attr("wellKnown_Tx"),
|
|
192
|
+
"Rx_role": "section",
|
|
193
|
+
"Tx_role": "student",
|
|
194
|
+
"name": name + "-" + section_id,
|
|
195
|
+
"section_id": section_id
|
|
196
|
+
}
|
|
197
|
+
})
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
After a few sections have reported, `sections()` returns more than it did, because each entry now has the section's well-known ECI beside its family `eci`:
|
|
202
|
+
|
|
203
|
+
```json
|
|
204
|
+
{
|
|
205
|
+
"CS462-1": { "eci": "cm0a8w4ks0004m8ys0p1e5k2r", "wellKnown_eci": "cm0a8w4ls0007m8ys6bd2f5h3" },
|
|
206
|
+
"A HTG 100-1": { "eci": "cm0a8w9sd0008m8ysg2l73c1d", "wellKnown_eci": "cm0a8w9tc000bm8ysd4w9j8e1" }
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Any section ID can now be turned into a well-known ECI by asking the Section Collection pico.
|
|
211
|
+
|
|
212
|
+
The Registration pico has to know the Section Collection pico's well-known channel too. To keep this lesson short, do that by hand: copy it from the Section Collection pico's Relationships tab, and send `registration:collection_known` with the `wellKnown_Rx` attribute to the Registration pico on its Testing tab. (Making the collection report it, like the sections do, is an exercise.)
|
|
213
|
+
|
|
214
|
+
### The Registration pico makes students
|
|
215
|
+
|
|
216
|
+
Here is `app_registration`. When a student arrives, it creates a child pico for them. When the child has finished setting up, it installs `app_student` and passes along the student's name and the collection's well-known channel:
|
|
217
|
+
|
|
218
|
+
```krl
|
|
219
|
+
ruleset app_registration {
|
|
220
|
+
meta {
|
|
221
|
+
use module io.picolabs.wrangler alias wrangler
|
|
222
|
+
shares collection
|
|
223
|
+
}
|
|
224
|
+
global {
|
|
225
|
+
collection = function() {
|
|
226
|
+
ent:collectionWellKnown
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
rule collection_known {
|
|
231
|
+
select when registration collection_known wellKnown_Rx re#(.+)# setting(well_known)
|
|
232
|
+
always {
|
|
233
|
+
ent:collectionWellKnown := well_known
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
rule allow_student_to_register {
|
|
238
|
+
select when student arrives name re#(.+)# setting(name)
|
|
239
|
+
always {
|
|
240
|
+
raise wrangler event "new_child_request" attributes {
|
|
241
|
+
"name": name,
|
|
242
|
+
"backgroundColor": event:attr("backgroundColor") || "#CCCCCC",
|
|
243
|
+
"student_name": name
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
rule install_student_ruleset {
|
|
249
|
+
select when wrangler child_initialized where event:attr("student_name")
|
|
250
|
+
event:send({
|
|
251
|
+
"eci": event:attr("eci"),
|
|
252
|
+
"domain": "wrangler",
|
|
253
|
+
"type": "install_ruleset_request",
|
|
254
|
+
"attrs": {
|
|
255
|
+
"absoluteURL": meta:rulesetURI,
|
|
256
|
+
"rid": "app_student",
|
|
257
|
+
"student_name": event:attr("student_name"),
|
|
258
|
+
"collection_wellKnown": ent:collectionWellKnown
|
|
259
|
+
}
|
|
260
|
+
})
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
This is the same create-then-install chain as in [Pico-Based Systems](/lessons/pico-based-systems): `new_child_request`, then `child_initialized`, then `install_ruleset_request`. Install `app_registration` in the Registration pico, with `app_student` in the same folder. Send `registration:collection_known` first, so there's a well-known channel to pass on, and then `student:arrives` with `name=Jane` on its Testing tab.
|
|
266
|
+
|
|
267
|
+
### The student asks the collection for a relationship
|
|
268
|
+
|
|
269
|
+
Now `app_student`, in full. Each rule is explained below, but read the first two now:
|
|
270
|
+
|
|
271
|
+
```krl
|
|
272
|
+
ruleset app_student {
|
|
273
|
+
meta {
|
|
274
|
+
use module io.picolabs.wrangler alias wrangler
|
|
275
|
+
use module io.picolabs.subscription alias relationship
|
|
276
|
+
shares classes
|
|
277
|
+
}
|
|
278
|
+
global {
|
|
279
|
+
classes = function() {
|
|
280
|
+
ent:classes.defaultsTo({}).values()
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
rule capture_initial_state {
|
|
285
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
286
|
+
always {
|
|
287
|
+
ent:name := event:attr("student_name")
|
|
288
|
+
ent:collectionWellKnown := event:attr("collection_wellKnown")
|
|
289
|
+
raise student event "new_relationship_request"
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
rule make_a_relationship {
|
|
294
|
+
select when student new_relationship_request
|
|
295
|
+
always {
|
|
296
|
+
raise wrangler event "relationship" attributes {
|
|
297
|
+
"wellKnown_Tx": ent:collectionWellKnown,
|
|
298
|
+
"Rx_role": "student",
|
|
299
|
+
"Tx_role": "registration",
|
|
300
|
+
"name": ent:name + "-registration"
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
rule add_a_class {
|
|
306
|
+
select when section add_request section_id re#(.+)# setting(section_id)
|
|
307
|
+
pre {
|
|
308
|
+
already_enrolled = classes() >< section_id
|
|
309
|
+
registration = relationship:established("Tx_role", "registration").head()
|
|
310
|
+
}
|
|
311
|
+
if not already_enrolled && registration then
|
|
312
|
+
event:send({
|
|
313
|
+
"sub": registration,
|
|
314
|
+
"domain": "section",
|
|
315
|
+
"type": "add_request",
|
|
316
|
+
"attrs": {
|
|
317
|
+
"wellKnown_Tx": relationship:wellKnown_Rx(){"id"},
|
|
318
|
+
"section_id": section_id,
|
|
319
|
+
"name": ent:name
|
|
320
|
+
}
|
|
321
|
+
})
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
rule auto_accept_section {
|
|
325
|
+
select when wrangler inbound_pending_relationship_added
|
|
326
|
+
Rx_role re#^student$#
|
|
327
|
+
Tx_role re#^section$#
|
|
328
|
+
pre {
|
|
329
|
+
section_id = event:attr("section_id")
|
|
330
|
+
}
|
|
331
|
+
if section_id then noop()
|
|
332
|
+
fired {
|
|
333
|
+
ent:classes{event:attr("Id")} := section_id
|
|
334
|
+
raise wrangler event "pending_relationship_approval" attributes event:attrs
|
|
335
|
+
last
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
rule reject_everything_else {
|
|
340
|
+
select when wrangler inbound_pending_relationship_added
|
|
341
|
+
always {
|
|
342
|
+
raise wrangler event "inbound_rejection" attributes event:attrs
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
rule drop_a_class {
|
|
347
|
+
select when section drop_request section_id re#(.+)# setting(section_id)
|
|
348
|
+
pre {
|
|
349
|
+
rel_id = ent:classes.defaultsTo({})
|
|
350
|
+
.filter(function(v) { v == section_id })
|
|
351
|
+
.keys()
|
|
352
|
+
.head()
|
|
353
|
+
}
|
|
354
|
+
if rel_id then noop()
|
|
355
|
+
fired {
|
|
356
|
+
clear ent:classes{rel_id}
|
|
357
|
+
raise wrangler event "relationship_cancellation" attributes {"Id": rel_id}
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
`capture_initial_state` runs when `app_student` is installed in the new pico. It stores what it was given, and raises `student:new_relationship_request`. It's a separate rule so we can raise that event again whenever we need another relationship. `make_a_relationship` raises `wrangler:relationship` with the collection's `wellKnown_Tx`, and roles: this pico is a `student`, the other a `registration`. It's what you did in the UI with the form.
|
|
364
|
+
|
|
365
|
+
Note what it sends to whom. The student asks the Section Collection pico, and that pico's `accept_student` rule (above) approves any request in which its own role is `registration`:
|
|
366
|
+
|
|
367
|
+
```krl
|
|
368
|
+
rule accept_student {
|
|
369
|
+
select when wrangler inbound_pending_relationship_added
|
|
370
|
+
where event:attr("Rx_role") == "registration"
|
|
371
|
+
always {
|
|
372
|
+
raise wrangler event "pending_relationship_approval" attributes event:attrs
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
When a relationship arrives, Wrangler raises `wrangler:inbound_pending_relationship_added` with the attributes of the request, seen from the receiver's side: `Rx_role` is the receiver's own role. The rule approves by raising `wrangler:pending_relationship_approval` with the same attributes (which include `Id`). That's the programmatic version of clicking **Approve**.
|
|
378
|
+
|
|
379
|
+
Don't approve everyone. This rule only accepts the request when its `Rx_role` is `registration`; anything else is left pending. For something more general, see [Accepting relationship requests](/developing/accepting-relationship-requests) for the auto-accept configuration.
|
|
380
|
+
|
|
381
|
+
### Add a class: introduce a section
|
|
382
|
+
|
|
383
|
+
With the relationship between a student and the collection established, a student pico can ask to join a class. The rule `add_a_class` in `app_student`, which you've seen in the listing, sends `section:add_request` over the relationship:
|
|
384
|
+
|
|
385
|
+
```krl
|
|
386
|
+
rule add_a_class {
|
|
387
|
+
select when section add_request section_id re#(.+)# setting(section_id)
|
|
388
|
+
pre {
|
|
389
|
+
already_enrolled = classes() >< section_id
|
|
390
|
+
registration = relationship:established("Tx_role", "registration").head()
|
|
391
|
+
}
|
|
392
|
+
if not already_enrolled && registration then
|
|
393
|
+
event:send({
|
|
394
|
+
"sub": registration,
|
|
395
|
+
"domain": "section",
|
|
396
|
+
"type": "add_request",
|
|
397
|
+
"attrs": {
|
|
398
|
+
"wellKnown_Tx": relationship:wellKnown_Rx(){"id"},
|
|
399
|
+
"section_id": section_id,
|
|
400
|
+
"name": ent:name
|
|
401
|
+
}
|
|
402
|
+
})
|
|
403
|
+
}
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
The prelude checks that we aren't enrolled already (`classes()` is a function defined in the ruleset, and shared), and finds the relationship whose other end is a `registration`. `relationship:established("Tx_role", "registration")` returns the established relationships whose `Tx_role` is that. `event:send` with `"sub"` sends over a relationship, here the one with the collection, so the student needs no ECI of its own for the collection. It passes the student's well-known ECI, the section, and the student's name.
|
|
407
|
+
|
|
408
|
+
The collection pico gets `section:add_request`. Its `introduce_section_to_student` rule (in the listing above) *introduces* the section to the student. It sends a `wrangler:relationship` event to the **section's** well-known channel, with the **student's** well-known ECI as `wellKnown_Tx`:
|
|
409
|
+
|
|
410
|
+
```krl
|
|
411
|
+
rule introduce_section_to_student {
|
|
412
|
+
select when section add_request
|
|
413
|
+
pre {
|
|
414
|
+
section_id = event:attr("section_id")
|
|
415
|
+
name = event:attr("name")
|
|
416
|
+
}
|
|
417
|
+
event:send({
|
|
418
|
+
"eci": ent:sections{[section_id, "wellKnown_eci"]},
|
|
419
|
+
"domain": "wrangler",
|
|
420
|
+
"type": "relationship",
|
|
421
|
+
"attrs": {
|
|
422
|
+
"wellKnown_Tx": event:attr("wellKnown_Tx"),
|
|
423
|
+
"Rx_role": "section",
|
|
424
|
+
"Tx_role": "student",
|
|
425
|
+
"name": name + "-" + section_id,
|
|
426
|
+
"section_id": section_id
|
|
427
|
+
}
|
|
428
|
+
})
|
|
429
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
This is the same as typing in the section pico's New relationship form, but the collection did it on its behalf. The section pico needs no code for it: `io.picolabs.subscription` handles the event, and the section proposes a relationship to the student, who is sent the `section_id` as well. This is **introduction**: a third pico that knows both well-known channels connects two picos that don't know each other.
|
|
433
|
+
|
|
434
|
+
### The student accepts a section
|
|
435
|
+
|
|
436
|
+
Back in `app_student`, these rules see the proposal arrive:
|
|
437
|
+
|
|
438
|
+
```krl
|
|
439
|
+
rule auto_accept_section {
|
|
440
|
+
select when wrangler inbound_pending_relationship_added
|
|
441
|
+
Rx_role re#^student$#
|
|
442
|
+
Tx_role re#^section$#
|
|
443
|
+
pre {
|
|
444
|
+
section_id = event:attr("section_id")
|
|
445
|
+
}
|
|
446
|
+
if section_id then noop()
|
|
447
|
+
fired {
|
|
448
|
+
ent:classes{event:attr("Id")} := section_id
|
|
449
|
+
raise wrangler event "pending_relationship_approval" attributes event:attrs
|
|
450
|
+
last
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
rule reject_everything_else {
|
|
455
|
+
select when wrangler inbound_pending_relationship_added
|
|
456
|
+
always {
|
|
457
|
+
raise wrangler event "inbound_rejection" attributes event:attrs
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
The first rule is selected only when `Rx_role` is `student` and `Tx_role` is `section`. If the request carries a `section_id`, the rule records the relationship in `ent:classes`, a map from relationship `Id` to section id, and approves. The relationship is now established at both ends.
|
|
463
|
+
|
|
464
|
+
`last` ends the processing of this event in this ruleset, and it's essential. Both rules select the same event, and rules run in the order they're written, so the accepting rule must come first. If it fired, the rejecting rule must not run, or the student would approve and reject the same request. A request this ruleset doesn't recognize falls to `reject_everything_else`, which raises `wrangler:inbound_rejection` to refuse it.
|
|
465
|
+
|
|
466
|
+
### A class list
|
|
467
|
+
|
|
468
|
+
`ent:classes` maps relationship ids to section ids, so the list of classes is its values:
|
|
469
|
+
|
|
470
|
+
```krl
|
|
471
|
+
classes = function() {
|
|
472
|
+
ent:classes.defaultsTo({}).values()
|
|
473
|
+
}
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
The function is shared in `meta`. Try the whole flow: send `section:add_request` with `section_id=CS462-1` to Jane's pico, and check `classes`. Jane's Relationships tab now lists the collection and the section.
|
|
477
|
+
|
|
478
|
+
Notice that `section:add_request` is used twice: a user sends it to a student pico, and the student pico sends it to the collection pico. The registration application is one application, spread across several rulesets, for several kinds of pico. Events with the same name mean the same thing wherever they go.
|
|
479
|
+
|
|
480
|
+
## Cancel a relationship
|
|
481
|
+
|
|
482
|
+
Either pico in an established relationship can end it by raising `wrangler:relationship_cancellation` with the relationship's `Id`. Wrangler removes both ends. This rule, in `app_student`, drops a class:
|
|
483
|
+
|
|
484
|
+
```krl
|
|
485
|
+
rule drop_a_class {
|
|
486
|
+
select when section drop_request section_id re#(.+)# setting(section_id)
|
|
487
|
+
pre {
|
|
488
|
+
rel_id = ent:classes.defaultsTo({})
|
|
489
|
+
.filter(function(v) { v == section_id })
|
|
490
|
+
.keys()
|
|
491
|
+
.head()
|
|
492
|
+
}
|
|
493
|
+
if rel_id then noop()
|
|
494
|
+
fired {
|
|
495
|
+
clear ent:classes{rel_id}
|
|
496
|
+
raise wrangler event "relationship_cancellation" attributes {"Id": rel_id}
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
The prelude finds the relationship for that section. `filter` keeps the map entries whose value is the section id, `keys()` turns the remaining map into an array of its keys, and `head()` takes the first, or `null` if there's none. If there is one, the postlude removes it from `ent:classes` and asks Wrangler to cancel. The rule in `io.picolabs.subscription` removes both ends. You can see the same with the **Delete relationship** button in the Relationships tab.
|
|
502
|
+
|
|
503
|
+
To remove every relationship at once, for example before deleting a pico, raise `wrangler:cancel_subscriptions`.
|
|
504
|
+
|
|
505
|
+
## Use DIDs instead of a well-known ECI
|
|
506
|
+
|
|
507
|
+
Everything above is **classic** (ECI-based) relationships, and it's fully supported. Engine 1.6 added **DID-based** relationships, which are what new work should use. A pico has a portable identity, its `did:webvh`, and a relationship between two DID-based picos has its own private pairwise identity, a `did:peer`. DIDs work across meshes and engines without sharing an ECI.
|
|
508
|
+
|
|
509
|
+
What changes in the code:
|
|
510
|
+
|
|
511
|
+
| | Classic | DID-based |
|
|
512
|
+
|--|---------|-----------|
|
|
513
|
+
| What the asker needs to know | The other pico's well-known ECI, `relationship:wellKnown_Rx(){"id"}` | The other pico's DID, `wrangler:myDid()` |
|
|
514
|
+
| `wrangler:relationship` attributes | `wellKnown_Tx` | `layer2: true` and `target_did` |
|
|
515
|
+
| The established relationship has | `Tx` and `Rx` ECIs | `Tx_did` and `Rx_did` |
|
|
516
|
+
| Sending an event | `event:send({"sub": rel, …})` | the same, or `event:send({"did": …, …})` |
|
|
517
|
+
| Querying | `relationship:queryOnSub(Id, rid, name, args)` | the same, or `wrangler:picoQuery(did, rid, name, args)` |
|
|
518
|
+
|
|
519
|
+
In this lesson's application, a section would report `wrangler:myDid()` instead of its well-known channel, and a student asks with `"layer2": true, "target_did": the_did`. Approval, roles, `inbound_pending_relationship_added`, `last`, and cancellation are the same. One thing to know: a pico accepts an introduction by DID from a stranger only if its **public intro** is on. Root picos default to on. Child picos default to off, so a student pico that others will reach by DID has to turn it on (`wrangler:set_public_intro` with `enabled`). See [Relationships](/wrangler/relationships) for the details, and for how a relationship works across engines.
|
|
520
|
+
|
|
521
|
+
## Where to go next
|
|
522
|
+
|
|
523
|
+
- [Relationships](/wrangler/relationships): DIDs, public intro, routing, across engines, and the whole API
|
|
524
|
+
- [Two picos talking](/cookbook/two_picos/): two picos, a relationship, and queries over it, that you can run in two minutes
|
|
525
|
+
- [Accepting relationship requests](/developing/accepting-relationship-requests): auto-accept by configuration
|
|
526
|
+
- [Scatter-Gather](/lessons/scatter-gather): what to do once a pico has relationships with many others
|
|
527
|
+
|
|
528
|
+
---
|
|
529
|
+
|
|
530
|
+
<small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/21659676) (Pico to Pico Subscriptions Lesson, last edited there 2021-03-06), and updated for this engine. "Subscriptions" there are "relationships" here.</small>
|