@lowdefy/docs-content 7.2.0 → 7.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/content/adapter-reference/mongodbauthadapter.md +2 -2
  2. package/content/agents/agent-properties.md +2 -2
  3. package/content/agents/agent-server-hooks.md +1 -1
  4. package/content/agents/agents-introduction.md +1 -1
  5. package/content/callback-reference/auth0logoutcallback.md +1 -1
  6. package/content/concepts/ai-agent-docs.md +1 -1
  7. package/content/concepts/blocks.md +1 -1
  8. package/content/concepts/connections-and-requests.md +8 -8
  9. package/content/concepts/custom-html.md +1 -1
  10. package/content/concepts/dynamic-page-content.md +1 -0
  11. package/content/concepts/logger.md +1 -1
  12. package/content/concepts/lowdefy-api.md +3 -3
  13. package/content/concepts/page-and-app-state.md +2 -2
  14. package/content/concepts/theming.md +1 -1
  15. package/content/connections/axioshttp.md +39 -5
  16. package/content/deployment/vercel.md +4 -2
  17. package/content/input-blocks/ratingslider.md +1 -0
  18. package/content/migration/v3-to-v4.md +2 -2
  19. package/content/operators/_api.md +11 -9
  20. package/content/operators/_ref.md +6 -6
  21. package/content/provider-reference/auth-js-providers.md +2 -2
  22. package/content/provider-reference/openidconnectprovider.md +1 -1
  23. package/content/testing/config-tests.md +2 -0
  24. package/content/tutorial/tutorial-create-page.md +1 -1
  25. package/content/tutorial/tutorial-requests-api.md +1 -1
  26. package/content/tutorial/tutorial-requests-sql.md +1 -1
  27. package/content/tutorial/tutorial-start.md +1 -1
  28. package/content/user-authentication/auth-configuration.md +9 -9
  29. package/content/user-authentication/auth-steps.md +2 -2
  30. package/content/user-authentication/organizations.md +11 -1
  31. package/content/user-authentication/protected-pages-apis.md +4 -4
  32. package/content/user-authentication/roles.md +2 -2
  33. package/content/user-authentication/user-object.md +1 -1
  34. package/content/websockets/websocket-publish.md +2 -2
  35. package/content/websockets/websocket-subscriptions.md +26 -1
  36. package/content/websockets/websockets-introduction.md +56 -3
  37. package/index.json +16 -16
  38. package/package.json +2 -2
@@ -18,7 +18,7 @@ If you are upgrading from the old `MongoDBAdapter`: the type is renamed, `databa
18
18
  ###### Minimum configuration.
19
19
 
20
20
  ```yaml
21
- lowdefy: 7.1.0
21
+ lowdefy: 7.4.0
22
22
  auth:
23
23
  database:
24
24
  id: auth_db
@@ -31,7 +31,7 @@ auth:
31
31
  ###### Full configuration.
32
32
 
33
33
  ```yaml
34
- lowdefy: 7.1.0
34
+ lowdefy: 7.4.0
35
35
  auth:
36
36
  database:
37
37
  id: auth_db
@@ -7,7 +7,7 @@ Agent properties configure the model and its behavior. They are set in the `prop
7
7
  - `model: string`: __Required__ - The model identifier (e.g. `claude-sonnet-4-20250514`, `gpt-4o`, `gemini-2.5-pro`).
8
8
  - `instructions: string`: System instructions that guide the agent's behavior. This is the system prompt sent to the model with every request. The string passes through the operator parser at request time, so `_t:` works for locale-aware prompts (see [i18n](/i18n)). Note: tool descriptions stay English — translating them can degrade tool-call accuracy on English-trained models.
9
9
  - `pageContext: boolean`: Default: `false` - When `true`, prepend context about the current page, user, conversation, URL query, path parameters and shared state to the instructions. URL query and shared state are only included when the [`AgentChat`](/AgentChat) block sends them as `urlQuery` and `sharedState`. Path parameters, the values of the placeholders in the page's [`path`](/page-paths), are sent by the block on a page with a path, and included when there are any. Useful when the agent needs to know who it's talking to or what the user has typed into form fields.
10
- - `generateTitle: boolean`: Default: `false` - When `true`, generate a short title from the first user message on the first turn of a conversation. Emits a `data-chat-title` data part that fires the [`AgentChat`](/AgentChat) block's `onTitleGenerated` event. Runs concurrently with the response and is non-fatal — a failed title generation logs a warning and does not break the turn.
10
+ - `generateTitle: boolean`: Default: `false` - When `true`, generate a short title from the first exchange of a conversation: the user's first message and the first 1,200 characters of the assistant's first reply. Titling from the reply means chats that open with the same suggested prompt still get titles that name their subject. The title is generated once the first reply is complete, before the response stream closes, and emitted as a `data-chat-title` data part that fires the [`AgentChat`](/AgentChat) block's `onTitleGenerated` event. A first reply that waits on a tool approval or a client tool is titled when it completes. A turn that fails is not titled, and a retry of it is. The title call uses the agent's `model`, `timeout` and `providerOptions`, so settings such as the AI Gateway's `zeroDataRetention` and `only`, OpenAI's `store` and Gemini's `safetySettings` apply to it as they do to the agent's own calls. Thinking and reasoning settings are the exception: the title call asks the model for no reasoning. A failed title generation logs a warning and does not break the turn.
11
11
 
12
12
  ###### Instructions with user context:
13
13
  ```yaml
@@ -175,7 +175,7 @@ A file in a chat or a `CallAgent` step goes to the model as a link when the prov
175
175
 
176
176
  ## Provider-Specific Properties
177
177
 
178
- - `providerOptions: object`: Pass provider-specific options directly to the AI SDK. Use this for options not covered by the properties above.
178
+ - `providerOptions: object`: Pass provider-specific options directly to the AI SDK. Use this for options not covered by the properties above. These options also apply to the title call `generateTitle` makes, except thinking and reasoning settings.
179
179
 
180
180
  Each agent type also has its own properties. See the connection pages for details:
181
181
 
@@ -108,7 +108,7 @@ api:
108
108
 
109
109
  ## Generating Titles
110
110
 
111
- > **Built-in option:** set the agent's [`generateTitle`](/agent-properties) property to `true` and Lowdefy generates a short title from the first user message automatically, emitting the `data-chat-title` part for you. The manual approach below is only needed when you want custom title logic.
111
+ > **Built-in option:** set the agent's [`generateTitle`](/agent-properties) property to `true` and Lowdefy generates a short title from the first exchange (the user's first message and the assistant's first reply) automatically, emitting the `data-chat-title` part for you. The manual approach below is only needed when you want custom title logic.
112
112
 
113
113
  Use a `data-chat-title` data part to send a generated title back to the client. The [`AgentChat`](/AgentChat) block fires an `onTitleGenerated` event when it receives this data part.
114
114
 
@@ -9,7 +9,7 @@ Agents are defined at the root of your Lowdefy configuration, alongside `connect
9
9
  A connection, an agent, and a chat block — that's all you need:
10
10
 
11
11
  ```yaml
12
- lowdefy: 7.1.0
12
+ lowdefy: 7.4.0
13
13
 
14
14
  connections:
15
15
  - id: anthropic
@@ -16,7 +16,7 @@ To trigger the Auth0 logout, the `Logout` action `callbackUrl.url` param should
16
16
  ###### Configuring Auth0LogoutCallback.
17
17
 
18
18
  ```yaml
19
- lowdefy: 7.1.0
19
+ lowdefy: 7.4.0
20
20
  providers:
