@lowdefy/docs-content 6.1.0 → 7.0.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 +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +43 -7
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +154 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +8 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +136 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +2 -0
- package/content/connections/smtp.md +3 -1
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +24 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +1 -0
- package/content/controls/try.md +4 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +10 -7
- package/content/deployment/docker.md +22 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +17 -6
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +24 -1
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3458 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# User Object
|
|
2
|
+
|
|
3
|
+
The `user` object holds data about the currently signed-in **caller**, read with the [`_user`](/_user) operator on both the server and the client. It is not the provider's profile — it is a caller Lowdefy resolves from the user's row *and their membership in the active organization*, so the same person carries a different `_user` in two organizations they belong to.
|
|
4
|
+
|
|
5
|
+
Its shape is **fixed**. Unlike the old provider-claim mapping, there is no `userFields` config and no set of OpenID Connect claims copied onto the session — the provider subject and extra claims are not on the user object at all. If you need a provider claim at signup, persist it with an [auth hook](/auth-upgrade#7-rewrite-callbacks-and-events-as-hooks) and read it from where you stored it.
|
|
6
|
+
|
|
7
|
+
## Fields
|
|
8
|
+
|
|
9
|
+
| Field | On which callers | Meaning |
|
|
10
|
+
| ----- | ---------------- | ------- |
|
|
11
|
+
| `id` | all | The internal user id. **This replaces the old `sub`** — it is a *different value* (the provider subject lives on the `user-accounts` collection as `accountId`). |
|
|
12
|
+
| `email` | all | The user's email. |
|
|
13
|
+
| `email_verified` | session | Whether the email is verified. |
|
|
14
|
+
| `name`, `image` | session | Display name and avatar — the **per-organization** copies from the active membership, falling back to the deployment-global user record. |
|
|
15
|
+
| `roles` | session, strategy | The app's own role strings, from the active membership's `appRoles`. **The only thing `auth.pages.roles` / `auth.api.roles` match.** |
|
|
16
|
+
| `org_roles` | session | The organization tier from `member.role`: `owner`, `admin` or `member`. An administrative fact — **no gate reads it**. |
|
|
17
|
+
| `attributes` | session | One merged bag: global `user.attributes` under the active `member.attributes`, per key, member wins. |
|
|
18
|
+
| `organization_id` | session, mcp | The organization the caller acts in — the value the [tenant wall](/organizations#the-tenant-wall) stamps and filters on. |
|
|
19
|
+
| `active_organization_id` | session | The active organization id (equal to `organization_id`). |
|
|
20
|
+
| `two_factor_enrolled` | session | Whether the caller holds a factor satisfying `auth.twoFactor.required`. |
|
|
21
|
+
| `auth_method` | strategy, mcp | How the caller authenticated — the strategy id, or `'mcp'` for an [assistant](/mcp-oauth). Absent on browser sessions. |
|
|
22
|
+
| `profile` | session | The user record's opaque display/app-data bag. Absent (never `{}`) when the user has written no profile. |
|
|
23
|
+
| `contact_id` | session | Link to the app's canonical record for this person, when one exists. |
|
|
24
|
+
|
|
25
|
+
> **`_user.role` (singular) carries nothing.** Lowdefy never writes it; it sits one character from `roles`, so gating on `_user.role` is gating on a constant. Read `roles`.
|
|
26
|
+
|
|
27
|
+
A caller resolved from an [API strategy](/auth-configuration) (`apiKey`, `jwt`) sits outside the membership boundary: it carries `id`, `roles`, `attributes` and `auth_method`, but no organization, `name`, `image`, `profile` or `two_factor_enrolled`. A signed-in user who holds only a pending invitation (before they accept, under `tenant`) is an *awaiting-organization* caller — known to the always-public accept page, refused everywhere else.
|
|
28
|
+
|
|
29
|
+
## Examples
|
|
30
|
+
|
|
31
|
+
###### Use the user's avatar in an Avatar block:
|
|
32
|
+
```yaml
|
|
33
|
+
id: avatar
|
|
34
|
+
type: Avatar
|
|
35
|
+
properties:
|
|
36
|
+
src:
|
|
37
|
+
_user: image
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
###### Stamp the creator when inserting a document:
|
|
41
|
+
```yaml
|
|
42
|
+
id: insert_data
|
|
43
|
+
type: MongoDBInsertOne
|
|
44
|
+
properties:
|
|
45
|
+
doc:
|
|
46
|
+
field:
|
|
47
|
+
_state: field
|
|
48
|
+
created_by:
|
|
49
|
+
name:
|
|
50
|
+
_user: name
|
|
51
|
+
id:
|
|
52
|
+
_user: id
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
###### Read a value out of the merged attributes bag:
|
|
56
|
+
```yaml
|
|
57
|
+
_user: attributes.plan
|
|
58
|
+
```
|
|
@@ -29,3 +29,11 @@ The Login and Logout actions are used to start the login and logout processes.
|
|
|
29
29
|
## \_user operator
|
|
30
30
|
|
|
31
31
|
The `_user` operator can be used to access data in the user object received from the identity provider. The OpenID Connect standard claims (fields like `name` or `email`) are mapped to the user object by default and addition fields can be configured using the `userFields` configuration option.
|
|
32
|
+
|
|
33
|
+
### `two_factor_enrolled`
|
|
34
|
+
|
|
35
|
+
`_user: two_factor_enrolled` is `true` when the caller holds a factor that satisfies [`auth.twoFactor.required`](/two-factor) — a TOTP enrolment **or** a registered passkey.
|
|
36
|
+
|
|
37
|
+
It is a fact about the **user**, not the session: it does not assert that a factor was presented on this sign-in, only that the user has one on file. (The name is imperfect — a passkey is not literally a second factor. The field means precisely "holds a factor that satisfies `auth.twoFactor.required`", which a passkey does on its own.)
|
|
38
|
+
|
|
39
|
+
It is present only on session-resolved callers. The API strategy and the injected callers used in dev and e2e carry no session and so do not carry this field.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Publish and Actions
|
|
2
|
+
|
|
3
|
+
A `Channel` websocket relays messages between clients: any subscriber can publish, and the server broadcasts to everyone subscribed — including the sender. This powers chat, presence, and collaborative features with no extra services.
|
|
4
|
+
|
|
5
|
+
## A Minimal Chat
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
lowdefy: 6.1.0
|
|
9
|
+
|
|
10
|
+
websockets:
|
|
11
|
+
- id: team_chat
|
|
12
|
+
type: Channel
|
|
13
|
+
properties:
|
|
14
|
+
publish: true
|
|
15
|
+
|
|
16
|
+
pages:
|
|
17
|
+
- id: chat
|
|
18
|
+
type: PageHeaderMenu
|
|
19
|
+
subscriptions:
|
|
20
|
+
- websocketId: team_chat
|
|
21
|
+
client:
|
|
22
|
+
maxMessages: 200
|
|
23
|
+
blocks:
|
|
24
|
+
- id: chat_input
|
|
25
|
+
type: TextInput
|
|
26
|
+
properties:
|
|
27
|
+
placeholder: Say something...
|
|
28
|
+
- id: send
|
|
29
|
+
type: Button
|
|
30
|
+
properties:
|
|
31
|
+
title: Send
|
|
32
|
+
events:
|
|
33
|
+
onClick:
|
|
34
|
+
- id: publish
|
|
35
|
+
type: Publish
|
|
36
|
+
params:
|
|
37
|
+
websocketId: team_chat
|
|
38
|
+
payload:
|
|
39
|
+
text:
|
|
40
|
+
_state: chat_input
|
|
41
|
+
- id: clear
|
|
42
|
+
type: SetState
|
|
43
|
+
params:
|
|
44
|
+
chat_input: ''
|
|
45
|
+
- id: messages
|
|
46
|
+
type: Html
|
|
47
|
+
properties:
|
|
48
|
+
html:
|
|
49
|
+
_array.join:
|
|
50
|
+
- _array.map:
|
|
51
|
+
on:
|
|
52
|
+
_websocket: team_chat.messages
|
|
53
|
+
callback:
|
|
54
|
+
_function:
|
|
55
|
+
__string.concat:
|
|
56
|
+
- '<p>'
|
|
57
|
+
- __args: 0.text
|
|
58
|
+
- '</p>'
|
|
59
|
+
- ''
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Publishing requires both the channel type to support it and `properties.publish: true` on the definition — server-push channels reject publishes by default.
|
|
63
|
+
|
|
64
|
+
## Actions
|
|
65
|
+
|
|
66
|
+
### `Publish`
|
|
67
|
+
|
|
68
|
+
Sends a payload to a channel. The action resolves when the server acknowledges the publish, and rejects if the channel does not allow publishing or the connection cannot be established:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
- id: publish
|
|
72
|
+
type: Publish
|
|
73
|
+
params:
|
|
74
|
+
websocketId: team_chat
|
|
75
|
+
payload:
|
|
76
|
+
text:
|
|
77
|
+
_state: chat_input
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Payload values keep their types across the wire — dates arrive as dates.
|
|
81
|
+
|
|
82
|
+
### `Subscribe` and `Unsubscribe`
|
|
83
|
+
|
|
84
|
+
Page `subscriptions` cover most cases, but the actions give dynamic control — subscribe after an interaction, or re-subscribe with a fresh payload. Both take the id of a subscription declared on the page; a subscription with `client.subscribeOnMount: false` opens only with `Subscribe`:
|
|
85
|
+
|
|
86
|
+
```yaml
|
|
87
|
+
- id: resubscribe
|
|
88
|
+
type: Subscribe
|
|
89
|
+
params: activity_feed # payload re-evaluates from current state
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`Subscribe` on an already-subscribed channel evaluates the payload again: with a changed payload it replaces the channel (its state starts empty), with the same payload it does nothing. `Unsubscribe` on a channel that is not open does nothing. Channels subscribed with the action are still cleaned up when the page unmounts.
|
|
93
|
+
|
|
94
|
+
## Deployment
|
|
95
|
+
|
|
96
|
+
### Vercel
|
|
97
|
+
|
|
98
|
+
Websockets use Vercel's native WebSocket support for Node.js functions on Fluid compute — deploy the same project, no configuration. Two platform behaviors to know:
|
|
99
|
+
|
|
100
|
+
- Connections close when a function reaches its `maxDuration`. The Lowdefy client reconnects and resubscribes automatically, so this is invisible to users; raise `maxDuration` to reduce reconnect frequency on websocket-heavy apps.
|
|
101
|
+
- Under load, Vercel may run multiple instances of your app. Server-driven sources run per instance, so every subscriber receives every source message regardless of which instance they land on. Client publishes, however, reach subscribers connected to the same instance. For chat-style apps at multi-instance scale, a cross-instance pubsub adapter is on the roadmap.
|
|
102
|
+
|
|
103
|
+
### Self-Hosted
|
|
104
|
+
|
|
105
|
+
The Node.js server handles websocket upgrades directly — nothing to configure. A single server process delivers publishes to all subscribers, so `Channel` behavior is complete on one instance. Behind a reverse proxy, forward the upgrade headers and the original `Host` header (`proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host;` for nginx). The server refuses a websocket upgrade from a page whose origin does not match the `Host` it receives.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Page Subscriptions
|
|
2
|
+
|
|
3
|
+
Pages subscribe to websocket channels with the `subscriptions` key. The engine subscribes when the page mounts (unless the subscription sets `client.subscribeOnMount: false`) and unsubscribes when the user navigates away — no cleanup wiring needed.
|
|
4
|
+
|
|
5
|
+
## Subscription Definition
|
|
6
|
+
|
|
7
|
+
- `websocketId: string`: __Required__ - The id of a websocket defined in the top-level `websockets` array.
|
|
8
|
+
- `payload: object`: Client-side operators (`_state`, `_url_query`, `_global`) evaluated at subscribe time. The server reads these values with `_payload` in the websocket `properties`.
|
|
9
|
+
- `events: object`: Actions for `onMessage`, `onSubscribe` and `onError`.
|
|
10
|
+
- `client.maxMessages: number`: How many messages to retain in `messages` (default 100, oldest dropped first).
|
|
11
|
+
- `client.throttleRender: number`: Minimum milliseconds between renders while messages stream in (default 250, minimum 100).
|
|
12
|
+
- `client.subscribeOnMount: boolean`: Subscribe when the page mounts (default `true`). Set `false` to open the channel only with the [`Subscribe`](/websocket-publish) action.
|
|
13
|
+
|
|
14
|
+
## Reacting to Messages
|
|
15
|
+
|
|
16
|
+
The most common realtime pattern is prompting a data refresh — a source signals that something changed, and the page refetches its request:
|
|
17
|
+
|
|
18
|
+
```yaml
|
|
19
|
+
pages:
|
|
20
|
+
- id: orders
|
|
21
|
+
type: PageHeaderMenu
|
|
22
|
+
requests:
|
|
23
|
+
- id: get_orders
|
|
24
|
+
type: MongoDBFind
|
|
25
|
+
connectionId: mongodb
|
|
26
|
+
properties:
|
|
27
|
+
query: {}
|
|
28
|
+
subscriptions:
|
|
29
|
+
- websocketId: order_updates
|
|
30
|
+
events:
|
|
31
|
+
onMessage:
|
|
32
|
+
- id: refetch
|
|
33
|
+
type: Request
|
|
34
|
+
params: get_orders
|
|
35
|
+
blocks:
|
|
36
|
+
- id: orders_table
|
|
37
|
+
type: AgGridAlpine
|
|
38
|
+
properties:
|
|
39
|
+
rowData:
|
|
40
|
+
_request: get_orders
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`onMessage` fires once per render batch, not once per message — on a busy channel the batch holds every message since the last flush. The batch is available on the event:
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
events:
|
|
47
|
+
onMessage:
|
|
48
|
+
- id: use_batch
|
|
49
|
+
type: SetState
|
|
50
|
+
params:
|
|
51
|
+
latest_batch:
|
|
52
|
+
_event: messages # array of message payloads in this batch
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`onSubscribe` fires when the server acknowledges the subscription (including after an automatic reconnect). `onError` fires with `_event: message` when the channel errors.
|
|
56
|
+
|
|
57
|
+
## Reading Channel State with `_websocket`
|
|
58
|
+
|
|
59
|
+
The `_websocket` operator reads the channel's client state anywhere on the page:
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
_websocket: ticker.connected # boolean — subscription is live
|
|
63
|
+
_websocket: ticker.messages # array — retained payloads, newest last
|
|
64
|
+
_websocket: ticker.lastMessage # the most recent message payload
|
|
65
|
+
_websocket: ticker.lastMessage.tick # dot paths into the payload
|
|
66
|
+
_websocket: ticker.messageCount # total received this page visit (not capped)
|
|
67
|
+
_websocket: ticker.error # last error, null when healthy
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Unlike `_request`, there is no invocation history — a subscription is continuous. State resets when the page unmounts.
|
|
71
|
+
|
|
72
|
+
## Subscription Payloads
|
|
73
|
+
|
|
74
|
+
The subscription `payload` parameterizes the channel per subscriber. Client operators are evaluated when the subscription starts:
|
|
75
|
+
|
|
76
|
+
```yaml
|
|
77
|
+
pages:
|
|
78
|
+
- id: activity
|
|
79
|
+
type: PageHeaderMenu
|
|
80
|
+
subscriptions:
|
|
81
|
+
- websocketId: activity_feed
|
|
82
|
+
payload:
|
|
83
|
+
project_id:
|
|
84
|
+
_url_query: project_id
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
websockets:
|
|
89
|
+
- id: activity_feed
|
|
90
|
+
type: MongoDBChangeStream
|
|
91
|
+
connectionId: mongodb
|
|
92
|
+
properties:
|
|
93
|
+
pipeline:
|
|
94
|
+
- $match:
|
|
95
|
+
fullDocument.project_id:
|
|
96
|
+
_payload: project_id
|
|
97
|
+
fullDocument.owner_id:
|
|
98
|
+
_user: id
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The payload is evaluated once, at subscribe time. To subscribe with new values — say a changed filter — run [`Subscribe`](/websocket-publish) again: with a changed payload it replaces the open channel, and the channel state starts empty.
|
|
102
|
+
|
|
103
|
+
## Subscribing on Demand
|
|
104
|
+
|
|
105
|
+
A subscription with `client.subscribeOnMount: false` is declared on the page but opens only when a [`Subscribe`](/websocket-publish) action runs, and [`Unsubscribe`](/websocket-publish) closes it. Use it for a channel the page needs only some of the time, such as a chat panel that holds a change stream only while it is open:
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
subscriptions:
|
|
109
|
+
- websocketId: thread_messages
|
|
110
|
+
payload:
|
|
111
|
+
ticket_id:
|
|
112
|
+
_state: ticket_id
|
|
113
|
+
client:
|
|
114
|
+
subscribeOnMount: false
|
|
115
|
+
blocks:
|
|
116
|
+
- id: open_thread
|
|
117
|
+
type: Button
|
|
118
|
+
events:
|
|
119
|
+
onClick:
|
|
120
|
+
- id: set_ticket
|
|
121
|
+
type: SetState
|
|
122
|
+
params:
|
|
123
|
+
ticket_id: T-1
|
|
124
|
+
- id: subscribe
|
|
125
|
+
type: Subscribe
|
|
126
|
+
params: thread_messages # payload evaluates now, with ticket_id T-1
|
|
127
|
+
- id: close_thread
|
|
128
|
+
type: Button
|
|
129
|
+
events:
|
|
130
|
+
onClick:
|
|
131
|
+
- id: unsubscribe
|
|
132
|
+
type: Unsubscribe
|
|
133
|
+
params: thread_messages
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Until it is subscribed, the channel's `_websocket` state reads as not connected with no messages. The page still closes it when it unmounts.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# WebSockets
|
|
2
|
+
|
|
3
|
+
Lowdefy websockets add realtime updates to your app — live dashboards, notifications, and chat — without polling and without running a separate socket service. Channels are defined at the root of your Lowdefy configuration, pages subscribe to them, and the same Lowdefy server that serves your pages pushes messages to the browser over a single WebSocket connection.
|
|
4
|
+
|
|
5
|
+
Websockets work identically on a self-hosted Node.js server and on Vercel, where Fluid compute now accepts WebSocket connections natively — one deployment, no extra infrastructure, no token wiring. Authentication uses your app's existing session: the connection is authorized with the same user roles as [API endpoints](/api-endpoints).
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
A channel and a page subscription — this page shows a live tick counter:
|
|
10
|
+
|
|
11
|
+
```yaml
|
|
12
|
+
lowdefy: 6.1.0
|
|
13
|
+
|
|
14
|
+
websockets:
|
|
15
|
+
- id: ticker
|
|
16
|
+
type: Interval
|
|
17
|
+
properties:
|
|
18
|
+
ms: 1000
|
|
19
|
+
|
|
20
|
+
pages:
|
|
21
|
+
- id: dashboard
|
|
22
|
+
type: PageHeaderMenu
|
|
23
|
+
subscriptions:
|
|
24
|
+
- websocketId: ticker
|
|
25
|
+
blocks:
|
|
26
|
+
- id: ticks
|
|
27
|
+
type: Html
|
|
28
|
+
properties:
|
|
29
|
+
html:
|
|
30
|
+
_string.concat:
|
|
31
|
+
- 'Ticks: '
|
|
32
|
+
- _websocket: ticker.lastMessage.tick
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
When the page loads, the client opens a websocket connection, subscribes to `ticker`, and the block re-renders as messages arrive. When the user navigates away, the subscription ends and the channel's server source stops.
|
|
36
|
+
|
|
37
|
+
## How WebSockets Work
|
|
38
|
+
|
|
39
|
+
1. A page with `subscriptions` mounts. The client opens one shared WebSocket connection to the Lowdefy server (lazily — apps without websockets never connect).
|
|
40
|
+
2. For each subscription, the client evaluates the subscription `payload` (client-side operators like `_state`) and sends a subscribe frame.
|
|
41
|
+
3. The server authorizes the subscription against the channel's `auth` config, then evaluates the websocket `properties` server-side — `_payload` reads the subscription payload and `_user` reads the subscriber's session, so a channel can be user-specific.
|
|
42
|
+
4. Subscribers whose evaluated properties are identical share one running source on the server. The first subscriber starts it; the last one to leave stops it.
|
|
43
|
+
5. Messages from the source are pushed to all subscribers, update the channel state read by the [`_websocket`](/websocket-subscriptions) operator, and fire the subscription's `onMessage` event.
|
|
44
|
+
|
|
45
|
+
If the connection drops — a deploy, a network blip, or a serverless function reaching its time limit — the client reconnects with backoff and resubscribes automatically. Channel state on the page is preserved across reconnects.
|
|
46
|
+
|
|
47
|
+
## Websocket Definition
|
|
48
|
+
|
|
49
|
+
Websockets are defined in the top-level `websockets` array:
|
|
50
|
+
|
|
51
|
+
- `id: string`: __Required__ - A unique identifier for the channel.
|
|
52
|
+
- `type: string`: __Required__ - The websocket type. `Channel` and `Interval` ship with Lowdefy; connection plugins provide types like [`MongoDBChangeStream`](/MongoDB).
|
|
53
|
+
- `connectionId: string`: The `id` of a [connection](/connections) for connection-backed types.
|
|
54
|
+
- `properties: object`: Settings for the type. __Operators are evaluated server-side per subscription__ — `_secret`, `_user`, and `_payload` are available.
|
|
55
|
+
|
|
56
|
+
###### A user-specific channel:
|
|
57
|
+
```yaml
|
|
58
|
+
websockets:
|
|
59
|
+
- id: my_feed
|
|
60
|
+
type: MongoDBChangeStream
|
|
61
|
+
connectionId: mongodb
|
|
62
|
+
properties:
|
|
63
|
+
pipeline:
|
|
64
|
+
- $match:
|
|
65
|
+
fullDocument.owner_id:
|
|
66
|
+
_user: id
|
|
67
|
+
fullDocument.category:
|
|
68
|
+
_payload: category
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Because `properties` evaluate per subscription, two users subscribing to `my_feed` get two independent server sources — but a thousand subscribers to a channel with static properties share just one.
|
|
72
|
+
|
|
73
|
+
A [module](/module-authoring) can ship websockets in its manifest's `websockets:` section. Their ids are scoped to the module entry (`support/thread-messages`), module pages subscribe with [`_module.websocketId`](/_module), and `auth.websockets` rules match the scoped ids (for example `support/**`). When the app has auth, a module websocket needs a signed-in caller unless the module's manifest or an app `auth.websockets.public` rule makes it public.
|
|
74
|
+
|
|
75
|
+
## Core Types
|
|
76
|
+
|
|
77
|
+
- `Channel` — a pure pub/sub relay. Clients publish messages with the [`Publish`](/websocket-publish) action and the server broadcasts them to all subscribers. Set `properties.publish: true` to allow publishing.
|
|
78
|
+
- `Interval` — emits `{ tick, at }` every `properties.ms` milliseconds (default 1000, minimum 100). Useful for examples and testing.
|
|
79
|
+
|
|
80
|
+
## Securing Channels
|
|
81
|
+
|
|
82
|
+
Channel access follows the same pattern as [protected API endpoints](/api-endpoints). Configure `auth.websockets` with `public`, `protected`, and `roles` lists:
|
|
83
|
+
|
|
84
|
+
```yaml
|
|
85
|
+
auth:
|
|
86
|
+
websockets:
|
|
87
|
+
roles:
|
|
88
|
+
admin:
|
|
89
|
+
- admin_feed # only users with the admin role may subscribe
|
|
90
|
+
public:
|
|
91
|
+
- ticker # everyone else requires a session
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Unauthorized subscriptions receive the same response as subscriptions to channels that do not exist.
|
|
95
|
+
|
|
96
|
+
An open connection follows the session. The server checks the caller again on every subscribe and at least once a minute. When the user signs out, the session ends, the membership is removed, the roles change or the user switches organization, the server closes the connection and the client reconnects straight away as the current caller. Subscriptions the current caller may not hold fail as they would on a freshly loaded page.
|
|
97
|
+
|
|
98
|
+
## What's Next
|
|
99
|
+
|
|
100
|
+
- [Page Subscriptions](/websocket-subscriptions) — Subscribe pages to channels, handle messages with events, and read channel state with `_websocket`.
|
|
101
|
+
- [Publish and Actions](/websocket-publish) — Client publishing, the `Publish`, `Subscribe` and `Unsubscribe` actions, and deployment notes.
|
package/hazards.json
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"id": "state-in-request-properties",
|
|
4
|
+
"appliesTo": { "kinds": ["requests"] },
|
|
5
|
+
"message": "_state in request properties is always undefined — a request is evaluated on the server with an empty state. Pass the value in the payload and read it with _payload.",
|
|
6
|
+
"see": "concepts/connections-and-requests"
|
|
7
|
+
},
|
|
8
|
+
{
|
|
9
|
+
"id": "visible-false-prunes-state",
|
|
10
|
+
"appliesTo": { "kinds": ["blocks"] },
|
|
11
|
+
"message": "visible: false removes the block and its state. Style it hidden (for example style: { display: none }) to keep the value.",
|
|
12
|
+
"see": "concepts/lowdefy-schema"
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"id": "link-same-page-no-onmount",
|
|
16
|
+
"appliesTo": { "types": ["Link"] },
|
|
17
|
+
"message": "A Link to the page already open does not remount it, so onMount does not fire again. Trigger the reload chain from the same action list.",
|
|
18
|
+
"see": "actions/link"
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"id": "ref-njk-renders-at-build",
|
|
22
|
+
"appliesTo": { "types": ["_ref"] },
|
|
23
|
+
"message": "A _ref to a .njk file renders at build, so _state, _request and _user are undefined inside it. Use _nunjucks over a .txt file for a template that needs runtime values.",
|
|
24
|
+
"see": "operators/_ref"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"id": "ref-js-imported-as-module",
|
|
28
|
+
"appliesTo": { "types": ["_ref"] },
|
|
29
|
+
"message": "A _ref to a .js file imports it as a module rather than reading it as text. Name the file .js.txt to read its source.",
|
|
30
|
+
"see": "operators/_ref"
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"id": "tenant-wall-lookup",
|
|
34
|
+
"appliesTo": { "kinds": ["requests"], "when": "connectionTenantNotNone" },
|
|
35
|
+
"message": "This request runs over a tenant-walled connection. The wall injects { $match: { <tenant field> } } into the top-level pipeline and into every $lookup / $unionWith sub-pipeline, so a lookup into a collection with no tenant field returns [] with no error. Run the request over the shared connection and pass tenant facts in the payload instead.",
|
|
36
|
+
"see": "concepts/connections-and-requests"
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"id": "reject-not-caught",
|
|
40
|
+
"appliesTo": { "types": [":reject"] },
|
|
41
|
+
"message": ":reject is the routine's reply, not an exception. A :catch never runs for it, :finally does, and :throw is the caught path.",
|
|
42
|
+
"see": "controls/reject"
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"id": "setstate-parent-keeps-hidden-inputs",
|
|
46
|
+
"appliesTo": { "types": ["SetState"] },
|
|
47
|
+
"message": "Setting a parent object to {} or null does not clear an input that is hidden at that moment: the input keeps its last value and writes it back to state when it shows again. Set each input's own key to null instead.",
|
|
48
|
+
"see": "actions/setstate"
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"id": "validate-no-cascade",
|
|
52
|
+
"appliesTo": { "types": ["Validate", "ResetValidation"] },
|
|
53
|
+
"message": "blockIds match exact block IDs and do not cascade to child blocks. A container's ID, or an ID that matches no block, validates nothing and succeeds. Match the inputs instead, for example regex: ^contact\\. for the inputs under contact.",
|
|
54
|
+
"see": "actions/validate"
|
|
55
|
+
}
|
|
56
|
+
]
|