21
21
  - id: auth0
22
22
  type: Auth0Provider
@@ -65,7 +65,7 @@ Agents manage the dev server with these tools, and never run `lowdefy dev`, choo
65
65
  | `lowdefy_dev_stop` | Stop the app's dev server if the hub started it |
66
66
  | `lowdefy_dev_status` | Owner, state, URL and build status, without starting anything |
67
67
  | `lowdefy_dev_logs` | Recent output of a hub-started dev server, optionally filtered |
68
- | `lowdefy_run_tests` | Run the app's journeys against its dev server, as `lowdefy test` does: all of them, a folder or glob (`paths`), or a tagged section (`tags`), narrowed by name with `filter`. Returns each result as data |
68
+ | `lowdefy_run_tests` | Run the app's journeys against its dev server, as `lowdefy test` does: all of them, a folder or glob (`paths`), or a tagged section (`tags`), narrowed by name with `filter`. Returns a summary and the failures; all results go to `.lowdefy/test/results.json` |
69
69
  | `lowdefy_dev_list` | Dev servers across the checkout's apps and other checkouts |
70
70
 
71
71
  The dev server itself also serves the MCP endpoint over streamable HTTP at `/lowdefy-docs/mcp`, for clients that connect by URL. Through `lowdefy mcp`, restart is `lowdefy_dev_start` with `restart: true` rather than `lowdefy_restart`.
@@ -35,7 +35,7 @@ Lowdefy has a set of default block types as defined in the Lowdefy docs. Most of
35
35
 
36
36
  ###### Default block type config example:
37
37
  ```yaml
38
- lowdefy: 7.1.0
38
+ lowdefy: 7.4.0
39
39
  pages:
40
40
  - id: example_dashboard
41
41
  type: PageHeaderMenu
@@ -22,7 +22,7 @@ The schema for a Lowdefy connection is:
22
22
 
23
23
  ###### Connections definition example:
24
24
  ```yaml
25
- lowdefy: 7.1.0
25
+ lowdefy: 7.4.0
26
26
  connections:
27
27
  - id: connection1
28
28
  type: ConnectionType1
@@ -100,7 +100,7 @@ _request: my_request
100
100
 
101
101
  ###### lowdefy.yaml
102
102
  ```yaml
103
- lowdefy: 7.1.0
103
+ lowdefy: 7.4.0
104
104
 
105
105
  connections:
106
106
  - id: connection1
@@ -142,7 +142,7 @@ To create this `connection`, define the connection as follows in the `lowdefy.ya
142
142
 
143
143
  ###### lowdefy.yaml
144
144
  ```yaml
145
- lowdefy: 7.1.0
145
+ lowdefy: 7.4.0
146
146
 
147
147
  connections:
148
148
  - id: my_api
@@ -159,7 +159,7 @@ To use this connection, a `request` must be defined, which references the corres
159
159
 
160
160
  ###### lowdefy.yaml
161
161
  ```yaml
162
- lowdefy: 7.1.0
162
+ lowdefy: 7.4.0
163
163
 
164
164
  connections:
165
165
  - id: my_api
@@ -183,7 +183,7 @@ This request should be called when the page is mounted. To do this, the [`Reques
183
183
 
184
184
  ###### lowdefy.yaml
185
185
  ```yaml
186
- lowdefy: 7.1.0
186
+ lowdefy: 7.4.0
187
187
 
188
188
  connections:
189
189
  - id: my_api
@@ -214,7 +214,7 @@ In this example, a [`Selector`](/Selector) block will be added. The [`_array.map
214
214
 
215
215
  ###### lowdefy.yaml
216
216
  ```yaml
217
- lowdefy: 7.1.0
217
+ lowdefy: 7.4.0
218
218
 
219
219
  connections:
220
220
  - id: my_api
@@ -259,7 +259,7 @@ To do this, create a new request that will make use of a `payload` to get the po
259
259
 
260
260
  ###### lowdefy.yaml
261
261
  ```yaml
262
- lowdefy: 7.1.0
262
+ lowdefy: 7.4.0
263
263
 
264
264
  connections:
265
265
  - id: my_api
@@ -321,7 +321,7 @@ This is done as follows:
321
321
 
322
322
  ###### lowdefy.yaml
323
323
  ```yaml
324
- lowdefy: 7.1.0
324
+ lowdefy: 7.4.0
325
325
 
326
326
  connections:
327
327
  - id: my_api
@@ -25,7 +25,7 @@ To add [Google Analytics](/https://developers.google.com/analytics/devguides/col
25
25
 
26
26
  ```yaml
27
27
  name: google-analytics-example
28
- lowdefy: 7.1.0
28
+ lowdefy: 7.4.0
29
29
  # ...
30
30
  app:
31
31
  html:
@@ -246,6 +246,7 @@ The policy checks a value as a URL where it is used as a link or a source: `href
246
246
  Everywhere else a URL is plain text:
247
247
 
248
248
  - **Text a block draws.** A block's properties schema marks how it draws a string (`textKind`). In a property it draws as HTML, such as a `Descriptions` item value, a `Paragraph` content, an input `title` or a `Selector` option label, a whole URL, a markdown link, a word starting with `//` and (unless the policy allows HTML) a CSS `url()` are words, since nothing there reads them as a link. The `html` rule still applies there, so text a block draws as HTML shows as written only when it is HTML-escaped (`&lt;` for `<`, `&amp;` for `&`). In a property it draws as escaped text, such as a `ControlledList` title, tag syntax is words too. When the policy allows HTML, a link or source attribute (`href`, `src`, `srcset`) in any string not drawn as escaped text is judged as a link or source, as a `url` or `src` property is.
249
+ - **Object keys and slot names.** A block can draw a key as well as a value: the keys of a `Descriptions` `items` object are its labels, and `Tabs` and `Collapse` draw slot names as titles. No schema marks how a key is drawn, so every object key and every slot or area name keeps every check a string no schema marks gets: the `html` rule and every URL check. Keys in data are not checked, since data is never drawn.
249
250
  - **State.** When the policy sets a `state` path, `SetState` values, such as a form's prefill, are data: no block property can read state (properties are literal). A URL or tag syntax in them is text, and only the operator rules apply. Without a `state` path the content may write any page state, so its `SetState` values keep every check. A value bound to an input in the content whose value is an object, such as a rich text editor, an upload or a table input, keeps every check, since those inputs draw parts of their value as markup, links or images. The content may read data state (`SetState` values, and the state of an input whose option values or rows are data) only in a `CallAPI`'s params, an action's `skip`, a `SetState` value, or an `:if` or `:case` condition. A `_state` read of it anywhere else, such as a `DisplayMessage`'s content, fails with `policy.state`. The page around the Dynamic block owns the state under the policy's `state` path: anything there that draws it as HTML or follows it as a link must treat it as untrusted input, whatever the policy's `html` setting.
250
251
  - **Option values.** A `Selector` or `MultipleSelector` option `value` beside a `label` is data (`textKind: data`); the `label` is drawn as HTML. An option without a `label` draws its `value` as HTML in its place, so that value keeps every check.
251
252
  - **Table cells.** When every column of a `Table` or `TableLight` draws its cell as text (`text`, `email`, `phone`, `number`, `currency`, `percent`, `progress`, `rating`, `date`, `datetime`, `boolean`, `tag`, `tags`, `status` or `json`, or no type), its `data` rows are data. A `url`, `link`, `relation`, `image`, `avatar`, `people`, `html`, `buttons` or `menu` column draws or follows row values, a `cell.colorFrom` reads a row field into a colour, and an `expandable.template` draws row fields as HTML, so their table's rows keep every check.
@@ -28,7 +28,7 @@ For client-side error capture, you also need to expose the DSN to the browser:
28
28
  You can customize Sentry behavior using the `logger` configuration in your `lowdefy.yaml`:
29
29
 
30
30
  ```yaml
31
- lowdefy: 7.1.0
31
+ lowdefy: 7.4.0
32
32
 
33
33
  logger:
34
34
  sentry:
@@ -42,7 +42,7 @@ The schema for a Lowdefy API is:
42
42
  ###### API definition example:
43
43
 
44
44
  ```yaml
45
- lowdefy: '7.1.0'
45
+ lowdefy: '7.4.0'
46
46
 
47
47
  connections:
48
48
  - id: users
@@ -77,7 +77,7 @@ Lowdefy APIs use the same [authorization configuration](/protected-pages-apis) a
77
77
  Unlike requests which are defined on a specific page and inherit the authorization of the page they are defined on, API endpoints can be called from any page in the app. Thus they do not inherit the authorization of the page they are called from, and authorization should be configured separately.
78
78
 
79
79
  ```yaml
80
- lowdefy: '7.1.0'
80
+ lowdefy: '7.4.0'
81
81
 
82
82
  auth:
83
83
  # Configure which APIs require authentication
@@ -1235,7 +1235,7 @@ blocks:
1235
1235
  Here's a comprehensive example showing various features:
1236
1236
 
1237
1237
  ```yaml
1238
- lowdefy: '7.1.0'
1238
+ lowdefy: '7.4.0'
1239
1239
  auth:
1240
1240
  api:
1241
1241
  protected: true
@@ -83,7 +83,7 @@ This example shows how you can create and read from `global`:
83
83
 
84
84
  `lowdefy.yaml`
85
85
  ```yaml
86
- lowdefy: 7.1.0
86
+ lowdefy: 7.4.0
87
87
  global:
88
88
  key: value
89
89
  pages:
@@ -101,7 +101,7 @@ The following examples shows how to modify the `global` object:
101
101
 
102
102
  `lowdefy.yaml`
103
103
  ```yaml
104
- lowdefy: 7.1.0
104
+ lowdefy: 7.4.0
105
105
  global:
106
106
  key: value
107
107
  pages:
@@ -7,7 +7,7 @@ Lowdefy uses the [Ant Design](https://ant.design/) design token system for themi
7
7
  Configure your app's theme in `lowdefy.yaml` under `theme.antd`:
8
8
 
9
9
  ```yaml
10
- lowdefy: 7.1.0
10
+ lowdefy: 7.4.0
11
11
  theme:
12
12
  antd:
13
13
  token:
@@ -4,10 +4,41 @@ The `AxiosHttp` connection is used to connect to APIs and web servers using HTTP
4
4
 
5
5
  It uses the [axios](https://github.com/axios/axios) library.
6
6
 
7
- The same properties can be set on both connections and requests. The properties will be merged, with the request properties overwriting connection properties. This allows properties like authentication headers and the baseURL to be set on the connection, with request specific properties like the request.
7
+ Most properties can be set on both connections and requests. The properties will be merged, with the request properties overwriting connection properties. This allows properties like authentication headers and the baseURL to be set on the connection, with request specific properties like the request. The properties that decide where the server may connect (`allowInternalAddresses`, `allowedHosts`, `allowAbsoluteUrls`, `proxy`, `socketPath`, `httpVersion`, `httpAgentOptions` and `httpsAgentOptions`) can only be set on the connection, since request properties can be filled from the client payload.
8
8
 
9
9
  >Secrets like authentication headers and API keys should be stored using the [`_secret`](_secret) operator.
10
10
 
11
+ ## Internal addresses
12
+
13
+ By default, `AxiosHttp` only connects to public addresses. A request to localhost, a private network (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), a link-local address such as the cloud metadata endpoint `169.254.169.254`, or another address that is not public, fails. A hostname is checked by the address it resolves to, and every redirect is checked too.
14
+
15
+ This matters when a request takes its URL, or part of it, from the payload. Without the check, a user could point the request at a service the server can reach but the internet cannot, such as a database admin page or the cloud metadata endpoint, which hands out the server's cloud credentials.
16
+
17
+ To call a service on the same machine or network, such as an API on localhost, a Docker Compose service name or an API on a private network, set `allowInternalAddresses: true` on the connection:
18
+
19
+ ```yaml
20
+ connections:
21
+ - id: orders_service
22
+ type: AxiosHttp
23
+ properties:
24
+ baseURL: http://orders-service:8080
25
+ allowInternalAddresses: true
26
+ ```
27
+
28
+ Without `allowInternalAddresses`, the server connects directly: the `HTTP_PROXY` and `HTTPS_PROXY` environment variables are ignored, and `proxy`, `socketPath` and `httpVersion: 2` fail, since the server cannot check where they connect.
29
+
30
+ To limit a connection to known hosts, list them in `allowedHosts`. A request to any other host, or a redirect to one, fails. `allowedHosts` applies alongside the address check: an internal host must be listed and the connection must set `allowInternalAddresses: true`.
31
+
32
+ ```yaml
33
+ connections:
34
+ - id: partner_api
35
+ type: AxiosHttp
36
+ properties:
37
+ baseURL: https://api.partner.com
38
+ allowedHosts:
39
+ - api.partner.com
40
+ ```
41
+
11
42
  ## Connections
12
43
 
13
44
  Connection types:
@@ -38,14 +69,17 @@ Request types:
38
69
  - `auth: object`: Indicates that HTTP Basic authorization should be used, and supplies credentials. This will set an `Authorization` header, overwriting any existing `Authorization` custom headers you have set using `headers`. Only HTTP Basic auth is configurable through this parameter, for Bearer tokens and such, use `Authorization` custom headers instead. The `auth` object should have the following fields:
39
70
  - `username: string`
40
71
  - `password: string`
41
- - `httpAgentOptions: object`: Options to pass to the Node.js [`http.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
42
- - `httpsAgentOptions: object`: Options to pass to the Node.js [`https.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
72
+ - `allowInternalAddresses: boolean`: Default: `false` - Connection only. Allow requests to addresses that are not public, such as localhost, private networks and the cloud metadata endpoint. Also needed for `proxy`, `socketPath` and `httpVersion: 2`. See [Internal addresses](#internal-addresses).
73
+ - `allowedHosts: string[]`: Connection only. The hostnames requests may connect to, matched exactly and ignoring case (no wildcards or ports). A request to any other host, or a redirect to one, fails.
74
+ - `httpAgentOptions: object`: Connection only. Options to pass to the Node.js [`http.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
75
+ - `httpsAgentOptions: object`: Connection only. Options to pass to the Node.js [`https.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
43
76
  - `maxContentLength: number`: Defines the max size of the http response content allowed in bytes.
44
77
  - `maxRedirects: number`: Defines the maximum number of redirects to follow. If set to 0, no redirects will be followed.
45
- - `proxy: object`: Defines the hostname and port of the proxy server. The `proxy` object should have the following fields:
78
+ - `proxy: object`: Connection only, and needs `allowInternalAddresses: true`. Defines the hostname and port of the proxy server. The `proxy` object should have the following fields:
46
79
  - `host: string`: Host IP address (eg. `'127.0.0.1'`).
47
80
  - `port: number`: Port number.
48
81
  - `auth: object`: Object with username and password.
82
+ - `socketPath: string`: Connection only, and needs `allowInternalAddresses: true`. A Unix socket to send requests to instead of a host.
49
83
  - `responseType: enum`: Default: `'json'` - The type of data that the server will respond with. Options are:
50
84
  - `'document'`
51
85
  - `'json'`
@@ -64,7 +98,7 @@ Properties for a AxiosHttp can be set on either the connection, the request, or
64
98
  ###### A basic full example requesting data from https://jsonplaceholder.typicode.com
65
99
 
66
100
  ```yaml
67
- lowdefy: 7.1.0
101
+ lowdefy: 7.4.0
68
102
  name: Lowdefy starter
69
103
  connections:
70
104
  - id: my_api
@@ -50,7 +50,7 @@ config:
50
50
  memory: 2048 # MB — omit to use the Vercel default
51
51
  ```
52
52
 
53
- - **`maxDuration`** — the hard cap on function execution time, in seconds. Defaults to `60`. Your plan's limits apply; Vercel rejects an over-limit value at deploy time.
53
+ - **`maxDuration`** — the hard cap on function execution time, in seconds. Defaults to `60`. Your plan's limits apply; Vercel rejects an over-limit value at deploy time. It also bounds each websocket connection: the server closes it 5 seconds before the limit and the client reconnects.
54
54
  - **`memory`** — function memory in MB. Omit to use the Vercel default.
55
55
 
56
56
  Each build writes these into the generated `.vercel/output/functions/api.func/.vc-config.json`. The output is regenerated on every deploy, so there is nothing to edit by hand — and because the deployment is prebuilt (Build Output API), `functions` settings in `vercel.json` or the dashboard's function defaults do not apply; `lowdefy.yaml` is the single source of truth.
@@ -119,8 +119,10 @@ Vercel Fluid bills by execution duration, so a request that hangs (a stuck datab
119
119
 
120
120
  Keep `config.requestTimeout` below `maxDuration`: when it is not, Vercel stops the function before the request timeout answers, so the upstream calls the request left running are not cancelled and the request ends without a logged timeout. The build warns when `config.requestTimeout` is not shorter than `maxDuration` (or than the 60-second default, when it runs on Vercel).
121
121
 
122
+ Give each agent a `timeout` below `maxDuration`, on the agent or on its connection. A chat turn is exempt from `config.requestTimeout` and runs on after its client disconnects, so without one only `maxDuration` stops it: the stream then ends without an error and the agent's `onFinish` hooks, which save the conversation, never run. The build warns for an agent with no timeout, or with one not shorter than `maxDuration`.
123
+
122
124
  On Vercel, only the request timeout cancels an AI model call a request is waiting on. A client that disconnects does not: the call runs until it finishes, reaches its own `timeout`, or hits the request timeout. On the Node server a disconnect cancels it too.
123
125
 
124
- > The function runs on Vercel's Node.js runtime. Streaming agent responses (`/api/agent/*`) are exempt from `config.requestTimeout` and are bounded only by `maxDuration` — for heavy streaming or agent workloads, a long-lived Node host (Docker, Fly.io, Railway, Render) may suit better. An agent run keeps running to the end when its client disconnects, so its work completes; a `GET` stream (such as an SSE feed) stops when its client goes, instead of holding the function until `maxDuration`. The MCP endpoint answers `GET` with 405, so an MCP client holds no stream open.
126
+ > The function runs on Vercel's Node.js runtime. Streaming agent responses (`/api/agent/*`) are exempt from `config.requestTimeout` and are bounded by the agent's own `timeout` and `maxDuration` — for heavy streaming or agent workloads, a long-lived Node host (Docker, Fly.io, Railway, Render) may suit better. An agent run keeps running to the end when its client disconnects, so its work completes; a `GET` stream (such as an SSE feed) stops when its client goes, instead of holding the function until `maxDuration`. The MCP endpoint answers `GET` with 405, so an MCP client holds no stream open.
125
127
 
126
128
  All other Vercel configuration like domain names, preview deploy branches, serverless regions and redirects can be configured as desired.
@@ -669,6 +669,7 @@ Rating slider with customizable range, icons, and N/A option.
669
669
  | `label.hasFeedback` | boolean | `true` | Display feedback extra from validation, this does not disable validation. |
670
670
  | `label.inline` | boolean | `false` | Render input and label inline. |
671
671
  | `label.wrap` | boolean | `false` | Wrap long label text onto multiple lines when the label is inline. Labels above their input always wrap. |
672
+ | `marks` | object | - | Tick marks on the slider. Keys are slider values and values are labels: a string, or `{ style, label }` as antd takes. Replaces the marks `showMarks` draws, including the blank mark one step below `min`. Example: { 0: "0", 5: "5", 10: "10" }. |
672
673
  | `min` | number | `0` | The minimum value of the slider. |
673
674
  | `max` | number | `10` | The maximum value of the slider. |
674
675
  | `notApplicableLabel` | string | `"N/A"` | Label shown at the null value of the slider. |
@@ -363,7 +363,7 @@ blocks:
363
363
  The `LOWDEFY_SERVER_BASE_PATH` environment variable configuration option has been removed. To configure a base path, use the `config.basePath` configuration option.
364
364
 
365
365
  ``yaml
366
- lowdefy: 7.1.0
366
+ lowdefy: 7.4.0
367
367
 
368
368
  config:
369
369
  basePath: /foo
@@ -371,7 +371,7 @@ config:
371
371
 
372
372
  The `_build.env` operator can be used to set the base path using an environment variable:
373
373
  ```yaml
374
- lowdefy: 7.1.0
374
+ lowdefy: 7.4.0
375
375
 
376
376
  config:
377
377
  basePath:
@@ -97,42 +97,44 @@ events:
97
97
  type: CallAPI
98
98
  params:
99
99
  endpointId: get_products
100
+ holdValue: true # Without holdValue, _api returns null while the call is loading
100
101
  - id: set_products_list
101
102
  type: SetState
102
103
  params:
103
- products_list
104
- _api: fetch_products.response.products
104
+ products_list:
105
+ _api: get_products.response.products
105
106
 
106
107
  blocks:
107
108
  - id: loading_text
108
109
  type: Html
109
110
  visible:
110
- _api: fetch_products.loading # Show loading text while API is loading
111
+ _api: get_products.loading # Show loading text while API is loading
111
112
  properties:
112
113
  html: '<div class="secondary">Loading...</div>'
113
114
 
114
115
  - id: error_message
115
116
  type: Alert
116
117
  visible:
117
- _not:
118
- _api: fetch_products.success
118
+ _eq: # success is null while the call is loading
119
+ - _api: get_products.success
120
+ - false
119
121
  properties:
120
122
  type: error
121
123
  message:
122
124
  _if:
123
125
  test:
124
- _api: fetch_products.error
126
+ _api: get_products.error
125
127
  then:
126
- _api: fetch_products.error.message
128
+ _api: get_products.error.message
127
129
  else: 'An error occurred'
128
130
 
129
131
  - id: products_list
130
132
  type: List
131
133
  visible:
132
134
  _and:
133
- - _api: fetch_products.success
135
+ - _api: get_products.success
134
136
  - _not:
135
- _api: fetch_products.loading
137
+ _api: get_products.loading
136
138
  ```
137
139
 
138
140
  ###### Working with multiple API calls:
@@ -82,7 +82,7 @@ The file path to the referenced file, from the root of the project directory.
82
82
  ###### Reference pages:
83
83
  ```yaml
84
84
  # lowdefy.yaml
85
- lowdefy: 7.1.0
85
+ lowdefy: 7.4.0
86
86
  pages:
87
87
  - _ref: pages/page1.yaml
88
88
  - _ref: pages/page2.yaml
@@ -103,7 +103,7 @@ blocks:
103
103
  ```
104
104
  Returns:
105
105
  ```
106
- lowdefy: 7.1.0
106
+ lowdefy: 7.4.0
107
107
  pages:
108
108
  - id: page1
109
109
  type: PageHeaderMenu
@@ -176,7 +176,7 @@ blocks:
176
176
  ###### Use key:
177
177
  ```yaml
178
178
  # lowdefy.yaml
179
- lowdefy: 7.1.0
179
+ lowdefy: 7.4.0
180
180
  version:
181
181
  _ref:
182
182
  path: package.json
@@ -190,7 +190,7 @@ version:
190
190
  ```
191
191
  Returns:
192
192
  ```
193
- lowdefy: 7.1.0
193
+ lowdefy: 7.4.0
194
194
  version: 1.0.0
195
195
  ```
196
196
 
@@ -227,7 +227,7 @@ module.exports = useLocalOrSharedConfig;
227
227
 
228
228
  ```yaml
229
229
  // lowdefy.yaml
230
- lowdefy: 7.1.0
230
+ lowdefy: 7.4.0
231
231
 
232
232
  cli:
233
233
  refResolver: resolvers/useLocalOrSharedConfig.js
@@ -253,7 +253,7 @@ module.exports = addFooter;
253
253
  ```
254
254
  ```yaml
255
255
  // lowdefy.yaml
256
- lowdefy: 7.1.0
256
+ lowdefy: 7.4.0
257
257
 
258
258
  pages:
259
259
  - _ref:
@@ -75,7 +75,7 @@ The providers that can be used are:
75
75
  ###### Auth0 configuration:
76
76
 
77
77
  ```yaml
78
- lowdefy: 7.1.0
78
+ lowdefy: 7.4.0
79
79
  auth:
80
80
  providers:
81
81
  - id: auth0
@@ -94,7 +94,7 @@ In Auth0, the callback URL should be configured to `https://example.com/api/auth
94
94
  ###### GitHub configuration:
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.1.0
97
+ lowdefy: 7.4.0
98
98
  auth:
99
99
  providers:
100
100
  - id: github
@@ -28,7 +28,7 @@ The OpenIDConnectProvider can be used to authenticate with a OpenID Connect comp
28
28
  Usually only the `wellKnown`, `clientId` and `clientSecret` properties need to be configured:
29
29
 
30
30
  ```yaml
31
- lowdefy: 7.1.0
31
+ lowdefy: 7.4.0
32
32
  providers:
33
33
  - id: my_provider
34
34
  type: OpenIDConnectProvider
@@ -145,6 +145,8 @@ FAIL member saves a ticket
145
145
  action-error Request "save_ticket" failed in save.onClick with ServiceError. pages/tickets.yaml:88
146
146
  ```
147
147
 
148
+ When the dev server loses its web server, a request gets no answer and the journey fails with a `dev-server` line instead. That says nothing about the app: check the dev server log for a restart or crash, then run the journey again.
149
+
148
150
  Each error line gives its kind, its message and the config file and line it came from, when known. Fix the app in most cases. When the error is the outcome the app means, such as a unique index violation that a `catch` action shows as "already exists", either make it a user error in config (a `Throw` action is one), or assert it with `expect: { error: text }` straight after the interaction:
149
151
 
150
152
  ```yaml
@@ -33,7 +33,7 @@ Change the `lowdefy.yaml` to look like this:
33
33
 
34
34
  ```yaml
35
35
  name: lowdefy-project-template
36
- lowdefy: 7.1.0
36
+ lowdefy: 7.4.0
37
37
 
38
38
  pages:
39
39
  ################ -------- Copy from here -------- ################
@@ -18,7 +18,7 @@ In your `lowdefy.yaml` file, add the following:
18
18
 
19
19
  ```yaml
20
20
  name: lowdefy-project-template
21
- version: 7.1.0
21
+ version: 7.4.0
22
22
 
23
23
  ################ -------- Copy from here -------- ################
24
24
  connections:
@@ -51,7 +51,7 @@ In your `lowdefy.yaml` file, add the following:
51
51
 
52
52
  ```yaml
53
53
  name: lowdefy-project-template
54
- version: 7.1.0
54
+ version: 7.4.0
55
55
 
56
56
  connections:
57
57
  # ...
@@ -63,7 +63,7 @@ Made by a Lowdefy 🤖
63
63
  Open the `lowdefy.yaml` file using a text editor like [VS Code](https://code.visualstudio.com/download). The content of the file should look like this:
64
64
 
65
65
  ```yaml
66
- lowdefy: 7.1.0
66
+ lowdefy: 7.4.0
67
67
  name: Lowdefy starter
68
68
 
69
69
  pages:
@@ -11,7 +11,7 @@ For a login method to work you must configure **at least one mechanism** (`email
11
11
  A required signing secret, given as a `_secret` reference:
12
12
 
13
13
  ```yaml
14
- lowdefy: 7.1.0
14
+ lowdefy: 7.4.0
15
15
  auth:
16
16
  secret:
17
17
  _secret: BETTER_AUTH_SECRET
@@ -24,7 +24,7 @@ Also pin the app's canonical origin — the `url` of the current environment in
24
24
  Sessions, users, accounts and organizations are stored through an adapter:
25
25
 
26
26
  ```yaml
27
- lowdefy: 7.1.0
27
+ lowdefy: 7.4.0
28
28
  auth:
29
29
  database:
30
30
  id: auth_db
@@ -46,7 +46,7 @@ See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names fo
46
46
  - **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
47
47
 
48
48
  ```yaml
49
- lowdefy: 7.1.0
49
+ lowdefy: 7.4.0
50
50
  auth:
51
51
  emailAndPassword:
52
52
  enabled: true
@@ -58,7 +58,7 @@ auth:
58
58
  `auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
59
59
 
60
60
  ```yaml
61
- lowdefy: 7.1.0
61
+ lowdefy: 7.4.0
62
62
  auth:
63
63
  email:
64
64
  connectionId: email # an SMTP connection in connections[]
@@ -94,7 +94,7 @@ BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` po
94
94
  | `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.1.0
97
+ lowdefy: 7.4.0
98
98
  auth:
99
99
  authPages:
100
100
  signIn: /login
@@ -113,7 +113,7 @@ A verification email links to Better Auth's verify endpoint, which confirms the
113
113
  Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
114
114
 
115
115
  ```yaml
116
- lowdefy: 7.1.0
116
+ lowdefy: 7.4.0
117
117
  auth:
118
118
  magicLink:
119
119
  enabled: true
@@ -161,7 +161,7 @@ See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [
161
161
  Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
162
162
 
163
163
  ```yaml
164
- lowdefy: 7.1.0
164
+ lowdefy: 7.4.0
165
165
  auth:
166
166
  session:
167
167
  expiresIn: 43200 # 12 hours in seconds
@@ -177,7 +177,7 @@ auth:
177
177
  - **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
178
178
 
179
179
  ```yaml
180
- lowdefy: 7.1.0
180
+ lowdefy: 7.4.0
181
181
  auth:
182
182
  strategies:
183
183
  - id: service-key
@@ -231,7 +231,7 @@ Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
231
231
 
232
232
  ###### Configure a mock user for development
233
233
  ```yaml
234
- lowdefy: 7.1.0
234
+ lowdefy: 7.4.0
235
235
 
236
236
  auth:
237
237
  providers:
@@ -114,7 +114,7 @@ Scope, required permission, and target for every auth step. Permissions are chec
114
114
 
115
115
  | Step | Scope | Permission | Target | What it does |
116
116
  | ---- | ----- | ---------- | ------ | ------------ |
117
- | `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. |
117
+ | `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. Accept sets `contactId` only on a login with no contact link, and refuses one linked to a different contact. |
118
118
  | `CancelInvitation` | org | `invitation: [cancel]` | — | Cancel a pending invitation. |
119
119
  | `ListMembers` | org | `member: [list]` | — | List members of the organization (accepts `organizationSlug`). |
120
120
  | `RemoveMember` | org | `member: [delete]` | — | Remove a member from the organization. |
@@ -125,7 +125,7 @@ Scope, required permission, and target for every auth step. Permissions are chec
125
125
  | `UnsuspendMember` | org | `member: [suspend]` | — | Lift a suspension (`memberId`); the member keeps the roles they held. |
126
126
  | `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
127
127
  | `RevokeOrgMcpToken` | org | `member: [update]` | — | Switch off any [member token](/mcp-oauth#tokens-for-scripts) in the organization (`id`). |
128
- | `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy). Self-service save is exempt. |
128
+ | `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy) and profile. Self-service save is exempt. Does not write `contactId`, which only an accepted invitation sets. |
129
129
  | `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
130
130
  | `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
131
131
  | `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
@@ -55,7 +55,17 @@ An equivalent unique index you created yourself, under any name, is accepted. If
55
55
 
56
56
  ### Invitations for existing members
57
57
 
58
- An invitation is how someone joins an organization, never how a membership changes. Accepting an invitation into an organization you already belong to (you joined another way after it was sent) succeeds and marks the invitation accepted, but leaves your membership exactly as it is: the invitation's role, app roles and attributes are not applied, and no second membership is written. If your session had no active organization, the accepted organization becomes active. To change an existing membership, use the [auth steps](/auth-steps) (`UpdateMemberOrgRole`, `UpdateMemberRoles`, `UpdateMemberAttributes`), which check the caller's authority at the time of the change.
58
+ An invitation is how someone joins an organization, never how a membership changes. Accepting an invitation into an organization you already belong to (you joined another way after it was sent) succeeds and marks the invitation accepted, but leaves your membership exactly as it is: the invitation's role, app roles and attributes are not applied, and no second membership is written. If your session had no active organization, the accepted organization becomes active. The invitation's contact link is the exception: it belongs to the login, not the membership, so it follows the rules in [Invitations and the contact link](#invitations-and-the-contact-link). To change an existing membership, use the [auth steps](/auth-steps) (`UpdateMemberOrgRole`, `UpdateMemberRoles`, `UpdateMemberAttributes`), which check the caller's authority at the time of the change.
59
+
60
+ ### Invitations and the contact link
61
+
62
+ An invitation may carry a `contactId`: the link from the login to the app's record for this person, read as [`_user.contact_id`](/user-object). Apps compare it in author and access checks, so it is set once, by accepting an invitation:
63
+
64
+ - Accepting an invitation sets the link on a login that has none.
65
+ - An invitation with no `contactId`, or the same one the login already holds, leaves the link as it is.
66
+ - An invitation naming a different contact than the login holds is refused with the code `CONTACT_LINK_MISMATCH`. No membership is written and the invitation stays pending. The person accepting sees a short message with no ids; the server logs a warning (`invitation_contact_link_mismatch`) with the login, the invitation and both contact ids, so whoever runs the app can find the case.
67
+
68
+ The page that accepts should call `UpdateSession` after `AcceptInvitation`, so the browser's `_user` picks up the new link (and the new organization) straight away. No auth step changes the link after that: `UpdateUserProfile` does not write `contactId`. A wrong link is corrected in the data.
59
69
 
60
70
  ### Suspending a member
61
71
 
@@ -14,7 +14,7 @@ The 404 page (used to indicate that a requested page cannot be found) is always
14
14
 
15
15
  ###### List specific public pages and APIs:
16
16
  ```yaml
17
- lowdefy: 7.1.0
17
+ lowdefy: 7.4.0
18
18
  auth:
19
19
  pages:
20
20
  protected: true
@@ -31,7 +31,7 @@ auth:
31
31
 
32
32
  ###### List specific protected pages and APIs:
33
33
  ```yaml
34
- lowdefy: 7.1.0
34
+ lowdefy: 7.4.0
35
35
  auth:
36
36
  pages:
37
37
  public: true
@@ -47,7 +47,7 @@ auth:
47
47
 
48
48
  ###### Mixed configuration:
49
49
  ```yaml
50
- lowdefy: 7.1.0
50
+ lowdefy: 7.4.0
51
51
  auth:
52
52
  # Protect specific pages while keeping most public
53
53
  pages:
@@ -75,7 +75,7 @@ Exact page IDs still work: `home`, `team-users/users-list`.
75
75
 
76
76
  ###### Wildcard pattern example:
77
77
  ```yaml
78
- lowdefy: 7.1.0
78
+ lowdefy: 7.4.0
79
79
  auth:
80
80
  pages:
81
81
  protected: true
@@ -7,7 +7,7 @@ Roles are read from the `roles` field on the [user object](/user-object) — an
7
7
  Declare the role names your app uses in `auth.roles` (id, optional label and description) so tooling can list them:
8
8
 
9
9
  ```yaml
10
- lowdefy: 7.1.0
10
+ lowdefy: 7.4.0
11
11
  auth:
12
12
  roles:
13
13
  - id: user-admin
@@ -24,7 +24,7 @@ Similarly, the API endpoints that are protected by roles are configured in the `
24
24
 
25
25
  ###### Protect pages and API endpoints using roles:
26
26
  ```yaml
27
- lowdefy: 7.1.0
27
+ lowdefy: 7.4.0
28
28
  auth:
29
29
  pages:
30
30
  public: true
@@ -20,7 +20,7 @@ Its shape is **fixed**. Unlike the old provider-claim mapping, there is no `user
20
20
  | `two_factor_enrolled` | session | Whether the caller holds a factor satisfying `auth.twoFactor.required`. |
21
21
  | `auth_method` | strategy, mcp | How the caller authenticated — the strategy id, or `'mcp'` for an [assistant](/mcp-oauth). Absent on browser sessions. |
22
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. |
23
+ | `contact_id` | session | Link to the app's canonical record for this person, when one exists. Set once, when the person accepts an invitation that carries `contactId`; no auth step changes it. |
24
24
 
25
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
26
 
@@ -5,7 +5,7 @@ A `Channel` websocket relays messages between clients: any subscriber can publis
5
5
  ## A Minimal Chat
6
6
 
7
7
  ```yaml
8
- lowdefy: 7.1.0
8
+ lowdefy: 7.4.0
9
9
 
10
10
  websockets:
11
11
  - id: team_chat
@@ -97,7 +97,7 @@ Page `subscriptions` cover most cases, but the actions give dynamic control —
97
97
 
98
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
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.
100
+ - Connections close when a function reaches its `maxDuration`. The server closes each connection 5 seconds before then (at half the limit when it is under 10 seconds), and the Lowdefy client reconnects and resubscribes at once. Changes a source publishes during the reconnect are not delivered; raise `maxDuration` to reduce reconnect frequency on websocket-heavy apps.
101
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
102
 
103
103
  ### Self-Hosted
@@ -52,7 +52,32 @@ events:
52
52
  _event: messages # array of message payloads in this batch
53
53
  ```
54
54
 
55
- `onSubscribe` fires when the server acknowledges the subscription (including after an automatic reconnect). `onError` fires with `_event: message` when the channel errors.
55
+ `onSubscribe` fires when the server acknowledges the subscription, again after an automatic reconnect, and again when the channel's source is back after an outage. `onError` fires with `_event: message` when the channel errors.
56
+
57
+ ## When the Source Fails
58
+
59
+ A channel's source can fail while pages are subscribed, for example when the database is unreachable. The page stays subscribed and the server restarts the source for as long as anyone is subscribed: 1 second after the failure, then doubling up to once a minute.
60
+
61
+ - During the outage, each failed start sends the page an error: `onError` fires and `_websocket: <id>.error` holds the message. No messages arrive, and the source misses whatever changes in the meantime.
62
+ - When the source is listening again, `onSubscribe` fires, `error` returns to `null` and messages flow again.
63
+
64
+ So a page that refetches in `onSubscribe` as well as in `onMessage` also catches up after an outage and after a reconnect:
65
+
66
+ ```yaml
67
+ subscriptions:
68
+ - websocketId: order_updates
69
+ events:
70
+ onSubscribe:
71
+ - id: refetch
72
+ type: Request
73
+ params: get_orders
74
+ onMessage:
75
+ - id: refetch
76
+ type: Request
77
+ params: get_orders
78
+ ```
79
+
80
+ The server reports the outage's first failure as an error, to the log and Sentry, and each further failed restart as a warning.
56
81
 
57
82
  ## Reading Channel State with `_websocket`
58
83
 
@@ -9,7 +9,7 @@ Websockets work identically on a self-hosted Node.js server and on Vercel, where
9
9
  A channel and a page subscription — this page shows a live tick counter:
10
10
 
11
11
  ```yaml
12
- lowdefy: 7.1.0
12
+ lowdefy: 7.4.0
13
13
 
14
14
  websockets:
15
15
  - id: ticker
@@ -38,11 +38,12 @@ When the page loads, the client opens a websocket connection, subscribes to `tic
38
38
 
39
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
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.
41
+ 3. The server authorizes the subscription against the channel's `auth` config and, when the websocket has a `check`, calls the check endpoint as the subscriber. It 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
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
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
+ 6. If the source fails, for example during a database outage, the server restarts it for as long as the channel has subscribers, up to once a minute. Subscribers get an `onError` for each failed start, and `onSubscribe` when the source is listening again, so the page can refetch what it missed. See [When the Source Fails](/websocket-subscriptions#when-the-source-fails).
44
45
 
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
+ 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. On Vercel the server closes each connection 5 seconds before the function's `maxDuration`, so the client reconnects at once instead of noticing the dead connection about 10 seconds late.
46
47
 
47
48
  ## Websocket Definition
48
49
 
@@ -52,6 +53,9 @@ Websockets are defined in the top-level `websockets` array:
52
53
  - `type: string`: __Required__ - The websocket type. `Channel` and `Interval` ship with Lowdefy; connection plugins provide types like [`MongoDBChangeStream`](/MongoDB).
53
54
  - `connectionId: string`: The `id` of a [connection](/connections) for connection-backed types.
54
55
  - `properties: object`: Settings for the type. __Operators are evaluated server-side per subscription__ — `_secret`, `_user`, and `_payload` are available.
56
+ - `check: object`: An [API endpoint](/api-endpoints) that decides whether this caller may hear, or publish to, the channel. It runs on every subscribe and publish, and once a minute while a subscription stays open. See [Securing Channels](#securing-channels).
57
+ - `endpointId: string`: __Required__ - The `Api` or `InternalApi` endpoint to call. The build fails when the app has no endpoint with this id.
58
+ - `payload: object`: The payload sent to the endpoint, evaluated server-side with `_payload`, `_user` and `_secret`. Defaults to the subscription payload.
55
59
 
56
60
  ###### A user-specific channel:
57
61
  ```yaml
@@ -95,6 +99,55 @@ Unauthorized subscriptions receive the same response as subscriptions to channel
95
99
 
96
100
  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
101
 
102
+ ### Checking access to a record
103
+
104
+ Roles decide who may hear a channel at all. A channel whose payload names a record, such as the events on one ticket, also needs to know whether this subscriber may see that ticket. A pipeline filter can not answer that, since it only sees the change event, so give the websocket a `check`: an endpoint that answers from your own data.
105
+
106
+ ```yaml
107
+ api:
108
+ - id: can-view-ticket
109
+ type: InternalApi
110
+ routine:
111
+ - id: ticket
112
+ type: MongoDBFindOne
113
+ connectionId: tickets
114
+ properties:
115
+ query:
116
+ _id:
117
+ _payload: ticket_id
118
+ $or:
119
+ - author_id:
120
+ _user: id
121
+ - subscriber_ids:
122
+ _user: id
123
+ - :return:
124
+ _ne:
125
+ - _step: ticket
126
+ - null
127
+
128
+ websockets:
129
+ - id: ticket_events
130
+ type: MongoDBChangeStream
131
+ connectionId: events
132
+ check:
133
+ endpointId: can-view-ticket
134
+ payload:
135
+ ticket_id:
136
+ _payload: ticket_id
137
+ properties:
138
+ pipeline:
139
+ - $match:
140
+ fullDocument.ticket_id:
141
+ _payload: ticket_id
142
+ ```
143
+
144
+ - The endpoint runs as the subscriber, with the same `_user`, roles and organization as a request from that session.
145
+ - Only a return value of exactly `true` lets the subscription continue. Any other value, an error, or an endpoint the subscriber may not call refuses it with the same response as a channel that does not exist. An error in the check or the endpoint is also logged.
146
+ - The check runs on every subscribe: the first one, the resubscribe after a reconnect, and a [`Subscribe`](/websocket-publish) with a new payload. It runs again at least once a minute while a subscription stays open, so revoking access ends a running subscription within a minute: the subscription gets the refusal as an error and no further messages. Each open subscription calls the endpoint once a minute, so keep the check cheap.
147
+ - The check is not part of the channel identity. Subscribers whose evaluated `properties` match still share one running source, and each is checked on their own.
148
+ - A publish is checked too, with an empty payload, since a publish evaluates the websocket `properties` without one. A check that reads the payload therefore refuses every publish, and a check that does not, such as membership of a group, decides who may publish as well as who may hear.
149
+ - A module websocket names its own endpoint with [`_module.endpointId`](/_module).
150
+
98
151
  ## What's Next
99
152
 
100
153
  - [Page Subscriptions](/websocket-subscriptions) — Subscribe pages to channels, handle messages with events, and read channel state with `_websocket`.
package/index.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "7.1.0",
2
+ "version": "7.4.0",
3
3
  "docs": [
4
4
  {
5
5
  "slug": "learn/introduction",
@@ -3113,14 +3113,14 @@
3113
3113
  "concepts/advanced/dynamic-page-content.yaml",
3114
3114
  "version.yaml"
3115
3115
  ],
3116
- "hash": "acdeb0d9965fef5e604324667440865b8bd7c58aca4bc09ab7d0b8aa51b67f16"
3116
+ "hash": "80eac384292186530102446d68826d1c0be59dc66241c8dfc44e6e19b27035c3"
3117
3117
  },
3118
3118
  "concepts/ai-agent-docs": {
3119
3119
  "files": [
3120
3120
  "concepts/advanced/ai-agent-docs.md",
3121
3121
  "concepts/advanced/ai-agent-docs.yaml"
3122
3122
  ],
3123
- "hash": "1873730b81d22282eeec3ba15ea034117cf501c67c621a3bacf66ed89b8057cf"
3123
+ "hash": "67982e5e01dfa11e4591ba3569a8bf5df6f97f7c0f6557dff3e3bca209600e69"
3124
3124
  },
3125
3125
  "agents/agents-introduction": {
3126
3126
  "files": [
@@ -3133,7 +3133,7 @@
3133
3133
  "files": [
3134
3134
  "agents/agent-properties.yaml"
3135
3135
  ],
3136
- "hash": "d3f70ea19d78c84002dc38195d41ba9c0c0153fb6380936861297cf49728240c"
3136
+ "hash": "5f6778173d5ce47f50b5098ec59859916da99e953ac89d84cecebdaacb7c2304"
3137
3137
  },
3138
3138
  "agents/agent-endpoint-tools": {
3139
3139
  "files": [
@@ -3157,7 +3157,7 @@
3157
3157
  "files": [
3158
3158
  "agents/server-hooks.yaml"
3159
3159
  ],
3160
- "hash": "8631ab81653d1c6395476e5fe4f042dd437087e2b8498a17e9a216ec253bb6a9"
3160
+ "hash": "9a4b2d0c867bbb31e6b9d2936354a6aa786187b0f33826ff83eca73e0429f20b"
3161
3161
  },
3162
3162
  "agents/agentchat": {
3163
3163
  "files": [
@@ -3176,21 +3176,21 @@
3176
3176
  "version.yaml",
3177
3177
  "websockets/introduction.yaml"
3178
3178
  ],
3179
- "hash": "9a3abf01a934df3610372700d1f888e1558e5b5287209b1691ffed1d1db504ec"
3179
+ "hash": "4cb3dcf88d3a35109f92c6d6c1fcb7ca6d4257f291f659014e378c90a760d4a0"
3180
3180
  },
3181
3181
  "websockets/websocket-subscriptions": {
3182
3182
  "files": [
3183
3183
  "version.yaml",
3184
3184
  "websockets/subscriptions.yaml"
3185
3185
  ],
3186
- "hash": "808690ae34a7f630f8ca360d60990fd24bfac50851f091a43f1d2b22685ac204"
3186
+ "hash": "5ac50cfa0c54160632bf1de3b2a8ca95adb32232ca5252431e0d1fe15b273870"
3187
3187
  },
3188
3188
  "websockets/websocket-publish": {
3189
3189
  "files": [
3190
3190
  "version.yaml",
3191
3191
  "websockets/publish.yaml"
3192
3192
  ],
3193
- "hash": "e399a5176ea0fe3db88dd1ca3425279b4687b193e27308f8159acb6da65c3720"
3193
+ "hash": "e01f81f52a3bff3493e3f31b2a43fc9e9cb93a13bb3821e5befe9666100ec1fe"
3194
3194
  },
3195
3195
  "deployment/docker": {
3196
3196
  "files": [
@@ -3208,7 +3208,7 @@
3208
3208
  "files": [
3209
3209
  "deployment/vercel.yaml"
3210
3210
  ],
3211
- "hash": "42dcf611ce291c27117b550a9050dc09c7f2a9e096c872efacd54499955a0bc0"
3211
+ "hash": "a3d55236b70520fe05204231204e92c0e192e2d0588f9fc8a40c1711c5fc776c"
3212
3212
  },
3213
3213
  "deployment/deployment-environments": {
3214
3214
  "files": [
@@ -3301,13 +3301,13 @@
3301
3301
  "files": [
3302
3302
  "users/organizations.yaml"
3303
3303
  ],
3304
- "hash": "be6003a3d5dce08abc7e74e6766c5031d0710b73fc24204b8bd9a694bcdbaed8"
3304
+ "hash": "a799ed56573f37a7374538657a5c523e8b0a3bd3e35dabed7492bf705ca26873"
3305
3305
  },
3306
3306
  "user-authentication/auth-steps": {
3307
3307
  "files": [
3308
3308
  "users/auth-steps.yaml"
3309
3309
  ],
3310
- "hash": "46c67f8c9ecf56a5f18ba4f109bb011beb956daa90a0844405ab7cb396e1cf4d"
3310
+ "hash": "6a3fd58bb355b46f33246b84c6993d3dda0d60495bd56d94384f505873888903"
3311
3311
  },
3312
3312
  "user-authentication/mcp-oauth": {
3313
3313
  "files": [
@@ -3319,7 +3319,7 @@
3319
3319
  "files": [
3320
3320
  "users/user-object.yaml"
3321
3321
  ],
3322
- "hash": "8abd5b2a058647962e6bf8ea6e0a2deb64b369beb2a1bff8fe5aa79cb03dd06a"
3322
+ "hash": "c56c01fd7f124bce78c8c920a96e09010fffe98e1b50e33638a277bfead730f6"
3323
3323
  },
3324
3324
  "user-authentication/auth-configuration": {
3325
3325
  "files": [
@@ -3361,7 +3361,7 @@
3361
3361
  "testing/config-tests.md",
3362
3362
  "testing/config-tests.yaml"
3363
3363
  ],
3364
- "hash": "94fd498047ff9b857bc2ac3d2c8832f39e83beeeff6fb107a950635278c96eb8"
3364
+ "hash": "954e1aaacaf6abe246a4574fad5dee7e54b947b48652133da667e592e678f122"
3365
3365
  },
3366
3366
  "testing/journey-data-sets": {
3367
3367
  "files": [
@@ -3709,7 +3709,7 @@
3709
3709
  "blocks/input/RatingSlider.yaml",
3710
3710
  "templates/blocks/gallery.yaml.njk"
3711
3711
  ],
3712
- "hash": "9d27407b34aa8454525cb37e210a879f1e324fad8c777394f0cfc735c7a3f78c"
3712
+ "hash": "f52c19b663d984b6d0c2d517603d3a8b21fd925563a9eba96790f6687b012dc5"
3713
3713
  },
3714
3714
  "input-blocks/segmentedselector": {
3715
3715
  "files": [
@@ -4874,7 +4874,7 @@
4874
4874
  "connections/AxiosHttp.yaml",
4875
4875
  "version.yaml"
4876
4876
  ],
4877
- "hash": "5ce8841e4e2896c9f1aadbbe698fc218b75348a55d6a55f47245065aac3923d0"
4877
+ "hash": "6dc718d4c360b78d0cc5d50b0af63b3502185b68a47defa206185b51e8f7597a"
4878
4878
  },
4879
4879
  "connections/elasticsearch": {
4880
4880
  "files": [
@@ -5293,7 +5293,7 @@
5293
5293
  "operators/_api.yaml",
5294
5294
  "templates/operators.yaml.njk"
5295
5295
  ],
5296
- "hash": "2194aa8b560f6c3789f57e591c7d91dc1a0c34099ba968e69397d993e4d34089"
5296
+ "hash": "8181db4d7542c90ad8cc2be7db4eb94f545a8361f32a001aa7339bff336ad268"
5297
5297
  },
5298
5298
  "operators/_app": {
5299
5299
  "files": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lowdefy/docs-content",
3
- "version": "7.2.0",
3
+ "version": "7.4.0",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Lowdefy documentation extracted as markdown for AI coding agents.",
6
6
  "homepage": "https://lowdefy.com",
@@ -36,7 +36,7 @@
36
36
  "scripts/*"
37
37
  ],
38
38
  "dependencies": {
39
- "@lowdefy/nunjucks": "7.2.0"
39
+ "@lowdefy/nunjucks": "7.4.0"
40
40
  },
41
41
  "publishConfig": {
42
42
  "access": "public"